[Josh Duffney (duffney)]

Summary

Authenticates service-to-API calls. Authentication only: route-level authorization (RBAC v2) will be stacked on top of this PR.

Alternative stack: main ← #1531 ← this PR ← RBAC v2 (next). It is an alternative to #1532. The existing stack #1531 ← #1532 is unchanged and remains the fallback.

Refs #1557

Run tokens

• A worker mints an opaque scope_rt_<requestId>_<secret><checksum> token when it claims a run. The secret is 256 bits; the checksum is CRC-32.
• Only a SHA-256 digest is stored, written atomically with the claim as run.tokenHash. The worker's terminal writes $unset it.
• Worker API clients send the token as a bearer: MCP servers, skills, extensions, resources, prompts, codebases and judge.
• The judge forwards the token to a criteria provider built for each evaluation.
• The API accepts the token only while all of these hold:
  • the run is processing;
  • the digest matches (constant-time compare);
  • the run is within RUN_TOKEN_MAX_AGE_MS.
• Otherwise the API returns 401.
• 14 worker read routes carry metadata-only runToken: true (exposed as x-scope-run-token in OpenAPI).
• run.tokenHash is removed from all run responses and history.

Per-service keys

• register-agents and the model scanners send X-Service-Name and X-Internal-Key, but only when SCOPE_INTERNAL_API_KEY is set.
• The API reads its keys from INTERNAL_API_KEY_REGISTER_AGENTS and INTERNAL_API_KEY_MODEL_SCANNER. Keys must be at least 32 characters and are compared in constant time.
• Missing configuration or a wrong key fails closed (401).
• Scopes are attached to the caller but not yet enforced; enforcement arrives with RBAC v2.

Caller identity

• The middleware attaches a separate req.principal (user | run | service).
• req.auth and req.user keep their existing semantics. Run and service callers get the anonymous user and no req.auth.
• Requests without a token behave exactly as before.

Implementation choices

• Ambiguous credentials: service headers sent together with Authorization return 400 ambiguous_credentials.
• Auth disabled: when IdP auth is disabled, credentials are ignored, preserving existing behavior.
• Token storage: run tokens are held in memory per claim and cleared in a finally block.
• register-agents key: the script passes its key to curl through a private header file (umask 077, removed on exit).
• Model-scanner scopes: agents:read, agents:register, models:sync.
• Follow-ups: post-run callers (post-processor report trigger, report-generator tools) don't send a run token yet.
• Deployment: Compose is wired; Kubernetes manifests and key provisioning live outside this repository.

Demos

N/A: no Portal or CLI changes.

Before

N/A

After

N/A

Testing

• pnpm --filter "./packages/**" build: passed
• pnpm exec tsc --noEmit -p . in apps/api, apps/judge, packages/shared, packages/model-scanning, apps/workers/coder-acp-copilot, apps/workers/coder-acp-claude-code, apps/model-scanners/copilot and apps/model-scanners/anthropic: passed
• pnpm exec vitest run apps/api packages/shared apps/judge packages/model-scanning scripts/register-agent.test.ts apps/workers: passed (133 files, 2216 tests)
• docker compose config -q: passed
• pnpm generate:openapi (in apps/api): regenerated website/src/openapi/scope-openapi.json; the snapshot test passes
• Package lint scripts were not run: eslint is not installed in the workspace (eslint: command not found).

Documentation and compatibility

• docs/architecture/auth-rbac.md §6 covers run tokens and per-service keys, with the authentication flow, failure codes and the service table.
• ENV_VARIABLES.md adds RUN_TOKEN_MAX_AGE_MS, INTERNAL_API_KEY_REGISTER_AGENTS, INTERNAL_API_KEY_MODEL_SCANNER and SCOPE_INTERNAL_API_KEY. .env.example is updated.
• Compatibility: no change for requests without a token.
• Upgrade step: to identify register-agents and the scanners, set the two internal API keys on the API and the matching SCOPE_INTERNAL_API_KEY on each caller. A caller without a key stays anonymous, as before. A caller that sends a key the API doesn't have configured gets 401.

Checklist

• N/A: If Portal features changed, keep CLI capabilities in sync.
• N/A: If Portal components changed, update their Storybook stories.
• N/A: If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. (run.tokenHash is optional and transient.)
• N/A: If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed.
• N/A: Video showing the behavior before the suggested change
• N/A: Video showing the behavior after the suggested change