@boopkit/cap-oauth-server 0.1.4 → 0.3.1

package/scaffold/reference/oauth-server.ref.md

@@ -31,6 +31,13 @@ The narrow, load-bearing constraint:
 The one table this capability owns is `oauth_clients`, which describes *software* rather than people.
 boop's own suite enforces the boundary mechanically: `tests/packages/cap-oauth-server-import-audit.test.ts` fails on `db.user`, `db.account`, `db.userIdentity`, `db.userProperty`, `db.accountUser` or `db.accountProperty` anywhere under the package's `src/` or `scaffold/src/`.
 
+### There is exactly one cap-users, and the manifest says so
+
+`@boopkit/cap-users` is a **peer** dependency (`>=0.9.0 <1`), not an ordinary one.
+The difference is the whole boundary: a `dependencies` entry lets npm satisfy this package with a nested second copy of cap-users whenever the declared range stops matching the one your project installed — and caret on a 0.x version pins the *minor*, so an ordinary minor bump is enough to trigger it.
+Two copies fail quietly rather than loudly. Tokens this capability hashes with one copy's `hashToken` are unresolvable by the other, and every `instanceof` across the pair is a silent false negative — which is why the error guards in `user-store.ts` and `oauth-error.ts` compare error *names* instead.
+Declared as a peer, the capability uses the cap-users your project already has, and an incompatible one is an install-time error you can read rather than an authentication outage your users report.
+
 ## The client registry
 
 One table, `oauth_clients`, with a `mode` discriminator rather than three tables.
@@ -49,6 +56,40 @@ Two columns carry the design:
 
 `status` is `enabled` or `suspended`. Suspending is how you stop a compromised client, because deleting the row would strand the live tokens that carry its prefix.
 
+### Two writers creating the same client
+
+Both paths that create a row — `registerStaticClient` and `resolveMetadataDocument` — look the client up, and then create it, with an `await` in between.
+Two callers can therefore both look, both see nothing, and both write.
+This is not hypothetical timing trivia: `registerStaticClient` is what a seed script calls, and two app instances booting together run it at the same moment.
+`resolveMetadataDocument` has the wider window of the two, because it fetches the client's metadata document between the lookup and the write, so two authorization requests naming the same new `client_id` overlap for a whole network round-trip.
+
+The unique index on `client_id` settles it, and the loser gets a Prisma `P2002`.
+Both paths catch that and converge on the winner's row instead of failing:
+
+- `registerStaticClient` re-runs its update against the existing row. The data it writes carries no `publicId`, so the **winner's token prefix survives** — which is the whole point, since every token this client is ever issued carries it.
+- `resolveMetadataDocument` re-reads rather than writes. The row that won might be `static` or `dynamic` — somebody racing an operator's seed of the same URL — and overwriting one of those is exactly what the mode check exists to prevent.
+
+A `P2002` on `public_id` is **not** treated as a lost race. That is a collision between two generated identifiers, which is genuinely exceptional, and it is rethrown.
+
+**If you write a recovery like this yourself, read `isUniqueConstraintViolation` in `errors.ts` first.**
+Which name Prisma puts in `meta.target` depends on the connector: PostgreSQL reports the **column** (`client_id`), because it reads the target off the constraint, while MySQL reports the **field** (`clientId`).
+The predicate accepts both, and it does so because it once did not — see below.
+
+### What is proven against a real database, and what is not
+
+Most tests of `ClientRegistryService` run against `tests/helpers/oauth-client-delegate.ts`, an in-memory stand-in.
+`tests/integration/oauth-clients-postgres.test.ts` migrates this capability's schema fragment into a throwaway Postgres and runs the service against the generated Prisma client, covering the things that are properties of the **column** rather than of the service: that `varchar(512)` holds a 512-character `client_id` and refuses a longer one, that the JSON columns round-trip by value, that `@updatedAt` fires while `@default(now())` stays put, that both `@@index` declarations survive migration and `(mode, created_at)` can answer the prune's predicate, and that two connections racing to seed one `client_id` converge on one row.
+
+It is gated on `E2E_SCHEMA=1`, because it installs Prisma and migrates a database, and it needs a local Postgres.
+
+```
+E2E_SCHEMA=1 npx jest tests/integration/oauth-clients-postgres.test.ts
+```
+
+Run it when you change the schema fragment or the mock delegate.
+It has already earned its keep: a mock decides for itself what its own errors look like, and the first thing real Postgres said was that the mock had picked the wrong spelling for `meta.target`.
+The recovery paths above matched a string the database never sends, and every mock test in the suite passed anyway.
+
 ### Redirect URIs
 
 Three shapes may be registered, and no others — the three RFC 8252 names for calling a client back.
@@ -63,9 +104,19 @@ None of them may carry a fragment.
 A private-use entry must be **hierarchical** — something after the scheme starts with `/` — and its scheme may not be one a browser already gives a meaning to.
 That refuses `urn:ietf:wg:oauth:2.0:oob`, `mailto:` and `tel:`, which carry an opaque payload rather than a location, and it refuses `javascript:`, `data:`, `vbscript:`, `view-source:`, `blob:`, `about:`, `file:`, `ws:`, `ftp:` and the privileged browser origins, which are places a browser must never be redirected to.
 
-Matching is **exact string match**, with **one** exception: a registered *loopback `http`* entry matches a presented URI that differs *only* in port (§7.3).
+Matching is **exact string match**, with **one** exception: a registered entry whose **host** is `localhost` or `127.0.0.1` matches a presented URI that differs *only* in port (§7.3).
 Claude Code needs it — it binds an ephemeral loopback port at connect time.
-Nothing else is relaxed: not the scheme, not the path, not a trailing slash, not the port on a public host, and not the port on a private-use URI whose authority happens to read as `localhost`.
+Nothing else is relaxed: not the path, not a trailing slash, not the port on a public host, and not the port on a private-use URI whose authority happens to read as `localhost`.
+The presented URI must carry the *same* scheme and the *same* host — `localhost` and `127.0.0.1` are two different hosts here, because §7.3 relaxes the port rather than name resolution.
+
+The exception is keyed on the host and **not** on the scheme, so a registered `https://localhost/cb` gets its port relaxed as well.
+§7.3 is about loopback `http`, so an argument exists for narrowing this to `http` alone; it stays host-keyed because a loopback port is ephemeral whichever scheme terminates it, and refusing an operator who runs a local client over TLS buys nothing.
+So registering `https://localhost/cb` does not buy you exact matching on the port, which is the reading an operator is most likely to arrive at on their own.
+
+Those two hosts are the whole list: the IPv6 loopback `[::1]` is **deliberately unsupported**.
+It keeps the surface to the two spellings the design enumerated, at the known cost of turning away a native app on an IPv6-only machine — a client RFC 8252 §7.3 anticipates.
+The refusal is at least legible rather than silent: `validateRedirectUris` reads `http://[::1]:52731/callback` as `http` on a non-loopback host and rejects it at **registration**, so the client learns at the point it registers instead of failing later with `redirect_uri is not registered`.
+An `https://[::1]/cb` entry does register — it is an ordinary absolute `https` URI — but it gets exact matching, port and all, like any other `https` host.
 
 Both halves read one exported function, `classifyRedirectUri`, so what may be stored and what may be matched cannot drift apart.
 A client that could register and then not connect is the same defect as a list that was never validated at all.
@@ -83,6 +134,12 @@ Both are **computed from configuration**, not read off disk, and both are cached
 
 `resource` is `OAUTH_RESOURCE_URL`, and it is **not** the issuer: it must equal the URL clients actually connect to, exactly as they enter it.
 
+The protected-resource document is served at **two** paths whenever that resource is not at the root.
+RFC 9728 §3.1 puts it at the well-known segment inserted between the host and the resource's own path — a resource at `https://app/api/mcp` publishes at `https://app/.well-known/oauth-protected-resource/api/mcp` — and that is where clients ask first.
+The bare `/.well-known/oauth-protected-resource` stays beside it, because it is where a client that took a 404 from the specified location falls back.
+Both paths are fixed at boot from `OAUTH_RESOURCE_URL`; neither is built from anything a caller sends, and a resource at the root gets the bare path alone.
+So does a resource whose path Express would read as a route pattern rather than as a literal — one containing `:`, `(`, `+`, `[` or `*` — since an app that refuses to boot over a discovery document's address is the worse trade.
+
 The device-code grant type appears in `grant_types_supported` only when `OAUTH_DEVICE_CODE_ENABLED` is the string `"true"`.
 When the flag is off the endpoints are not mounted *and* the grant type is absent — advertising a grant whose endpoint answers 404 is worse than not advertising it, because a client that read the metadata treats the 404 as a server fault.
 The same rule governs the four endpoint URLs: every one of them, `revocation_endpoint` included, is mounted.
@@ -92,19 +149,204 @@ The same rule governs the four endpoint URLs: every one of them, `revocation_end
 `POST /oauth/register` — RFC 7591 open registration. Unauthenticated by design; that is what the Claude ecosystem expects.
 
 A valid request returns **201** with `client_id`, `client_id_issued_at`, the echoed metadata, `grant_types`, `response_types`, `token_endpoint_auth_method` and `scope`.
-There is no `client_secret`: this server issues only public clients.
+There is no `client_secret`: this server issues only public clients, and `token_endpoint_auth_method` in the response is always `none`, whatever the request declared.
+[Which authentication method a client may declare](#which-authentication-method-a-client-may-declare) says what is accepted and what is refused.
 
-Because the endpoint is an unauthenticated write, it carries four controls:
+Because the endpoint is an unauthenticated write, it carries six controls:
 
 1. `redirect_uris` is **required** and validated.
-2. Per-IP rate limiting — `OAUTH_REGISTRATION_RATE_LIMIT` per hour, in process memory, per instance.
-3. A row ceiling — `OAUTH_MAX_REGISTERED_CLIENTS`. This is the hard bound; the rate limit only makes reaching it slow.
-4. `ClientRegistryService.pruneAbandonedClients()` for rows that never went anywhere. It takes an "is this in use?" predicate, which stays unimplemented until grants exist.
+2. `logo_uri`, `client_uri`, `policy_uri` and `tos_uri` must each be an absolute `https` URL or be
+   absent, and a non-https value is refused with `invalid_client_metadata` naming the field.
+   These four are the stranger-supplied values the consent screen renders — one in an `<img src>`,
+   three in an `<a href>` — and template escaping does not touch a scheme, so `javascript:` would
+   otherwise reach an `href` on the page where the user grants access. The same rule applies to
+   `ClientRegistryService.updateRegistration` and to a metadata document. The consent screen sanitises on the
+   way out as well (`safeHttpsUri`), which is what covers rows written before the rule existed; the
+   registration-time refusal is what tells the registrant rather than letting their privacy-policy
+   link silently fail to appear.
+3. Per-IP rate limiting — `OAUTH_REGISTRATION_RATE_LIMIT` per hour, in process memory, per instance.
+4. A row ceiling — `OAUTH_MAX_REGISTERED_CLIENTS`. This is the hard bound; the rate limit only makes reaching it slow.
+5. A scheduled prune for rows that never went anywhere — `npm run oauth:prune-clients`, backed by `ClientRegistryService.pruneAbandonedClients()`. See [Collecting abandoned registrations](#collecting-abandoned-registrations).
+6. `scope` is **narrowed to `OAUTH_SCOPES_SUPPORTED`**, the way `grant_types` is.
+   A registration naming `profile admin` is stored as `profile` and the 201 says so; one naming only scopes you do not advertise is refused with `invalid_client_metadata`.
+   Storing it verbatim would make `scopes_supported` in your discovery document untrue and put a word nothing describes in front of a user on the consent screen.
+   The same ceiling applies to a metadata document, whose owner writes it unsupervised, and to the no-`scope` path at `/oauth/authorize`, which falls back to the client's registered list.
 
 **A `static` row cannot be modified or deleted through this surface.** That is a check in the service, not a convention: `/oauth/register` has no caller to authenticate, so a client you vouched for must not be rewritable by a stranger.
 
 If open registration does not suit you, remove the `preRoutes` hook that mounts `oauthServerRoutes` and keep the seed script.
 
+### Which authentication method a client may declare
+
+This server does not authenticate a client at the token endpoint.
+A `client_id` that names an enabled row is the whole check, and PKCE is what protects the code exchange.
+So every row is stored with `token_endpoint_auth_method: "none"`, and what a client declares decides only whether it is registered at all.
+The rule is the same for a `POST /oauth/register` body and for a Client ID Metadata Document.
+
+| The client declares | And its `token_endpoint_auth_methods_supported` | What happens |
+|---|---|---|
+| nothing, or `none` | anything | Registered as a public client. |
+| any other method, such as `private_key_jwt` or `client_secret_basic` | lists `none` | Registered as a public client. The declared method is not stored and is never performed. |
+| any other method | is absent, or does not list `none` | Refused with `invalid_client_metadata`. The message names the declared method and the methods the client listed. |
+
+The middle row is what lets ChatGPT connect.
+Its metadata document declares `private_key_jwt` and lists `["none", "private_key_jwt"]` as the methods it supports, so it prefers a signed assertion and can work without one.
+RFC 7591 §3.2.1 lets a server replace a requested metadata value with one it supports, which is the same reading that narrows `grant_types` and `scope`.
+The client is told what it got: the discovery document advertises only `none`, and a registration response echoes `token_endpoint_auth_method: "none"`.
+
+The last row stays a refusal on purpose.
+A client that declares `private_key_jwt` and does not offer `none` expects the token endpoint to check its signature.
+This server would not, so registering it would give that client weaker protection than it asked for without telling it.
+On the metadata-document path the refusal reaches the operator through the consent router's `warn` port, like any other document the registry will not use.
+
+#### When a registered client stops offering `none`
+
+A metadata document is fetched again once the registry's copy is more than 24 hours old, and the rule above is applied to the new document too.
+If the new document cannot be fetched, or is refused for any other reason, `resolveMetadataDocument` returns the row it already has and reports the failure through `onMetadataRefreshFailed`.
+A client whose document is briefly unreachable, or briefly wrong, should not break consent for the people already using it.
+
+One refusal is handled differently.
+If the document was fetched and now declares a method without offering `none`, `resolveMetadataDocument` throws the same `invalid_client_metadata` a new client with that document would get, and does not call `onMetadataRefreshFailed`.
+The client has withdrawn the thing its registration rested on, and serving the old row would give it the weaker protection the last row of the table refuses.
+A client that arrived yesterday and one that arrives today get the same answer.
+
+The refusal writes nothing.
+The row is still `enabled`, and its copy of the document is still stale, so the next call fetches the document again and a client that puts `none` back is served again without anyone stepping in.
+Because the row is untouched, the token endpoint and the resource server, which look a client up by its row and never read its document, go on serving the connections that client already has.
+If you want those stopped as well, [`suspend`](#there-is-no-way-to-edit-a-registration-afterwards-by-design) the client.
+
+Only the authentication method is treated this way.
+Refusing the cached row for every validation failure would turn a typo in a client's document, or a rule of this server's that turns out to be too strict, into an outage for everyone connected through that client.
+
+**The shipped `/oauth/authorize` route does not reach any of this yet.**
+It looks a client up by its row first and calls `resolveMetadataDocument` only when there is none, so a metadata-document client that already has a row is never fetched again through the routes (boop-uep7).
+Until that changes, the paragraphs above describe `resolveMetadataDocument` for an app that calls it directly, and a registered client's row stays as it was on first sight.
+
+`private_key_jwt` itself is not implemented: nothing fetches a client's `jwks_uri`, and nothing verifies a `client_assertion`.
+See [What is not here yet](#what-is-not-here-yet).
+
+### There is no way to edit a registration afterwards, by design
+
+RFC 7592 defines `PUT` and `DELETE` on `/oauth/register/:client_id`, authenticated by a `registration_access_token` the registration response hands out.
+**None of that is here, and none of it is planned** — see [What is not here yet](#what-is-not-here-yet) for the reasoning.
+So a registration is create-and-forget: a client that loses its `client_id` registers again, which costs it one unauthenticated request.
+
+What you get instead is a library API rather than an HTTP one.
+`ClientRegistryService.updateRegistration(clientId, metadata)` and `.deleteRegistration(clientId)` are exported for **your** admin screens and support scripts, where the caller is an operator you have already authenticated.
+Both validate what `registerDynamic` validates, so an amendment cannot reach a value a registration could not, and both refuse a `static` row.
+Prefer `suspend` over `deleteRegistration` for a client that may still have tokens outstanding: deleting the row drops the `publicId` every one of those tokens carries as its prefix.
+
+### The other registration endpoint: `GET /oauth/authorize`
+
+A Client ID Metadata Document client registers itself **by arriving**. An https `client_id` with no row yet is fetched at its own URL and written, on an unauthenticated GET — so the consent endpoint is a registration endpoint too, and it carries the same controls under different names:
+
+| Control | On `POST /oauth/register` | On first-sight CIMD resolution |
+|---|---|---|
+| Rate limit | `OAUTH_REGISTRATION_RATE_LIMIT` | `OAUTH_METADATA_RESOLUTION_RATE_LIMIT`, charged only when the `client_id` has no row |
+| Row ceiling | `OAUTH_MAX_REGISTERED_CLIENTS` | the same ceiling — `dynamic` and `metadata_document` rows are counted together |
+| Prune | `npm run oauth:prune-clients` | the same prune, over both modes |
+| Where it may point | n/a — nothing is fetched | private, loopback, link-local and local-network targets are refused |
+
+Only `static` rows are outside all four: an operator wrote them, and letting them fill the ceiling would let your own seed script lock registration shut.
+
+Both limiters key on `req.ip`. If you run behind a proxy or a CDN, set `trust proxy` on the app — without it `req.ip` is the proxy, every caller shares one bucket, and the limiter stops nobody in particular while rationing everybody.
+
+**The last row is the one to understand.** The URL fetched is a string an unauthenticated caller supplied, so without a guard the consent endpoint is a blind SSRF probe of whatever network your app runs in — the document body is discarded on a failure, but existence and latency are both readable off the response time, and `169.254.169.254` is where your cloud keeps its instance credentials. Every literal private, loopback, link-local and multicast address is refused, as are `localhost`, `.local`, `.internal` and `.home.arpa`, and the check runs again on every redirect hop.
+
+A *name* that merely points somewhere private needs DNS, which the capability will not do on its own. The scaffold wires `dns.promises.lookup` as `metadataResolveHost`, and every address a name resolves to is then run through the same table. Keep it. What remains uncovered is DNS rebinding — a name re-resolved between the check and the connection — which needs a transport that connects to an address this code chose, and `fetch` does not offer one.
+
+The ceiling is checked **before** the fetch, not before the write: a caller past it must not still be able to make your server issue one outbound request per attempt. A client that already has a row is served past the ceiling, including its lazy re-fetch, so filling the table does not break every existing connection at once.
+That re-fetch is the registry's; the route does not yet trigger one for a client it already knows, as [When a registered client stops offering `none`](#when-a-registered-client-stops-offering-none) explains.
+
+#### When resolution fails, the log and the page say different things
+
+A resolution can fail for reasons that need different fixes — the document was unreachable, it was not
+JSON, it declared a grant type this server does not support, it declared an authentication method
+without offering `none`, the registry was built with no `fetch` to reach it through, the ceiling was
+already full.
+The page tells the person in front of it only that `the metadata document for this client_id could not
+be used`;
+the reason goes to the operator, in the registry's own words, through the consent router's `warn` port
+(`console.warn` unless you pass one):
+
+```
+[cap-oauth-server] consent refused: could not resolve the Client ID Metadata Document at
+https://client.example/id — boop_metadata_document_unusable: metadata document at
+https://client.example/id is not JSON
+```
+
+Those two audiences do not need the same words, and until they were separated they did not get the
+truth either: every one of those failures was reported to both as `unknown client_id`, a condition
+that on this branch is never what happened (boop-nvbd).
+Distinguishing it from a genuinely unknown `client_id` is not an enumeration oracle, because the
+branch is reached only for an https `client_id` with no row — the caller learns nothing their own URL
+did not already tell them.
+
+The refusal page names a **suspended** client as suspended, with `403`, for the same kind of reason
+(boop-wwxg).
+Folding it into `unknown client_id` would hide nothing: a registered `client_id` is already
+distinguishable from an unregistered one here, because probing either with a `redirect_uri` the client
+does not own tells only the registered one that the URI is unregistered — and RFC 6749 §4.1.2.1
+requires that sentence to be said on this page rather than redirected.
+A `client_id` is a public identifier in any case.
+What it would cost is the operator of a suspended client being told their intact registration is
+unknown, which is the untrue sentence the paragraph above exists to remove.
+
+The line is collapsed to one line before it is emitted.
+The `client_id` is a query parameter and appears in it twice, so without that a caller sending `%0A`
+writes a second line into your log and chooses what it says.
+
+A failure that is **not** a registry refusal — the client store unreachable, a bug in the capability —
+is answered `500` rather than turned into a refusal page, so an operator is not sent to read a request
+when the answer is in the database.
+
+### Collecting abandoned registrations
+
+Of the controls above, only the prune is a *collector*.
+`OAUTH_MAX_REGISTERED_CLIENTS` caps the table and the rate limits make filling it slow, but neither
+ever gives a row back — so a deployment that leaves the prune unscheduled eventually reaches the
+ceiling and starts refusing **legitimate** registrations, because a script that walked away a year
+ago is still holding a thousand slots.
+
+The sweep is `npm run oauth:prune-clients`, which runs `src/scripts/prune-oauth-clients.ts`.
+**It does not run on a timer by itself.**
+Schedule it daily — Heroku Scheduler, cron, or a cap-background-jobs consumer calling the script's
+exported `pruneAbandonedOAuthClients()`.
+It is idempotent and reads only rows past the cutoff, so running it more often changes nothing but
+the size of each batch.
+
+It deletes a `dynamic` or `metadata_document` row when **both** are true:
+
+1. it was created more than thirty days ago, and
+2. nobody has that client connected.
+
+A `static` row is never swept, however old — an operator wrote it, and the ceiling does not count it
+either.
+
+**"Connected" means a live grant, and nothing else.**
+The predicate (`createClientInUsePredicate`) finds the client's users through the `"<publicId>|"`
+token-key scan and then reads each one's `oauth-grants`.
+It does not decide from the identity rows, for the reason
+[What a revoke actually writes](#what-a-revoke-actually-writes) gives at length: an ended row does
+not mean disconnected, because ordinary expiry end-dates rows too, and a live row does not mean
+connected, because rotation leaves the superseded refresh row deliberately active.
+Reading tokens would delete a client half your deployment uses.
+
+The scan is sound because a grant is only ever written at redemption, in the same request that mints
+the first token — a grant with no token row behind it is not a state this server can reach.
+
+Two consequences worth knowing before you shorten the thirty days:
+
+- **A disconnected client is collectable.** An ended grant is not in use, so once the row is old
+  enough it goes. `/connections` already renders a grant whose registry row has gone: it falls back
+  to the `client_id` the client presented and says the application is no longer registered here,
+  because a connection the screen does not list is a connection nobody can disconnect.
+- **An unredeemed authorization code is not protected.** Codes live for a minute and the cutoff is
+  thirty days, so the window is a client that registered a month ago, never connected, and is
+  mid-flow at the moment the sweep runs. It loses that one redemption and can register again.
+  Closing it would mean scanning `oauth-codes`, a per-user property with no cross-user read — a full
+  user scan to buy a minute of protection for a client that has never completed a grant.
+
 ## The interactive grant, end to end
 
 A connector's whole journey through this app, and where each step lives.
@@ -134,7 +376,10 @@ Three things on that page are load-bearing rather than decorative. A redesign ha
 icon come from an unauthenticated stranger, and they are the entire evidence base for the only
 decision on the page. `.consent-icon` fixes the box's size; a 4000px logo, a 1px logo and no logo at
 all all produce the same layout. Anything that is not an absolute `https` URL falls back to a
-monogram.
+monogram, and the same `https`-only rule governs the client's three link URIs — `client_uri`,
+`policy_uri` and `tos_uri` — which are dropped rather than rendered when they fail it. The person
+who follows a connector's privacy-policy link before approving is the cautious one, and a scheme a
+stranger chose must not be what they land on.
 
 **The provenance line says where the client's claims came from**, and its wording differs by
 registration mode: an operator-configured client says so, a metadata-document client names the origin
@@ -189,6 +434,46 @@ Both ports say no by throwing. The login face shows one generic message whatever
 signup face shows the thrown error's message, so a validation failure somebody can act on should
 carry words worth reading.
 
+### The form defends itself against another site
+
+`POST /oauth/authorize` mints an authorization code, and the only credential it needs is the session
+cookie the browser attaches unprompted. That is the shape cross-site request forgery exploits: an
+attacker registers a client with their own `redirect_uris` — dynamic registration is open — and
+serves a page that auto-submits this form with `action=approve`, so a code for the victim's account
+lands at the attacker's callback.
+
+Neither of the two things that look like a defence is one. PKCE binds a code to whoever asked for it,
+and here the attacker *is* the client, holding both the challenge and the verifier. `state` is the
+client's CSRF token, echoed back untouched, and on this attack the attacker chose it. What was
+actually holding the line was a browser default — an unlabelled cookie is treated as `SameSite=Lax`,
+which is not sent on a cross-site POST — and a defence that lives entirely in the user agent is one
+this server cannot assert or test.
+
+So there are two now, and they are independent:
+
+- **The route checks where the submission came from.** `Origin` and `Sec-Fetch-Site` are forbidden
+  header names, so page script cannot set or remove either and a hostile page's form post carries
+  them truthfully. Anything labelled as coming from elsewhere is refused with a **403 on our own
+  page** — never a redirect, because redirecting to the URI the attacker registered would tell them
+  the victim's browser got here. A request carrying neither header is accepted: it is not a browser,
+  and a forgery needs a browser, because a browser is the only thing that will attach somebody
+  else's cookie. `isSameSiteRequest` is exported if you want it on a form of your own.
+- **The session cookie is labelled.** `SameSite=Lax` and, in production, `Secure` — on the cookie
+  the consent page's inline login writes and on both cookies cap-users' `getOrCreateUser` writes.
+
+`Lax` rather than `Strict`, deliberately. The consent screen is *reached* by a cross-site top-level
+navigation — the client sends the browser here — and `Strict` withholds the cookie on exactly that
+hop, so every authorization would meet a login form for somebody who is already signed in. `Lax`
+refuses the cross-site POST, which is the request the attack needs, and permits the arrival, which
+is the request the flow needs. `cookieSameSite` overrides it if your deployment disagrees.
+
+The one thing you may need to configure is `allowedOrigins`. The host the request arrived on is read
+from the request, so an ordinary deployment needs nothing; the scaffold additionally names
+`OAUTH_ISSUER_URL`'s origin, because that *is* this server's public origin, which is what keeps the
+check right behind a reverse proxy that rewrites `Host` without setting `X-Forwarded-Host`. Add an
+entry only if you deliberately serve the consent page from a second origin — every entry widens what
+counts as your application.
+
 ### Scope descriptions are yours to write
 
 The capability transports and enforces scope strings; what `workflows:advance` *means* is your domain
@@ -205,6 +490,11 @@ Any advertised scope you have not described produces a **boot warning naming it*
 back to showing the raw string marked as machine text. A consent screen listing `workflows:advance`
 is asking somebody to approve something they cannot evaluate.
 
+The list you describe is the whole list a consent screen can show, because no client can hold a scope
+outside `OAUTH_SCOPES_SUPPORTED`: registration narrows to it, an explicit `scope` on an authorization
+request is checked against it, and the no-`scope` fallback to the client's registered list is filtered
+through it as well.
+
 ## Tokens
 
 Three credentials, all `<client publicId>.<random>` on the wire and all stored as
@@ -216,6 +506,28 @@ Three credentials, all `<client publicId>.<random>` on the wire and all stored a
 | Access token | `oauth-access` | `OAUTH_ACCESS_TOKEN_TTL_SECONDS` (900) |
 | Refresh token | `oauth-refresh` | `OAUTH_REFRESH_TOKEN_TTL_SECONDS` (7776000), sliding |
 
+### How the token endpoint identifies the client
+
+`POST /oauth/token` and `POST /oauth/revoke` read `client_id` from the request body and nothing else.
+A request with no `client_id` is answered `400 invalid_request`, and one whose `client_id` names no registered client, or a suspended one, is answered `401 invalid_client`.
+
+A request may carry `client_assertion` and `client_assertion_type` beside a valid `client_id`, as a client that declared `private_key_jwt` might send.
+Both fields are ignored: the assertion is not verified, and the request is not refused for carrying it.
+
+A client that sends an assertion *in place of* `client_id` is refused, because nothing here reads an identity out of an assertion.
+Whether ChatGPT does that has not been observed.
+Until its document was accepted it was turned away at consent, so it had never reached this endpoint.
+To make that first attempt diagnosable, a request refused because the client could not be identified writes one line through the router's `warn` option (`console.warn` unless you pass one), naming which of the three client-authentication fields the request carried:
+
+```
+[cap-oauth-server] POST /oauth/token refused: no client_id in the request. The request carried
+client_assertion, client_assertion_type.
+```
+
+The line gives field names and never values.
+An assertion is a signed credential, and a `client_id` is a string the caller chose.
+A refusal for a suspended client is not logged this way, because that client was identified.
+
 ### `endedAt` is a tombstone, not an expiry
 
 Worth knowing before you read the code and conclude something is missing. cap-users'
@@ -314,6 +626,15 @@ Do not mount `resolveOAuthBearer` on a router that already carries cap-users' `r
 read the same header. They are safe to have in one application because both **refuse** rather than
 falling back to the session cookie, but one router should have one door.
 
+**Where your users come from is one line.** `createOAuthResourceServer` takes a token service, a
+grant service, a `findUserById` function and a challenge — and nothing else. The scaffold points
+`findUserById` at cap-users' `userService.findById`, which is the right answer for a boop
+application, but the resolver calls it as a plain function and never reaches for a service, so an
+application that resolves users through a cache, a read replica or a layer of its own replaces that
+line and changes nothing else. The factory used to demand cap-users' `{ authService,
+identityService, userService }` trio as well and read none of it; it no longer does (boop-9ral), so
+the user layer is supplied once rather than twice.
+
 
 ## Disconnecting — `/connections` and soft revocation
 
@@ -413,6 +734,8 @@ somebody debug — an empty 200 is the feature.
 The only refusals are about the request itself: `400 invalid_request` for a missing `token` or
 `client_id`, `400 unsupported_token_type` for a `token_type_hint` naming a species this server does
 not issue, and `401 invalid_client` for a client that is unknown or suspended.
+A request refused because the client could not be identified is logged as the token endpoint logs
+it; see [How the token endpoint identifies the client](#how-the-token-endpoint-identifies-the-client).
 
 The hint is advisory. Both token domains are searched, hint first, because a server that trusted it
 would silently fail to revoke a correctly-presented token that a client mislabelled.
@@ -428,6 +751,7 @@ would silently fail to revoke a correctly-presented token that a client mislabel
 | `OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `7776000` | 90 days, sliding on rotation. Clamped to 3600–31536000. |
 | `OAUTH_MAX_REGISTERED_CLIENTS` | `1000` | |
 | `OAUTH_REGISTRATION_RATE_LIMIT` | `10` | Per hour, per address. |
+| `OAUTH_METADATA_RESOLUTION_RATE_LIMIT` | `10` | Per hour, per address. Charged only for a metadata-document `client_id` with no row yet. |
 | `OAUTH_DEVICE_CODE_ENABLED` | `false` | Not implemented yet; named so the flag has one home. |
 | `OAUTH_DOCUMENTATION_URL` | — | Echoed into both documents. |
 
@@ -450,6 +774,7 @@ The refresh token is long and *sliding*: each rotation mints a token with a fres
 | `src/services/oauth-server.service.ts` | Binds `db.oauthClient` and the environment to the capability's services |
 | `src/middleware/oauth-server.ts` | Builds the routers the server hooks mount, plus `resolveOAuthBearer` and `requireOAuth` |
 | `src/scripts/seed-oauth-clients.ts` | The static clients this deployment trusts. Edit this. |
+| `src/scripts/prune-oauth-clients.ts` | The abandoned-registration sweep. Schedule it. |
 | `views/oauth-consent.hbs` | The consent screen, in all three variants |
 | `views/oauth-consent-error.hbs` | Shown when the request named no usable client or redirect URI |
 | `views/oauth-connected-clients.hbs` | `/connections` — what this user has connected, and what they once had |
@@ -465,7 +790,10 @@ The refresh token is long and *sliding*: each rotation mints a token with a fres
 - `generateClientPublicId()`, `isValidClientPublicId(value)`
 - `buildAuthorizationServerMetadata(config)`, `buildProtectedResourceMetadata(config)`
 - `createDiscoveryRouter(config)`, `createRegistrationRouter(options)`, and the handler-set factories behind both
-- `createRegistrationRateLimiter(options)`
+- `createFixedWindowRateLimiter(options)` — the per-IP counter both unauthenticated write paths share; `createRegistrationRateLimiter` is the same factory under its original name
+- `blockedHostReason(hostname)`, `isBlockedAddress(value)` — where a caller-chosen URL may point
+- `STRANGER_CREATED_MODES` — the two modes the ceiling and the prune count
+- `createClientPruneJob(options)` — the scheduled abandoned-registration sweep; `createClientInUsePredicate(options)` is the "is anybody still connected?" half on its own
 - `readServerConfig(env)` — the environment, parsed, clamped and defaulted
 - `createTokenService(options)` — minting, parsing, the expiry rule and the lazy sweep
 - `createGrantService(options)` — `read`, `write`, `list`, `findActive`, `findById`, `approve`, `setRefreshKey`, `end`
@@ -474,10 +802,10 @@ The refresh token is long and *sliding*: each rotation mints a token with a fres
 - `createConnectionsRouter(options)` — `/connections` and its disconnect confirmation page
 - `createAuthorizationCodeService(options)` — `issue`, `redeem`, `list`
 - `createConsentRouter(options)`, `createTokenRouter(options)`, and the handler-set factories behind both
-- `createOAuthResourceServer(deps, options)` — `resolveBearer` and `requireOAuth`, sharing one challenge
+- `createOAuthResourceServer(options)` — `resolveBearer` and `requireOAuth`, sharing one challenge
 - `requireOAuth(...scopes)` and `missingScopes(granted, required)` on their own, for a route that already has a resolver in front of it
 - `verifyCodeChallenge`, `deriveCodeChallenge`, `isValidCodeVerifier`, `isValidCodeChallenge`
-- `warnUndescribedScopes`, `provenanceFor`, `safeLogoUri`, `monogramFor`, `toScopeViews`
+- `warnUndescribedScopes`, `provenanceFor`, `safeHttpsUri`, `monogramFor`, `toScopeViews`
 - `ACCOUNT_COVERAGE_STATEMENT`, `REVOKED_BY_USER`, `REVOKED_BY_CLIENT`, `REVOKED_CLIENT_WIDE`
 - `ClientRegistryError` / `isClientRegistryError`, `OAuthError` / `isOAuthError`, `isStaleWriteError`
 
@@ -490,6 +818,26 @@ Named so nobody debugs their absence:
   one.
 - **The device-code endpoints.** `OAUTH_DEVICE_CODE_ENABLED` names the flag; nothing reads it beyond
   keeping the grant type out of the discovery document.
+- **`private_key_jwt`, or any other client authentication.** A client that declares one is
+  registered as a public client when it also offers `none`, and refused otherwise; see
+  [Which authentication method a client may declare](#which-authentication-method-a-client-may-declare).
+  Implementing it means fetching the client's `jwks_uri` through the same guarded fetch as the
+  metadata document, verifying a signed `client_assertion` at the token and revocation endpoints,
+  and advertising the method in the discovery document.
+
+And one that is decided rather than pending — nothing is waiting on a later slice to add it:
+
+- **RFC 7592 client management.** `PUT`/`DELETE /oauth/register/:client_id` are not mounted, the 201
+  carries no `registration_access_token` or `registration_client_uri`, and the discovery document
+  advertises no management surface. Authenticating those endpoints means a third credential kind,
+  with its own hashing, rotation and revocation story, bought so that a client can amend a
+  registration it can re-create with one unauthenticated `POST`; nothing in the Claude ecosystem
+  checklist asks for it. The endpoints being *absent* is what makes them safe — mounted without that
+  credential, they would let any caller rewrite any dynamic client's redirect URIs, which is the hole
+  the six registration controls above exist to close. Reversing this means shipping the routes, the
+  token and the response fields in one change, never the fields alone.
+  `ClientRegistryService.updateRegistration` and `.deleteRegistration` are the operator-side
+  replacement; see [There is no way to edit a registration afterwards, by design](#there-is-no-way-to-edit-a-registration-afterwards-by-design).
 
 Everything the discovery document advertises is mounted. That is the rule the device grant type is
 held to by `OAUTH_DEVICE_CODE_ENABLED`, and it is why `revocation_endpoint` now has an endpoint

package/scaffold/src/middleware/oauth-server.ts

@@ -112,6 +112,27 @@ oauthServerRoutes.use(
       UserService.authService.login(email, password, sessionToken),
     register: (registration) => UserService.authService.signup(registration),
     scopesSupported: config.scopesSupported,
+    // The other unauthenticated write. An https `client_id` with no row yet is
+    // fetched and registered right here, so this path carries the same per-IP
+    // limit `/oauth/register` does — charged only when a request is about to
+    // resolve a client this server has never seen, so an ordinary visitor to an
+    // already-known connector never spends any of it.
+    metadataRateLimit: {
+      limit: config.metadataResolutionRateLimit,
+      windowMs: config.registrationRateWindowMs,
+    },
+    // `POST /oauth/authorize` refuses a submission that came from another
+    // site: it mints an authorization code on the strength of a cookie the
+    // browser attaches by itself, which is the shape cross-site request
+    // forgery exploits, and neither PKCE nor `state` covers it because on that
+    // attack the attacker is the client. The host the request arrived on is
+    // read from the request, so an ordinary deployment needs nothing here.
+    //
+    // Your issuer URL is named as well, because it *is* this server's public
+    // origin — that is what makes the check survive a reverse proxy that
+    // rewrites `Host` without setting `X-Forwarded-Host`. Add another entry
+    // only if you deliberately serve the consent page from a second origin.
+    allowedOrigins: [new URL(config.issuer).origin],
     // Describe every scope you advertise, in your app's composition root:
     //   app.locals.oauthScopeDescriptions = { profile: 'See your name and…' };
     scopeDescriptions: undefined,
@@ -181,23 +202,18 @@ oauthServerRoutes.use(
  * the `resource_metadata` pointer — and Claude does not honour that header on a
  * 200, which makes the 401 the only place it can arrive.
  */
-const { resolveBearer: resolveOAuthBearer, requireOAuth } =
-  createOAuthResourceServer(
-  {
-    authService: UserService.authService,
-    identityService: UserService.identityService,
-    userService: UserService.userService,
-  },
-  {
-    tokenService,
-    grantService,
-    findUserById: (userId) => UserService.userService.findById(userId),
-    // RFC 9728: point an unauthenticated caller at the document that tells it
-    // where to go. `requireOAuth` sends this same value, because the resolver
-    // hands it forward on the request rather than it being configured twice.
-    challenge: `Bearer resource_metadata="${config.issuer}/.well-known/oauth-protected-resource"`,
-  },
-);
+const { resolveBearer: resolveOAuthBearer, requireOAuth } = createOAuthResourceServer({
+  tokenService,
+  grantService,
+  // The one user read the OAuth path makes. It is a function rather than a
+  // service, so an application that resolves users some other way — a cache, a
+  // read replica, a service of its own — swaps this line and nothing else.
+  findUserById: (userId) => UserService.userService.findById(userId),
+  // RFC 9728: point an unauthenticated caller at the document that tells it
+  // where to go. `requireOAuth` sends this same value, because the resolver
+  // hands it forward on the request rather than it being configured twice.
+  challenge: `Bearer resource_metadata="${config.issuer}/.well-known/oauth-protected-resource"`,
+});
 
 /**
  * `GET /api/oauth/whoami` — the smallest protected resource there is.