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.mdindex 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 astoday (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`)```sqlCREATE 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 returnsallow/deny; it is not an `OwnerFilter` on page rows. A team with grants still sees thesame 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 anon-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.