Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(authz): close the enforcement-gap in the per-project authz design (#708)

AkitaOnRailsa38d3b3a5470
diff --git a/docs/design-per-project-authz.md b/docs/design-per-project-authz.md
index 748ae4ef..d5acc6b9 100644
--- a/docs/design-per-project-authz.md
+++ b/docs/design-per-project-authz.md
@@ -40,7 +40,7 @@ so existing open deployments do not silently lock out on upgrade.
(above + write_page/consolidate/handoff/message/delete). `admin` stays global/root as
today (project-admin is out of scope for v1).
-### Schema (new migration, next free V on `release/2.3`)
+### Schema (new migration, next free V on `release/2.5`)
```sql
CREATE TABLE project_grants (
workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
@@ -70,6 +70,46 @@ invariant-#16 hazard: the grant gate is an *authorization* check that returns
allow/deny; it is not an `OwnerFilter` on page rows. A team with grants still sees the
same shared pages — grants gate entry to the project, not row visibility within it.
+### Enforcement gaps beyond the choke point (must close before enforcing)
+
+The single `authorize_project` choke point at scope resolution is **necessary but not
+sufficient**: two read classes never resolve a single `(workspace, project)` scope, so
+they bypass the gate entirely. Both must be handled or a `restricted` project leaks.
+
+1. **Unscoped / cross-project reads.** `memory_query(global=true)`, global `memory_recent`,
+ and cross-project web search fan out across every project and never call the scope
+ resolver, so `authorize_project` is never reached. These must filter the **result set
+ by the caller's readable projects inside SQL, before `LIMIT`** — not after. Post-filtering
+ a materialized page would still leak the *existence and count* of hits in projects the
+ caller cannot read (and could starve the visible results under the limit). Concretely:
+ join candidate rows against `project_grants` (+ `access_mode='open'` + creator + root)
+ and apply the predicate in the same query that orders and limits. A caller with no
+ grants sees exactly the open projects, as today.
+2. **Raw-id entry points.** Several paths take a `session_id` / `run_id` / `page_id`
+ directly and resolve their project *from the row*, bypassing scope resolution by
+ construction: consolidation-by-session-id, managed-run routes, SessionStart handoff
+ delivery, and `ReaderPool::page_evidence_counts(page_ids)`. Each must resolve the id →
+ its `(workspace, project)` and then call `authorize_project` before returning content —
+ an unauthorized id is `NotFound`/`Forbidden`, never a silent read. Audit every
+ entry point that accepts a bare id against this rule; a new one that skips it silently
+ reopens the hole while every scoped test still passes.
+
+Structural enforcement (recommended): make the unguarded lookups crate-private so the
+compiler forces new call sites through the guarded resolver + `authorize_project`, the
+same way `ScopeResolver` already funnels scoped access.
+
+### Ship inert, and never fail closed on missing rows
+
+The feature must be a no-op until an operator opts in, and it must not turn a resolution
+gap into a lockout (the #678 dead-end lesson: an unresolved pointer means degrade, not
+refuse). Concretely: an empty `project_grants` table plus `access_mode DEFAULT 'open'`
+means every existing project stays open; enabling `restricted` on a project with **zero
+grants still admits root and the project creator** (never "locked out of my own data");
+a startup that cannot read the grants table (older schema mid-migration) degrades to
+`open` with a loud warning rather than denying every read; and single-user / loopback
+(`distinguishes_operators()` false) skips the gate entirely. Enforcement is gated on
+both the server distinguishing operators **and** the specific project being `restricted`.
+
### Management surface (root-only, `/admin/*`)
`ai-memory user grant --user alice --workspace w --project p --level write` and
`… revoke …`, plus `ai-memory project access --workspace w --project p --mode restricted|open`.
@@ -102,4 +142,16 @@ abstractions. Those can layer on the `project_grants` table later.
Table-driven authorization tests (root / granted-read / granted-write / no-grant /
anonymous × open/restricted projects), a multi-session integration test proving a
non-granted user is refused a restricted project while a granted teammate is admitted
-(the invariant-#16 shape that unit tests miss), and a migration idempotency test.
+(the invariant-#16 shape that unit tests miss), and a migration idempotency test. Plus,
+for the two bypass classes above:
+- an **unscoped-read leak test**: `memory_query(global=true)` / global `recent` / web
+ search by a caller with no grant returns hits only from open projects and never
+ reveals the count or existence of hits in a `restricted` project (the filter is
+ applied before `LIMIT`, verified with enough rows that a naive post-filter would
+ under-fill the visible window);
+- a **raw-id authz test** per bare-id entry point (session/run/page id, and
+ `page_evidence_counts`): an id belonging to a `restricted` project the caller lacks a
+ grant for returns `Forbidden`/`NotFound`, not content;
+- a **ship-inert test**: an empty grants table, and a `restricted` project with zero
+ grants, both still admit root and the creator; a caller on an `open` project is
+ unaffected.