@boopkit/cap-oauth-server 0.1.3 → 0.3.0

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

@@ -6,9 +6,10 @@ This app is an OAuth 2.1 **authorization server** (it issues tokens on a user's
 and a **resource server** (it accepts those tokens on its own API).
 That is what lets Claude, Claude Code, ChatGPT or any MCP client act as one of your users.
 
-> Slices 1 and 2 have landed: the client registry, the discovery documents, the consent screen,
-> `POST /oauth/token`, and a resource-server guard good enough to protect a route.
-> Revocation, the connected-clients screen and the device flow are not here yet;
+> What is here: the client registry, the discovery documents, the consent screen,
+> `POST /oauth/token`, a resource-server guard good enough to protect a route,
+> the connected-clients screen at `/connections`, and revocation, both from that screen and
+> from the client through `POST /oauth/revoke`. The device flow is not here yet;
 > this page describes what is actually here and says plainly what is not.
 
 ## Related
@@ -30,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.
@@ -48,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.
@@ -62,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.
@@ -82,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.
@@ -93,17 +151,150 @@ The same rule governs the four endpoint URLs: every one of them, `revocation_end
 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.
 
-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.
 
+### 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.
+
+#### 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, 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.
@@ -133,7 +324,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
@@ -188,6 +382,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
@@ -204,6 +438,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
@@ -313,6 +552,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
 
@@ -427,6 +675,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. |
 
@@ -449,6 +698,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 |
@@ -464,7 +714,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`
@@ -473,10 +726,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 +743,20 @@ Named so nobody debugs their absence:
 - **The device-code endpoints.** `OAUTH_DEVICE_CODE_ENABLED` names the flag; nothing reads it beyond
   keeping the grant type out of 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
 behind it rather than being taken back out of the document.

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.

package/scaffold/src/scripts/prune-oauth-clients.ts

@@ -0,0 +1,86 @@
+/**
+ * Garbage-collect abandoned OAuth client registrations.
+ *
+ * Run with `npm run oauth:prune-clients`. **Schedule it** — see below.
+ *
+ * ## What it deletes, and what stops it
+ *
+ * `POST /oauth/register` and the Client ID Metadata Document path both write a
+ * registry row for a caller nobody authenticated. Most of those rows are real
+ * connectors. Some are a script that walked away, and those never go anywhere:
+ * no consent, no grant, no token. After thirty days they are garbage, and this
+ * is what collects them.
+ *
+ * A row is deleted only when **nobody has that client connected** — that is,
+ * when no user's `oauth-grants` holds a live entry naming its `publicId`. The
+ * capability owns that question (`createClientInUsePredicate`), because the row
+ * that matters is the one carrying the `publicId` every live token for that
+ * client has as its prefix.
+ *
+ * Rows an operator wrote with `npm run oauth:seed-clients` are never touched,
+ * however old they are. Only the two unauthenticated modes are swept.
+ *
+ * ## Scheduling it
+ *
+ * Nothing here runs on a timer by itself, and an unscheduled prune is the same
+ * as no prune: `OAUTH_MAX_REGISTERED_CLIENTS` then becomes the only bound on
+ * registry growth, and a deployment that reaches it starts refusing legitimate
+ * registrations. Pick one:
+ *
+ *   - **Heroku Scheduler** (or your platform's equivalent): run
+ *     `npm run oauth:prune-clients` daily.
+ *   - **cron**, on a host you control:
+ *     `0 4 * * * cd /srv/app && npm run oauth:prune-clients`
+ *   - **cap-background-jobs**, if this project has it: import
+ *     `pruneAbandonedOAuthClients` from a job controller's `onMessage` and give
+ *     the queue a daily entry in `src/scheduler.ts`. That is the right home once
+ *     the sweep is one of several recurring jobs.
+ *
+ * Daily is a suggestion, not a requirement. The sweep is idempotent and reads
+ * only rows older than the cutoff, so running it more often changes nothing but
+ * the size of each batch.
+ */
+
+import { createClientPruneJob } from '@boopkit/cap-oauth-server';
+
+import {
+  clientRegistryService,
+  grantService,
+  tokenService,
+} from '../services/oauth-server.service';
+
+/**
+ * How long an unconnected registration survives. Thirty days, per the plan.
+ *
+ * Shorten it if open registration is being abused; do not shorten it below the
+ * time a person plausibly takes between installing a connector and approving
+ * it, because that gap is exactly what this measures.
+ */
+const ABANDONED_AFTER_DAYS = 30;
+
+const pruneJob = createClientPruneJob({
+  clientRegistry: clientRegistryService,
+  grantService,
+  tokenService,
+  ttlMs: ABANDONED_AFTER_DAYS * 24 * 60 * 60 * 1000,
+});
+
+/** One sweep. Exported so a background-jobs consumer can call it directly. */
+export async function pruneAbandonedOAuthClients(): Promise<string[]> {
+  const { before, removed } = await pruneJob.run();
+  console.log(
+    `[oauth-server] pruned ${removed.length} abandoned client registration(s) ` +
+      `created before ${before.toISOString()}`,
+  );
+  for (const clientId of removed) console.log(`  removed ${clientId}`);
+  return removed;
+}
+
+if (require.main === module) {
+  pruneAbandonedOAuthClients()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error('Pruning abandoned OAuth clients failed:', err);
+      process.exit(1);
+    });
+}

package/scaffold/src/services/oauth-server.service.ts

@@ -20,6 +20,8 @@
  * `oauth-grants` and `oauth-codes` the only two properties it ever reaches.
  */
 
+import { promises as dns } from 'node:dns';
+
 import db from '../db';
 import UserService from './users.service';
 import {
@@ -43,7 +45,29 @@ export const clientRegistryService = createClientRegistryService(db.oauthClient,
   // is the seam boop's own tests drive; here it is the real network.
   fetch: globalThis.fetch as unknown as FetchLike,
   maxRegisteredClients: oauthServerConfig.maxRegisteredClients,
+  // Where a metadata document may live. A Client ID Metadata Document is
+  // fetched at a URL an unauthenticated caller chose, so without this the
+  // consent endpoint is an SSRF probe of whatever network this app runs in —
+  // the body is discarded, but existence and latency are readable off the
+  // response time. The capability refuses every literal private, loopback and
+  // link-local target on its own; this resolver is what extends that to a name
+  // like `db.internal.example` that merely *points* somewhere private.
+  //
+  // It lives here rather than in the package because a capability has no
+  // business importing `node:dns`. Swap it for your own if you run a resolver
+  // with a different view of the network.
+  metadataResolveHost: async (hostname) => {
+    const records = await dns.lookup(hostname, { all: true });
+    return records.map((record) => record.address);
+  },
+  // Two different questions, answered from one list here: what a client is
+  // granted when it asks for nothing, and what it may ask for at all. Narrow
+  // `defaultScopes` if you want a smaller default grant — but leave
+  // `scopesSupported` as the advertised list, because it is the ceiling that
+  // keeps an unauthenticated registrant from writing itself a scope this
+  // server's discovery document says it does not have.
   defaultScopes: oauthServerConfig.scopesSupported,
+  scopesSupported: oauthServerConfig.scopesSupported,
   onMetadataRefreshFailed: (clientId, err) => {
     // A stale document that could not be refreshed is served from cache, so the
     // user's consent still works — but the failure is not silent, because a

package/scaffold/views/oauth-consent-error.hbs

@@ -6,9 +6,16 @@
   redirect: sending an error to an unverified redirect URI is the open redirect.
   So the person is told here instead, on our own page.
 
-  The message names what was wrong with the request and nothing about the
-  registry — a page that distinguished "no such client" from "that client is
-  suspended" would be an enumeration oracle for whoever is probing.
+  The message names what was wrong, including when what was wrong is that the
+  client has been suspended. That distinction is deliberate. It is not the
+  enumeration oracle it looks like: a registered `client_id` is already
+  distinguishable from an unregistered one here — probe either with a
+  `redirect_uri` the client does not own and only the registered one is told the
+  URI is unregistered, which is a sentence RFC 6749 requires this page to say —
+  and a `client_id` is a public identifier regardless, carried in the
+  authorization URL of every user the client has ever sent. What naming the
+  suspension buys is a suspended client's operator reading the right column
+  instead of hunting a registration that is perfectly intact (boop-wwxg).
 --}}
 <div class="consent-page">
   <section class="consent-card consent-card--error">