Skip to content

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

Merged
agent-relay-code[bot] merged 1 commit into
mainfrom
feat/moved-org-session-bridge
Nov 20, 2026
Merged

agent-relay-code[bot] merged 1 commit into
mainfrom
feat/moved-org-session-bridge

Conversation

@agent-relay-code

@agent-relay-code agent-relay-code Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

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.

Written for commit 69c1691. Summary will update on new commits.

View guided diff Turn on auto-fix

…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>
@agent-relay-code agent-relay-code Bot added the merge-train:hold Do not merge until the owner gives the go label Nov 20, 2026
@coderabbitai

coderabbitai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a1621d3f-58be-4d44-816c-d65c97f71b02

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@agent-relay-code

Copy link
Copy Markdown
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 agent-relay-code Bot removed the merge-train:hold Do not merge until the owner gives the go label Nov 20, 2026
@agent-relay-code
agent-relay-code Bot merged commit 0807c6f into main Nov 20, 2026
3 checks passed
@agent-relay-code
agent-relay-code Bot deleted the feat/moved-org-session-bridge branch November 20, 2026 22:01
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants