feat(oauth): assistants sign in with OAuth, and the owner approves at home

[frahlg]

Second of four stacked PRs. It is based on #18 (keys); review that first.

What this adds

The authorization server for MCP clients (ChatGPT, Claude, Grok), after the MCP authorization spec, revision 2026-07-28. The issuer is https://cloud.ftw.energy.

• OAuth 2.1 with PKCE S256 only. plain and a missing challenge are refused. Every authorization response, errors too, carries iss (RFC 9207). The RFC 8414 metadata says so, and says client_id_metadata_document_supported.

• Protected resource metadata (RFC 9728) for https://cloud.ftw.energy/mcp, at the path-inserted and the root well-known URIs.

• resource (RFC 8707). Only that resource is accepted, at authorize and at the token endpoint. Each token records its audience, and Authenticate checks it.

• Client ID metadata documents, fetched behind a fence:

  • https on 443, to a DNS name;
  • every resolved address public, checked again on the address the socket connects to;
  • no proxy, no redirects, no cookies;
  • 16 KiB, 5 s, eight at once, and per host four, then one every ten seconds;
  • cached by Cache-Control for between a minute and a day, even with no-store;
  • failures in a small cache of their own, for a minute, so they never push a good document out.

  A document with client_secret in it is refused. A document may list grants this server does not offer, as Claude's lists the JWT bearer grant; it must use the code grant. ::/96 (IPv4-compatible IPv6) joins the blocked ranges.

• Dynamic registration (RFC 7591), kept for ChatGPT and older clients. A client may be public, or use client_secret_post or client_secret_basic, with the secret kept as a hash. Redirect URIs must be https, or loopback http with any port; custom schemes are refused.

• Short tokens. Access tokens last 10 minutes. Refresh tokens rotate within a family. A retry within 5 s works once more, since its answer may have been lost; a later reuse revokes the family. A reused code revokes what it got, even after its consent was swept: spent codes' hashes outlive it. Tokens, codes and request ids are kept as SHA-256 only.

• redirect_uri at the token endpoint is required when authorize named one, and must be the same.

• Limits per address and for everyone. Authorize, registration and code lookups each have a bucket per address (an IPv6 address by its /64) beside the global one. Authorize takes both before it fetches a document or makes a key. Registered clients that never got an agent go after a day.

• No token passthrough. The token stays here. The box sees the agent's own Noise session.

• 401 and 403 with WWW-Authenticate (resource_metadata, scope, and insufficient_scope for step-up).

Built to the agent contract

srcfl/ftw#1642 (docs/agents.md), merged; #18 pins it at bf5bf50:

• Registry names. Scopes and roles are the registry's constants.
• Approval comes only from the roster. A consent is approved only by a roster row with role agent, an agent grant whose principal.clientId is the client the offer named, and an end still ahead. An agent row has tun: false: only the keys part opens its session. Support and release rows are not this door's.
• Only each home's newest roster is applied. A newer roster replaces an older one that has not been applied, so nothing drops and nothing old replays. When the keys part cannot keep an approved key, a retry runs the approval pass alone, on the newest roster: it cannot widen a grant the owner narrowed since, approve a consent the owner removed, or revoke an agent approved since.
• A key belongs to one home. Agents are unique by their full key, never taken over by another key with the same 48-bit id. A roster that lists, as its agent, a key approved for another home revokes it there and forgets the key.
• A purge reaches here. uplink.OnPurge calls DropHome: the home's agents, their tokens and keys, and its consents go, and a roster from before the purge is not applied after it.
• Revoking always deletes the key. A key to forget is queued in oauth.db with the revocation and stays queued, across restarts, until the keys part has forgotten it. Keep and Forget get 5 s each.
• The grant is the token's and the roster's. Scopes, ops, caps and end are refreshed with every roster. A token allows the scopes it carries that the box still grants, so an owner who narrows a grant narrows the token at once, and a narrowed refresh stays narrow. Wider rights need a new consent. The service stops admitting an agent at expiresAtMs by its own clock.
• The token's shape is checked first. A bearer token must have this server's shape before the store is asked. The token, revocation and registration endpoints give a client 10 s to send its body.
• The grant offer is protocol.SignedOffer {o, kid, sig}. o is GrantOffer: the agent's key, the client, clientHost (the metadata document's host, or a registered client's redirect host), verified, the scopes, the ops those scopes open, proposed caps, 30 days, the page's code and exp (at most ten minutes). It has no home, because the owner picks the home.
  • The keys part signs it; kid is keys.OfferKid.
  • The keys part signs it only for its own pending key (feat(keys): ftwkeysd, the one part that can open an agent's session #18).
  • It rides in the link's fragment with the request id (https://app.ftw.energy/a#<request>.<offer>), so neither reaches a server's log, and in the QR.
  • /oauth/requests?code= returns it once, rate limited per address and for everyone, to any origin, since the box's page fetches it from the owner's browser. The code is eight characters, drawn evenly (about 39 bits).
  • /.well-known/ftw-offer-key serves the kid and the key to pin.
• verified means a client FTW Cloud knows, by the exact URL of its metadata document. The list holds Claude's (https://claude.ai/oauth/mcp-oauth-client-metadata), read at that URL on 15 October 2026. ChatGPT's and Grok's documents were not found, so they show as unverified, by their host, until someone adds their exact URLs. Support's client id is refused here: support offers never come through this page.
• No redirect for a stranger. A client FTW Cloud does not know gets an error page with a link back to its host, never a 302, before the owner acts (RFC 9700, 4.11.2). A verified client's errors go back at once. On the page, an expiry offers the same link; approval and denial go back at once, since the owner acted.
• Tokens route without naming their home. A token is ftwat_<route>.<secret>, where the route is the home sealed with a fresh nonce under the route key (oauth-route.key, which every routing instance shares). Any instance opens it (Server.TokenHome) to find the home's shard, as in feat: a seam for shards, a quicker hot path, metrics, deploys without a storm, and a load harness #17, but a client sees no id that is the same in two of its tokens.

1. The authorize page. /oauth/authorize asks ftwkeysd for the agent's key pair; only the public half leaves it. The page shows:
   • the client's name, checked for a metadata document and marked unchecked for a registration;
   • the host the browser goes back to, with a warning for loopback;
   • the rights, in plain words;
   • a short code, a QR, and the universal link;
   • Strict-Transport-Security, as the error pages have.
2. What the app and the box read. The app reads /oauth/requests/<id>; the box's page reads /oauth/requests?code=, rate limited. Both get the client, the scopes and the agent's public key.
3. The page waits on a server-sent event, not a poll. Only the browser that started the request keeps a stream open, two at most, under a cap for the process; anyone else gets the state once.
4. The signed roster decides. When the box's signed roster lists that key as a device that may open a session, the consent is approved and the key is kept. Only the browser that started the request (by an __Host- cookie) gets a fresh code.
5. Deny and expiry. A denied or expired request returns access_denied, and the key is forgotten.

A token maps to (shard, home, agent id). The subject has a kind, so a later staff principal fits without changing an agent's token; staff sign-in is not built. The shard is a name, as in the seam from #17. A roster that drops an agent, or the end the box set for it, deletes the agent's tokens and its key.

ftwcloudd mounts it with -keys-socket, and keeps its state in oauth.db beside the registry. server.go and main.go gain only routes and wiring.

What the tests prove

internal/oauth, with a real keys part and an https metadata server:

• The full flow with a metadata document and PKCE, then refresh with rotation. A reused refresh token kills the family; a reused code kills its tokens.
• The full flow with dynamic registration, public and confidential. Bad registrations are refused.
• PKCE is required. A missing or plain challenge gets a link back with invalid_request and iss, and a wrong verifier is refused.
• No unchecked redirect. An unknown client or a mismatched redirect URI gets an error page, never a redirect. For an unverified client, another resource and an unknown scope get a page with a link back (invalid_target, invalid_scope); for a verified one, a 302.
• Consent completes only when the roster lists the very key. Not under another id, not for another client, not past its end, not as support, and not as a phone. A stranger's stream gets the state once and closes; after the approval it hears "approved" but gets no code. A third stream of the browser's is refused.
• The offer opens with protocol.OpenOffer and the key pinned by its kid. Its fields are right (no home; exp within ten minutes). It does not open with another key or at its end. It is in the page's link fragment, and the code finds it once.
• The grant follows the roster. Narrowing reaches the token at once; widening does not reach an existing token; a renewal extends the agent; a narrowed refresh stays narrow; and the service's own clock stops the agent at its end. A token routes to its home without naming it, two tokens never share a route, a route under another key does not open, a made-up secret with a good route is refused, and a token of the wrong shape never reaches the store.
• Deny and expiry both redirect with access_denied. A roster after that does not approve.
• Revoke at the box. The next roster leaves the agent out: the access and refresh tokens fail, the keys part forgets the key, and the MCP side hears it.
• An expired agent fails, and is swept.
• Wrong audience is refused, as are a refresh token used as an access token and a token in the query string.
• The challenge headers are right, and the box's page finds a request by its code as an owner types it.
• The page is safe. It has a strict CSP and HSTS and escapes a client's name. Authorize is rate limited before it fetches a document, and authorize, registration and lookups each per address, one /64 counting as one caller.
• Rosters (review_test.go):
  • a retry runs only the approval, on the newest roster;
  • 3,000 homes' rosters at once drop nothing;
  • a purge drops the agents, their tokens, keys and consents, and a roster from before it is not applied after it;
  • a key listed at a second home is revoked and forgotten;
  • a key the keys part could not forget stays queued until it has, and a denied consent's key goes too.
• Codes and tokens:
  • codes are eight characters, drawn evenly over 20,000 draws;
  • redirect_uri is required at the token endpoint when authorize named it;
  • a code used again after the sweep still revokes;
  • a refresh retried within the grace works once, and a third use revokes the family.
• Clients:
  • only the exact verified URLs count;
  • support's client id is refused;
  • unused registrations go after a day.
• internal/store: an agent's, support's or the release check's row is admitted neither as a phone nor by a token. internal/uplink: a purge calls OnPurge each time the box asks.

CIMD SSRF:

• URL rules: scheme, port, IP literals, dot segments, userinfo, fragment.
• Inside addresses are refused before a socket opens: loopback, the private ranges, 169.254.169.254, CGNAT, IPv6 ULA and link-local, IPv4-mapped, NAT64, and a name that mixes a public and a private answer. The connect-time check refuses too.
• A misbehaving server is refused: a redirect to the metadata service, an oversized body, a slow server, an error, a mismatched client_id, a secret in the document, a custom-scheme redirect, private_key_jwt, no name, HTML.
• Caching follows the rules, and the fetcher reads no proxy. Fetches per host are capped, failures never push a good document out, and Claude's real document, JWT bearer grant and all, is accepted.

internal/server: no assistant route returns a home's readings.

Not in this PR

• The app does not open the universal link yet. app.ftw.energy's AASA covers /p only, so /a needs a paired change in srcfl/ftw-webapp (public/.well-known/apple-app-site-association) and a handler in the iOS app. The link's fragment is <request>.<offer>. The app then sends agent.add to its box. That is the core-agent-role contract.
• Consents across shards. With more than one shard, a consent starts on the default host while the approving roster arrives on the home's shard. Both must see one consent store, or the default host must forward. feat: a seam for shards, a quicker hot path, metrics, deploys without a storm, and a load harness #17's follow-up decides which.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-15T17:29:50.633839Z	a9485fb	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a9485fb556

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not discard the only copy of a roster change

When more than 1,024 roster events are awaiting processing, this branch silently drops the newest event and assumes another roster will follow. However, internal/uplink/uplink.go invokes OnRoster only when SetRoster accepts a newly received roster, so an unchanged roster is not periodically replayed. During a reconnect or update burst, dropping the event that removes an agent can therefore leave that agent's tokens and retained key valid indefinitely, until the box happens to publish another roster revision.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Validate refresh scopes before rotating the token

For a refresh request containing a scope not present in the original grant, the token is marked used here before the scope validation at lines 106–115 rejects the request. The client receives no replacement refresh token, and retrying with a valid scope is then treated as token reuse and revokes the whole family, forcing the owner through authorization again. Validate the request first and rotate only as part of issuing the replacement.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Prevent registrations from permanently exhausting capacity

The unauthenticated registration endpoint rejects every new client once this persistent count reaches 50,000, but the added store has no expiry or deletion path for client rows. A caller can consume the capacity at the allowed sustained rate in roughly three days, after which dynamic registration returns 503 permanently across restarts and requires manual database repair. Prune stale or unused registrations rather than imposing a lifetime-only count.

Useful? React with 👍 / 👎.

[frahlg]

Included in #21 (squash 2e7afbd), which carries the whole MCP stack.