Relationships
#4876 The sign-in exchange: a root token becomes a workspace token through a single-use code
Opened by zack · 11/18/2026· Shipped 11/18/2026
Issue 14 of the execution plan in design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4849 (workspace requests on the root), shipped.
Problem
Every hosted workspace is a whole serve with its own tokens. A person who uses five workspaces signs in five times, once at each workspace's address.
A root in token mode also refuses workspace.create (token_mode_create_refused). The creator would have no way to get a token inside the new workspace.
Change
A person signs in once, to the root. Each workspace still mints and checks its own tokens, so every access record stays in the workspace. The design section is Sign-in.
The exchange
- The client asks the root for a sign-in code for one workspace, with a new
workspace.sign-inrequest. The root gives any authenticated principal a single-use code that names the workspace and expires within a minute. - The client gives the code to the workspace, at
POST /auth/exchange. - The workspace redeems the code at the root and sends its own name with it. The root refuses a code that names another workspace. Otherwise it answers once with who the code was issued to: the principal, the username and the collectives.
- The workspace applies its own admission lists and mints its own server token for that principal.
The root
- Issues codes and redeems them. A code is random, single-use, bound to one workspace name and gone within a minute whether or not it was redeemed.
- A code is never logged and never written to the audit log. The audit log records that one was issued and that one was redeemed, with the caller and the workspace name.
- The root does not authenticate the redeemer. The design accepts this: a hostile workspace that redeems another's code gains a token only inside itself.
A workspace
- Offers
POST /auth/exchange, and says so in/auth/info. - A serve that was given no root address offers no exchange, and
/auth/infosays that too. - The token it mints lives no longer than the root token the code came from. Its collectives are the ones the root knew at the exchange.
- The exchange is rate limited as serve's other unauthenticated sign-in routes are.
The host
- Passes each workspace the root's address when it starts it, as it already passes the root the host's address (
src/serve/host/serve_process.ts). A host with no root passes none.
Token mode
- The exchange is the same in token mode, so the creator of a workspace reaches it with the root token they already hold.
- A token-mode root stops refusing
workspace.create.
Decisions this issue makes
The PR states what it chose and updates the design doc.
- A caller acting through an integration or a delegation. The workspace token would not carry the caller's ceiling. The expected answer is that the root refuses such a caller a code.
- Where the root keeps codes. The node that redeems a code must find it. A root with followers has more than one node.
- How a workspace reaches the root to redeem. Through the host's router at the root's public address, or another way. The root token is not involved either way.
- How the redeem reply carries the root token's expiry, so the workspace can cap its own token.
Done when
- The holder of a root token gets a workspace token that works at the workspace's address.
- The root token is sent only to the root. A test asserts on what the workspace received.
- A code for one workspace is refused at another.
- A code is refused the second time it is used, and after it expires.
- A principal the workspace's admission lists do not admit gets no token, and the refusal is in the workspace's audit log.
- The workspace token expires no later than the root token.
- A serve given no root address answers
/auth/exchangeas not offered, and/auth/infodoes not offer it. - A token-mode root creates a workspace, and its creator gets a token inside it through the exchange.
- Tests run in-process. A test that authenticates through serve's HTTP routes as a fixed principal calls
resetRateLimitState()first.
Out of scope
- The CLI doing the exchange by itself. The next issue in the plan.
- The dashboard signing in under a workspace segment. Item 17.
- Carrying a revocation on the root into a workspace. The design lists it under Limits: a workspace token outlives changes on the root until it expires.
- The
workspacekind in grants.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.