Repository navigation
feat(identity): session bridge for organizations moved from Agent Relay Cloud (off by default) - #257
Merged
Conversation
…ay Cloud Off by default (SELFHOST_CLOUD_BRIDGE_ENABLED); while off its routes answer 404 and no other bridge setting is read. Cloud signs a short-lived, single-use Ed25519 assertion for a browser with a live Cloud session and posts it to /cloud/api/v1/auth/cloud-bridge/consume. This service verifies it against operator-configured public keys and issues its own browser session for the existing user (matched by id, never email) in an organization the operator listed with a time-boxed window. It accepts no Cloud token or cookie, creates no user, membership or workspace, and exchanges no Desktop, MCP or API credential. - migration 0083: cloud_bridge_organizations (per-organization window) and cloud_bridge_assertions (spent assertion ids) - start route keeps the nonce and next path in an encrypted attempt cookie; consume requires the handoff page's exact Origin, the nonce, a verified assertion, an open window, membership, a recent enough Cloud sign-in and no sign-out here since that sign-in - operator routes under /api/v1/installation/cloud-bridge/organizations (bootstrap bearer), audited - every acceptance and verified refusal is audited; refusals log an internal reason and never the assertion, nonce or cookie - verifier schema manifest refreshed for 0083 Co-Authored-By: Claude <noreply@anthropic.com>
|
Important Review skippedBot user detected. To trigger a single review, invoke the
|
Contributor
Author
|
Hold lifted: the maintainer gave the explicit decision this PR waited for. Merging enables nothing: the switch stays off and no keys are configured. |
agent-relay-code Bot
pushed a commit
that referenced
this pull request
Nov 20, 2026
Conflicts in CHANGELOG.md and openapi.yaml resolved by keeping both sides. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.POST /cloud/api/v1/auth/cloud-bridge/consume.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
/api/v1/installation/cloud-bridge/organizations).useother thanbrowseris refused. Desktop completes its normal browser sign-in on the bridged browser session.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.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
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.SELFHOST_TRUSTED_PROXIESmust be set behind a proxy.x-error-codeheader, because the caller is a browser navigation.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.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
use: desktop_refresh): refused here; a separate decision.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/11Hold
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
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith 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_KEYSand 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.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
useother thanbrowseris refused; no Desktop, MCP OAuth, API, or CI token exchange.Written for commit 69c1691. Summary will update on new commits.