[Josh Duffney (duffney)]

Summary

Project membership RBAC, stacked on the service-auth / run-token layer (#1558). This PR is #1532 rebased onto #1558, plus one commit that wires RBAC enforcement to #1558's run and service principals. Refs #1557.

Stack: main ← #1531 ← #1558 (service auth / run tokens) ← this PR.

Fallback: #1532 (stacked directly on #1531) is unchanged and stays the fallback if the run-token approach in #1558 is rejected.

Commits:

Commit	Description
54718a4	Add project membership RBAC and operator-managed access (#1532 d7759c42, conflicts resolved against #1558)
33abaf3	fix: wait for access story navigation before selecting projects (#1532 a248e76d)
98ff677	fix: scope AI prompt context lookups to the authorized project (#1532 b7439535)
189f8f3	feat(api): authorize run-token and service-key callers (new)
d3d933a	test(api): cover run-token and service-key authorization (new)
7989ceb	docs: describe run-token and service-key authorization (new)

Conflict resolution (cherry-picks)

• auth/types.ts: Request keeps both principal? (feat: authenticate service-to-API calls (run token + service keys) #1558) and authorizedProjectId? (feat: add project membership RBAC and administration #1532).
• index.ts: the auth middleware keeps feat: add project membership RBAC and administration #1532's getProvider: () => authEnabled ? authProvider : null and feat: authenticate service-to-API calls (run token + service keys) #1558's run-token / service-key verifiers.
• openapi/api-route.ts: feat: add project membership RBAC and administration #1532's policy/security default and feat: authenticate service-to-API calls (run token + service keys) #1558's x-scope-run-token extension both apply.
• website/src/openapi/scope-openapi.json: regenerated.

Guard wiring (apps/api/src/auth/authorization.ts)

decide() branches on req.principal, which #1558 sets for run and service callers. Those callers have req.user = ANONYMOUS_USER and no req.auth.

Run principal

• Allowed only on routes declared runToken: true (14 GET routes), only for GET/HEAD, and only when the route policy is project. Otherwise it returns 403 run_token_not_allowed.
• The project is resolved the same way as for users (query, point document, requestId, references). It must equal the run's project and must not be deleted. Otherwise it returns 404 not_found, the same non-disclosing contract a non-member user gets.
• On success, req.authorizedProjectId is set.

Service principal

• Allowed only on routes granted by its scopes:
  • agents:read: GET/HEAD /api/v1/agents
  • agents:register: POST /api/v1/agents and /api/v1/agents/:id/versions
  • models:sync: POST /api/v1/models/sync
• Anything else returns 403 insufficient_scope.

Other changes

• Non-user principals skip the IdP JWT exp lease parse. Their lease is the normal authorization budget, and their credential lifetime is enforced by feat: authenticate service-to-API calls (run token + service keys) #1558's verifiers.
• currentUser() rejects non-user principals (403 user_required), so user-only flows never treat a run or service caller as a user.
• The global /api/v1 gate admits authenticated principals.
• apiRoute passes { runToken } to guard(), including stream revalidation.
• User principals keep feat: add project membership RBAC and administration #1532's behavior unchanged.

Known gap

The post-processor's /reports/trigger call and the report-generator tools don't send run tokens yet. Report generation is disabled by policy in this stack, so these paths aren't exercised. They are left for a follow-up.

Demos

N/A. This is API authorization behavior; no Portal/CLI UI change beyond #1532's.

Before

N/A

After

N/A

Testing

Commands and results:

• pnpm exec vitest run apps/api packages/shared apps/judge packages/model-scanning scripts apps/workers: passed (148 files, 2458 tests).
• pnpm exec vitest run apps/cli apps/portal: passed. The full unit set across api, shared, judge, model-scanning, scripts, workers, cli and portal was 251 files and 3499 tests.
• Integration (isolated Mongo/Redis): passed (6 files, 61 tests). Command:

  AUTH_TEST_MONGO_URI=… AUTH_TEST_REDIS_PORT=… pnpm exec vitest run --config vitest.integration.config.ts apps/api/src/auth/ apps/api/src/routes/project-membership.integration.test.ts apps/api/src/routes/task-prompts.integration.test.ts
  

  • This includes the new caller-authorization.integration.test.ts. 5 of its 7 tests fail without the guard-wiring commit.
• Typecheck passed for:
  • apps/api, apps/judge, packages/shared, apps/cli, packages/model-scanning (tsc --noEmit)
  • Portal (pnpm --filter portal exec tsc -b)
  • workers, except coder-acp-copilot-windows, which fails only because a sibling package's dist isn't built locally. That is unrelated to this change.
• OpenAPI snapshot regenerated (website/src/openapi/scope-openapi.json).
• Lint: not run (eslint is not installed in this workspace).

Local end-to-end (Docker Compose, SCOPE_AUTH_ENABLED=true, entra-local, isolated port offset/DB):

Setup:

• Service keys were set for register-agents and model-scanner.
• Admin was bootstrapped with operator-access.js bootstrap-admin (preview, then --apply).
• Two projects, X and Y, were created.

Service and run callers:

• ✅ register-agents exited 0 and registered both agents and their dev versions.
• ✅ model-scanner-copilot exited 0 (+38 models synced).
• ✅ A run submitted in project X completed with outcome succeeded (1/1 criteria passed).
  • The worker and judge used the run token; the judge fetched criteria with it.
  • The worker, judge, post-processor, scheduler, report-generator, scanner and register-agents logs had no 401/403.
  • Report generation is disabled by policy, so no report was produced.
• ✅ Service key out of scope → 403 insufficient_scope:
  • register-agents on GET /agents, POST /models/sync and GET /criteria
  • model-scanner on GET /criteria
• ✅ Service key with a wrong value → 401 invalid_service_key.
• ✅ Service headers sent together with a bearer → 400 ambiguous_credentials.

Run token for project X (minted for a separate synthetic processing request):

• ✅ Flagged GET in X (/criteria, /criteria/:id) → 200.
• ✅ Flagged GET for project Y (/criteria?projectId=Y, /criteria/<Y criterion>?projectId=Y) → 404.
• ✅ Non-flagged GETs (/requests, /projects) and POST /criteria → 403 run_token_not_allowed.
• ✅ /users/me → 401.
• ✅ Lifecycle: older than max age → 401 run_token_expired; run no longer processing → 401 run_not_active; tampered token → 401 invalid_run_token.

User principals:

• ✅ A user who isn't a member of X gets 404 for both reading and submitting in X; members are unaffected.

Not verified end to end:

• The post-processor /reports/trigger and report-generator run-token paths (see known gap).
• The judge default model was overridden locally to one available to the test account.

Documentation and compatibility

• docs/architecture/auth-rbac.md now has a new subsection, "Authorization of run and service callers" (allowed routes, project matching, status codes, lease handling). It also updates the internal-caller cutover table and the release-gate test list.
• Compatibility: same as feat: add project membership RBAC and administration #1532 plus feat: authenticate service-to-API calls (run token + service keys) #1558. With auth disabled, behavior is unchanged. With auth enabled, run and service callers are now limited to the routes described above.

Checklist

• If Portal features changed, keep CLI capabilities in sync. (Unchanged from feat: add project membership RBAC and administration #1532.)
• If Portal components changed, update their Storybook stories. (Unchanged from feat: add project membership RBAC and administration #1532.)
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. (feat: add project membership RBAC and administration #1532's 031-create-project-memberships, unchanged.)
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. N/A: no dependency changes.
• Video showing the behavior before the suggested change. N/A
• Video showing the behavior after the suggested change. N/A