feat(identity): session bridge for organizations moved from Agent Relay Cloud (off by default)
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
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.- Cloud's handoff page signs an assertion for that nonce and auto-posts it to
POST /cloud/api/v1/auth/cloud-bridge/consume. - Consume checks, in order: per-address rate limit, exact
Originof the handoff page, attempt cookie, assertion (signature first, thentyp,iss,aud,use: browser, lifetime at most 120 s), per-person and per-organization limits, nonce, single use (jtiis spent before the account checks). Then in one transaction: the user exists bysub(never matched by email), the organization has an open window, the user is a member,auth_timeis recent enough, and the person has not signed out here since that Cloud sign-in. It then issues a normal browser session and answers303tonext.
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.
useother thanbrowseris 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 tosrc/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: optionalSameSite=Nonefor 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_timerefuses 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_PROXIESmust be set behind a proxy. - Refusals are HTML pages with the code in an
x-error-codeheader, because the caller is a browser navigation. - No
Sec-Fetch-Sitecheck on consume: it is cross-site by design; the exactOriginmatch is the check. A handoff page served withReferrer-Policy: no-referrerwould sendOrigin: nulland 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: cleantest/cloud-bridge-verifier.test.ts: 11/11test/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](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
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/startstores an encrypted nonce plusnextin 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.
useother thanbrowseris 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.