feat(identity): session bridge for organizations moved from Agent Relay Cloud (off by default)

Merged
AG
2d ago
+2501-16

What

A session bridge for organizations moved from Agent Relay Cloud to a deployment of this service, so a person with a live Cloud browser session does not have to sign in again after the move. Off by default (SELFHOST_CLOUD_BRIDGE_ENABLED); while off every bridge route answers 404 and no other bridge setting is read.

This service never validates a Cloud session or token. Cloud signs a short-lived, single-use Ed25519 assertion naming the person; this service verifies the signature against operator-configured public keys and issues its own browser session.

Flow

  1. GET /cloud/api/v1/auth/cloud-bridge/start?next= makes a nonce, keeps {nonce, next} in an encrypted HttpOnly attempt cookie scoped to the consume path, and redirects to the configured handoff URL with only the nonce.
  2. Cloud's handoff page signs an assertion for that nonce and auto-posts it to POST /cloud/api/v1/auth/cloud-bridge/consume.
  3. Consume checks, in order: per-address rate limit, exact Origin of the handoff page, attempt cookie, assertion (signature first, then typ, iss, aud, use: browser, lifetime at most 120 s), per-person and per-organization limits, nonce, single use (jti is spent before the account checks). Then in one transaction: the user exists by sub (never matched by email), the organization has an open window, the user is a member, auth_time is recent enough, and the person has not signed out here since that Cloud sign-in. It then issues a normal browser session and answers 303 to next.

Limits it keeps

  • Creates nothing: no user, organization, membership, workspace or invitation. Invites, auto-join domains and admin-email rules do not help a bridged sign-in.
  • Refuses organizations without an open window; the window is per organization, time-boxed (at most 90 days), and set only through bootstrap-bearer operator routes (/api/v1/installation/cloud-bridge/organizations).
  • Exchanges no Desktop credential, MCP OAuth grant or API token. use other than browser is refused. Desktop completes its normal browser sign-in on the bridged browser session.
  • Every acceptance and every refusal of a verified assertion is audited (auth.cloud_bridge.accepted / .refused, installation.cloud_bridge.organization_set / _removed). Logs carry an internal reason and never the assertion, nonce or cookie; claims are logged only after the signature verified.
  • The browser sees one code (cloud_bridge_invalid) for every request or assertion problem and distinct codes only for account refusals.

Changes

  • migrations/0083_cloud_bridge.sql: cloud_bridge_organizations, cloud_bridge_assertions (both added to src/control-tables.ts); verifier schema manifest refreshed.
  • src/identity/cloud-bridge.ts: settings parser and assertion verifier (Node crypto only).
  • src/identity/routes.ts, src/identity/store.ts, src/identity/config.ts: routes, account checks, operator routes.
  • src/identity/attempt-cookie.ts: optional SameSite=None for the cross-site form post (default unchanged).
  • docs/identity.md, docs/repository-guide.md, openapi.yaml, CHANGELOG.md.

Decisions worth a reviewer's eye

  • Signed-out fence. Any session of the person ended at or after auth_time refuses the assertion, except one ended by a workspace switch or by removing one Desktop MCP provider. A token revoke, a password reset and an enrollment-key revoke therefore all fence earlier Cloud sign-ins. This fails closed.
  • Rate limits. 30 starts and 30 consumes per source address per 5 minutes (the same rule as the other sign-in routes), 10 per person and 1,200 per organization per 10 minutes once verified. A large office behind one address can hit the per-address rule on the first morning; it is the existing sign-in behaviour, and SELFHOST_TRUSTED_PROXIES must be set behind a proxy.
  • Refusals are HTML pages with the code in an x-error-code header, because the caller is a browser navigation.
  • No Sec-Fetch-Site check on consume: it is cross-site by design; the exact Origin match is the check. A handoff page served with Referrer-Policy: no-referrer would send Origin: null and be refused.
  • The contract fixture (test/fixtures/cloud-bridge-contract.json) is a throwaway public key and an expired assertion from the signer's test suite; it holds no private key.

Not in this PR

  • A Desktop refresh-token exchange (use: desktop_refresh): refused here; a separate decision.
  • MCP OAuth grants, API tokens and CI tokens: re-authorised as today.
  • Anything an edge router in front of this service must do (route the two paths here, pass Set-Cookie), and Cloud's side (the handoff page, ending the Cloud session it vouches for).

Tests

Run locally one at a time, on this head:

  • tsc -p tsconfig.json --noEmit: clean
  • test/cloud-bridge-verifier.test.ts: 11/11
  • test/cloud-bridge.test.ts: 16/16 (routes, account refusals, fence, rate limits, operator routes, off = 404)
  • test/identity.test.ts: 46 pass, 3 skipped, 0 fail (regression)
  • test/migrations.test.ts: 11/11
  • verifier harness on PostgreSQL 15 with the refreshed manifest: 109/109

Hold

Labelled merge-train:hold: this adds a new way to obtain a session and needs the maintainer's explicit decision before merge. Merging it enables nothing; the switch stays off and no keys are configured.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Adds a session bridge so people with a live Agent Relay Cloud browser session don't have to sign in again after their organization moves to this deployment. Off by default via SELFHOST_CLOUD_BRIDGE_ENABLED; while off, all bridge routes answer 404 and no other bridge setting is read.

The bridge never trusts a Cloud session or token. Cloud signs a short-lived, single-use Ed25519 assertion naming the person; this service verifies the signature against SELFHOST_CLOUD_BRIDGE_PUBLIC_KEYS and issues its own browser session.

Flow

  • GET /cloud/api/v1/auth/cloud-bridge/start stores an encrypted nonce plus next in an HttpOnly attempt cookie and redirects to the configured handoff URL.
  • The handoff page auto-posts a signed assertion to POST /cloud/api/v1/auth/cloud-bridge/consume, which checks Origin, signature, claims, rate limits, per-organization window, membership, and that no sign-out happened here since the Cloud sign-in before issuing the session.

Limits

  • Creates nothing: no user, organization, membership, workspace, or invitation.
  • Refuses organizations without an operator-set, time-boxed (max 90 days) window configured via bootstrap-bearer routes.
  • use other than browser is refused; no Desktop, MCP OAuth, API, or CI token exchange.
  • Every acceptance and verified refusal is audited; logs never include the assertion, nonce, or cookie.