Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: per-project authorization design proposal (#708)
AkitaOnRailsb773c6c87325
diff --git a/docs/design-per-project-authz.md b/docs/design-per-project-authz.mdnew file mode 100644index 00000000..748ae4ef--- /dev/null+++ b/docs/design-per-project-authz.md@@ -0,0 +1,105 @@+# Design proposal: per-project authorization for multi-user servers (#708)++**Status: proposal for review — not implemented.** This is the design pass promised+on #708 before any code lands. It changes a security boundary, so it is deliberately+separated from implementation.++## Problem++On a multi-user server (one where DB users exist, or a trusted identity proxy is+configured — `deployment_distinguishes_operators()` is true), a DB-user token attributes+writes to that user but does **not** scope which projects the user may read or write.+Any authenticated non-root caller can resolve any `(workspace, project)` and read or+write it. Attribution exists; authorization does not. `/admin/*` is already root-only,+and `OwnerFilter` isolates *handoffs* per operator, but pages/observations/search are+project-scoped only, never user-scoped.++This is fine for the default posture (loopback, single operator) and is why it has not+bitten single-user installs. It is a real gap for a shared server hosting several teams.++## Current model (what exists today)++- **Auth ladder** (`ai-memory-core::actor`): `AuthLevel` = `Anonymous` / `User` / `Root`;+ `Capability` = `Admin` / `UserManagement` / `NormalRead` / `NormalWrite` /+ `SkipAdmissionChain`. `authorize(capability, distinguishes_operators)` gates them.+ `NormalRead`/`NormalWrite` are currently granted to everyone (no project dimension).+- **Identity**: `IdentityKey` (storage-key form `user:alice`, `oidc:…`); `ActorContext`+ carries the resolved user. DB users live in the `users` table (token-hash auth).+- **Scope**: `ScopeResolver` resolves `(workspace_id, project_id)`; reads use no-create+ lookups and fail closed on missing scope. `OwnerFilter` (pages shared, batons owned)+ applies to handoffs only — invariant #16 forbids it becoming a page-read filter.++## Proposed model++Introduce an explicit, additive **project grant** keyed by `(user, workspace, project,+level)`. Deny-by-default only when a project has *declared* itself access-controlled,+so existing open deployments do not silently lock out on upgrade.++### Grant levels+`read` (query/read pages/observations/status/briefing in that project) and `write`+(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`)+```sql+CREATE TABLE project_grants (+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,+ user_id BLOB NOT NULL REFERENCES users(id) ON DELETE CASCADE,+ level TEXT NOT NULL CHECK (level IN ('read','write')),+ granted_by BLOB REFERENCES users(id) ON DELETE SET NULL,+ granted_at INTEGER NOT NULL,+ PRIMARY KEY (workspace_id, project_id, user_id)+) WITHOUT ROWID;+```+A per-project flag decides enforcement: a project row gains+`access_mode TEXT CHECK (access_mode IN ('open','restricted')) DEFAULT 'open'`. `open`+= today's behavior (any authenticated user). `restricted` = only root, the project+creator, and users with a matching grant.++### Enforcement points (fail closed)+A single choke point, `authorize_project(actor, ws, proj, need: read|write)`, consulted by:+- `ScopeResolver` read/write resolution (the one place every MCP/API/web path already+ funnels through), and+- the writer actor as defense in depth for destructive ops.++`open` project → allow (current behavior). `restricted` → allow root; allow a `write`+grant for writes and a `read`/`write` grant for reads; else `AuthzError::Forbidden`.+Anonymous is denied on any restricted project. This must **not** reintroduce the+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.++### 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`.+REST under `/admin/projects/*` and `/admin/users/*`, mirroring existing admin routes.++### Migration / rollout+Additive: every existing project defaults to `access_mode='open'`, so nothing changes+for current deployments on upgrade. An operator opts a project into `restricted`+explicitly, then grants users. Single-user/loopback is unaffected (no DB users →+`distinguishes_operators()` false → gate is a no-op).++## Open questions for review+1. **Default for NEW projects on a multi-user server**: keep `open` (least surprise) or+ `restricted` to the creator (secure-by-default)? Proposal: `open`, with a server+ config `[auth] new_projects_restricted = true` to flip it — so secure-by-default is+ available without breaking the common case.+2. **Global scope (`_global`)**: read-open to all authenticated users (it is shared+ preference context), never restricted. Writes stay as today.+3. **Interaction with cross-project messaging (V64)**: a `restricted` recipient inbox+ should require the sender to hold a `write` grant on the recipient project, or the+ message is refused — otherwise grants are bypassable via the mailbox. This ties #708+ to the messaging feature and is why it must be designed, not bolted on.+4. **Handoff `OwnerFilter`**: unchanged; grants and owner-batons are orthogonal.++## Non-goals (v1)+Per-project *admin* delegation, row-level ACLs, time-boxed grants, group/role+abstractions. Those can layer on the `project_grants` table later.++## Verification plan (when approved)+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.