@boopkit/cap-oauth-server 0.1.0

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

@@ -0,0 +1,478 @@
+# OAuth server
+
+What exists now, after `boop add oauth-server`.
+
+This app is an OAuth 2.1 **authorization server** (it issues tokens on a user's behalf)
+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;
+> this page describes what is actually here and says plainly what is not.
+
+## Related
+
+- Skill: `boop-services-services`, `boop-services-controllers` — the service and controller patterns this capability follows.
+- Capability: `users-and-accounts` — the sole authority on users, identities and sessions. This capability owns no user data.
+- Capability: `oauth-client` — the mirror image: signing *your* users in with Google or Microsoft. The two are independent.
+
+## The identity boundary
+
+The narrow, load-bearing constraint:
+**anything user-, account- or identity-shaped goes through cap-users' public surface, and nothing reaches around it.**
+
+- Tokens are minted with cap-users' `generateToken`, stored hashed with `hashToken`, and resolved through `IdentityService` under OAuth-specific identity domains.
+- A token *is* a `UserIdentity` row, so bearer resolution and cookie resolution are the same query and yield the same `req.user`.
+- The consent gate is the existing session middleware.
+- No new user or account concepts, and **no direct Prisma access to the user tables**.
+
+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/`.
+
+## The client registry
+
+One table, `oauth_clients`, with a `mode` discriminator rather than three tables.
+A mode says **where a client's authoritative metadata lives**, and almost nothing else.
+
+| Mode | How a row appears | Who owns the metadata |
+|---|---|---|
+| `dynamic` | `POST /oauth/register`, unauthenticated (RFC 7591) | We do, after registration |
+| `metadata_document` | First time a `client_id` that is an `https` URL is seen | The client, at that URL |
+| `static` | `npm run oauth:seed-clients` | You do |
+
+Two columns carry the design:
+
+- **`publicId`** — twelve lowercase base36 characters we assign in **every** mode. This is the **token prefix**: tokens are shaped `<publicId>.<random>` and the identity key is `<publicId>|<sha256>`. It is never the raw `client_id`, because a metadata-document `client_id` is a URL containing `/`, `:` and `.`, all of which break one of those two splits.
+- **`clientId`** — what the client actually sends. Equal to `publicId` for `dynamic` and `static`; the metadata-document URL otherwise.
+
+`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.
+
+### Redirect URIs
+
+Three shapes may be registered, and no others — the three RFC 8252 names for calling a client back.
+None of them may carry a fragment.
+
+| Shape | Example | Why |
+|---|---|---|
+| Absolute `https` | `https://claude.ai/api/mcp/auth_callback` | §7.2. A hosted connector. |
+| `http` on `localhost` or `127.0.0.1` | `http://127.0.0.1/callback` | §7.3. A native app cannot terminate TLS on loopback. |
+| A private-use scheme | `claude://oauth/callback`, `com.example.app:/oauth2redirect/cb` | §7.1. How a desktop or mobile app is handed the response by its operating system. |
+
+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).
+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`.
+
+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.
+
+## Discovery
+
+Two documents, mounted **outside `/api`** and reachable with **no authentication** — a client reads them before it holds any credential.
+
+| Path | Contents |
+|---|---|
+| `GET /.well-known/oauth-authorization-server` | RFC 8414: issuer, the four endpoint URLs, `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported: ["none"]`, `client_id_metadata_document_supported: true` |
+| `GET /.well-known/oauth-protected-resource` | RFC 9728: `resource`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported: ["header"]` |
+
+Both are **computed from configuration**, not read off disk, and both are cached for an hour (`Cache-Control: public, max-age=3600`).
+
+`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 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.
+
+## Client registration
+
+`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.
+
+Because the endpoint is an unauthenticated write, it carries four 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.
+
+**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.
+
+## The interactive grant, end to end
+
+A connector's whole journey through this app, and where each step lives.
+
+| Step | What happens | Where |
+|---|---|---|
+| 1 | The client calls your protected route with no token and gets **401** with `WWW-Authenticate: Bearer resource_metadata="…"` | `resolveOAuthBearer` / `requireOAuth` |
+| 2 | It follows that pointer to `/.well-known/oauth-protected-resource`, then to `/.well-known/oauth-authorization-server` | `oauthDiscoveryRoutes` |
+| 3 | It sends the user to `GET /oauth/authorize` with a PKCE `S256` challenge | the consent screen |
+| 4 | The user signs in (inline, on that page) and approves | `POST /oauth/authorize` |
+| 5 | We redirect back with a `code` and the client's original `state` | |
+| 6 | The client POSTs the code to `/oauth/token` with its `code_verifier` | `POST /oauth/token` |
+| 7 | It gets an access token, a refresh token, and calls your route again | |
+
+`tests/packages/cap-oauth-server-flow.test.ts` in boop walks exactly that, end to end, reading each
+step's values out of the previous step's real response.
+
+### The consent screen
+
+One page with three faces — an already-signed-in user, an inline login, an inline signup — because an
+authorization request is a long query string and round-tripping it through cap-users' `?next=` would
+mean encoding a URL into a redirect target. The request stays on the page in hidden fields.
+
+Three things on that page are load-bearing rather than decorative. A redesign has to keep all three.
+
+**The icon sits in a fixed box.** Under open dynamic registration the client's name, description and
+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.
+
+**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
+its document was published at, and a self-registered one says that nothing about it has been
+verified. Without that line a stranger's self-assertion is displayed exactly like something you
+vouched for, which makes the page a phishing surface.
+
+**The coverage statement comes before the Approve button.** The grant is keyed on the *user*, so a
+client reaches every account that user reaches, now and in future. Somebody must not discover that
+afterwards.
+
+Cancel is a protocol response rather than a navigation: it redirects to the registered URI with
+`error=access_denied` and the original `state`, so the waiting client is told rather than left to
+time out. The target is derived from the registry and never read from the form.
+
+**Signing in on that page is your decision.** `createConsentRouter` takes `signIn` and `register` as
+required ports, the way it takes `requireSignIn` for `/connections` — the capability never forms its
+own opinion about what signing in means here. The scaffold passes cap-users straight through:
+
+```ts
+signIn: ({ email, password, sessionToken }) =>
+  UserService.authService.login(email, password, sessionToken),
+register: (registration) => UserService.authService.signup(registration),
+```
+
+Replace either one when your application's own answer differs. The case that produced the ports:
+`authService.login` resolves credentials through a **proven `email` identity**, so an application
+that mints that identity later than signup — after a verification link is redeemed, say — has a
+login form that admits somebody this page would refuse. Two doors disagreeing about one password
+cannot be explained on the page, because cap-users returns a single generic failure on purpose:
+saying "this account has no password yet" would confirm the account exists. Pass the function your
+own login controller calls, and the doors agree.
+
+Both ports say no by throwing. The login face shows one generic message whatever the reason; the
+signup face shows the thrown error's message, so a validation failure somebody can act on should
+carry words worth reading.
+
+### Scope descriptions are yours to write
+
+The capability transports and enforces scope strings; what `workflows:advance` *means* is your domain
+knowledge. Publish the words on `app.locals`:
+
+```ts
+app.locals.oauthScopeDescriptions = {
+  profile: 'See your name and email address',
+  offline_access: 'Stay connected when you are not using the app',
+};
+```
+
+Any advertised scope you have not described produces a **boot warning naming it**, and the page falls
+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.
+
+## Tokens
+
+Three credentials, all `<client publicId>.<random>` on the wire and all stored as
+`"<publicId>|<sha256>"` in a `user_identities` row. The raw value is never stored anywhere.
+
+| Credential | Domain | Lifetime |
+|---|---|---|
+| Authorization code | `oauth-code` | 120 seconds, single use, **not configurable** |
+| Access token | `oauth-access` | `OAUTH_ACCESS_TOKEN_TTL_SECONDS` (900) |
+| Refresh token | `oauth-refresh` | `OAUTH_REFRESH_TOKEN_TTL_SECONDS` (7776000), sliding |
+
+### `endedAt` is a tombstone, not an expiry
+
+Worth knowing before you read the code and conclude something is missing. cap-users'
+`findByDomainAndKey` is active-only, so a *future* `endedAt` would read as already ended, and
+`endDate` takes no timestamp. A token's lifetime therefore has no home on the row, and is computed:
+**a token is expired when `createdAt + ttl < now`**.
+
+Because that comparison is derived from configuration it is retroactive — lengthening a TTL would
+otherwise resurrect tokens that had already expired. So the resolver **writes `endedAt` the first
+time it reads an expired token**, and the row is then permanently dead whatever the configuration
+does later. That write is a correctness requirement, not an optimisation; do not remove it.
+
+The authorization code is not governed by this rule: its `oauth-codes` entry carries an explicit
+`expires_at`, and that field is the authority.
+
+### Refresh rotation, and what reuse means
+
+Every refresh returns a new refresh token, and the grant records which one is current. Presenting an
+**already-rotated** refresh token is treated as evidence of theft — the legitimate client holds the
+newer one — so the whole grant is revoked: every `oauth-access` and `oauth-refresh` row is
+end-dated, the grant is end-dated with `reason: "refresh_reuse"`, and the answer is
+`400 invalid_grant`. The honest client's tokens die too, which is deliberate: after a theft there is
+no way to tell which of the two holders is real.
+
+A rotated token's identity row is deliberately left *active* rather than end-dated. That is what
+makes reuse detectable: resolution is the only thing that yields a user id, and without one there is
+no way to reach the grant at all. The old row grants nothing, because its key no longer matches
+`grant.refresh_key`.
+
+## Grants — what was approved
+
+`oauth-grants`, a user property, one entry per client:
+
+```jsonc
+{
+  "grant_id": "…", "client_id": "…", "client_public_id": "…",
+  "scopes": ["profile", "offline_access"],
+  "resource": null, "refresh_key": "<publicId>|<sha256>",
+  "created_at": "…", "updated_at": "…", "ended_at": null, "ended_reason": null
+}
+```
+
+**The grant is the scope authority at request time and the token carries no scope copy.** The guard
+reads the grant on every request, so re-consenting with a narrower list takes effect on the very next
+call with no revocation involved. Re-consent **replaces** the scope set rather than unioning it: the
+screen showed a specific list and the user approved that list.
+
+**No credential goes in here.** Only `credentials` is on cap-users' sensitive-property list, so this
+property and `oauth-codes` are readable by default. Client ids, scopes and timestamps belong there;
+token values, raw codes and PKCE verifiers do not. `refresh_key` is a SHA-256 digest, which is the
+same value the identity row holds.
+
+### Both properties are written whole, under `expectedRevision`
+
+Every write to `oauth-grants` and `oauth-codes` reads the entire array, changes it, and writes it
+back quoting the revision it read. It will look wasteful next to cap-users' `addAuthenticationMethod`,
+which updates one entry — and reaching for that is the bug in boop-zj8: it *replaces* an entry rather
+than merging it, and silently destroys fields the write did not name. Follow `setAuthorization`.
+
+The revision check is what makes a concurrent consent and revoke collide **detectably**. Without it
+one of the two would simply vanish and nothing anywhere would say so.
+
+## Protecting your own routes
+
+```ts
+import { resolveOAuthBearer, requireOAuth } from './middleware/oauth-server';
+
+app.use('/api/mcp', resolveOAuthBearer, requireOAuth('profile'), mcpRoutes);
+```
+
+`src/middleware/oauth-server.ts` already mounts one route this way — `GET /api/oauth/whoami`, which
+answers with the user a token resolved to and the scopes its grant currently carries. It is there so
+the guard has a real call site and so you have something to curl with a fresh token while checking a
+deployment. Delete it once you have a real protected surface, or keep it; it grants a connector
+nothing it did not already have by holding the token.
+
+`resolveOAuthBearer` puts the user on `req.user` and the grant on `req.oauthGrant`, and labels the
+request `req.authStrategy = 'oauth'`. That label is why an OAuth access token **fails**
+cap-users' `requireApiKey`, whose whole purpose is to demand an independently revocable key.
+
+A request with no `Authorization` header passes *through* the resolver untouched, so it can be
+mounted on a router that also serves anonymous traffic; gating is `requireOAuth`'s job.
+
+`requireOAuth` answers RFC 6750: **401** with the resolver's `WWW-Authenticate` challenge when there
+is no usable token, and **403** with `error="insufficient_scope"` and a `scope` parameter naming what
+the route requires when the token is valid but the grant is short. The challenge is not configured
+twice — the resolver writes it onto the request and the gate reads it back, so the two halves cannot
+disagree about where a client should look next. A gate mounted with no resolver in front of it
+refuses everything with a bare `Bearer`, which is the visible symptom of that mistake.
+
+**The grant is the authority, not the token.** Scopes are read off `oauth-grants` on every request,
+so a consent narrowed a moment ago binds a token minted under the wider set, with no revocation
+involved.
+
+Do not mount `resolveOAuthBearer` on a router that already carries cap-users' `resolveBearer` — both
+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.
+
+
+## Disconnecting — `/connections` and soft revocation
+
+`/connections` is mounted for you, gated by cap-users' `requireAuth`. It lists what this user has
+connected, states what a connected application actually reaches, and sends every disconnect through a
+confirmation page. **What it needs from you is a link**, from wherever your account settings live —
+nothing else points at it.
+
+Three things on that screen are load-bearing rather than layout, and a redesign has to keep all three.
+
+**The account-coverage statement.** A grant is keyed on the *user*, so a connected application reaches
+every account that user reaches, present and future. Somebody reading a list of client names will
+otherwise assume a connector reaches only the account they were looking at when they approved it. The
+consent screen says this before the Approve button; this screen says it above the list.
+
+**The "previously connected" section.** Revocation is soft, and the audit trail is why. A screen that
+showed only live grants would hide the ended ones from the person who wants them: the user who just
+disconnected something and wants to see that it stuck, and the user working out what a connector did
+last month. It is a quiet secondary section, because a disconnected client is history rather than
+inventory.
+
+**A dedicated confirmation page, not an inline delete.** `GET /connections/:grantId/disconnect`
+renders and changes nothing; only the `POST` revokes. Disconnecting is not undoable and its
+consequence — an agent that stops mid-conversation, and the whole flow to walk again — is not visible
+from a row in a list. A `GET` that revoked would also fire on a link prefetch or a restored tab.
+
+### What a revoke actually writes
+
+```ts
+await revocationService.revokeGrant(userId, grantId, 'user_revoked');
+```
+
+The grant record is end-dated with a reason **first**, then every live `oauth-access` and
+`oauth-refresh` row for that client is end-dated too. Both writes lock the client out on their own —
+the guard needs a live grant *and* a live token row — so ending the grant first makes the lockout one
+write, and a token sweep that fails halfway is safe to retry against a client that is already refused.
+
+Nothing is deleted. **The rows that stay behind are the point**, and they are what distinguishes a
+revoked client from one that never connected: `findAllByUser(userId, { includeEnded: true })` returns
+the ended rows for the first and nothing at all for the second.
+
+But do not read revocation *off* those rows, in either direction. An ended row does not mean revoked —
+expiry end-dates a row on the first read past its deadline. A live row does not mean connected —
+rotation leaves the superseded refresh row deliberately active, so presenting it again reads as reuse
+rather than as a typo. **The signal is `grant.ended_at` and `grant.ended_reason`**, which is what the
+screen and the guard both read.
+
+### The compromised-client case
+
+```ts
+await revocationService.revokeClient(clientPublicId, 'client_revoked');
+```
+
+A client and nothing else — it finds its own users. A token's identity key is
+`"<publicId>|<hash>"`, so everybody that client ever reached is a left-anchored prefix away, and
+cap-users' `findAllByDomainAndKeyPrefix(domain, keyPrefix, opts)` runs that scan behind the
+`IdentityStore` port. The boundary at the top of this document is unchanged: the query is still
+cap-users', by prefix exactly as it is by user id.
+
+Every one of those users' grants for that client ends, and no other client's does — the match is on
+the whole `client_public_id`, never a prefix of it. The result carries one entry per connection
+actually broken, so its length is how many people were disconnected rather than how many the scan
+turned up.
+
+Two details worth knowing before you read the code:
+
+- **The scan includes end-dated rows.** An idle connection's access and refresh rows are both swept
+  by the expiry rule while its grant stays perfectly alive, so a live-rows-only enumeration would
+  report that nobody uses a client half your users have connected.
+- **A malformed public id throws** rather than sweeping nothing. During an incident, a typo that
+  reads as "no users are affected" is the worst available answer. Pass the twelve-character
+  `publicId` from the client registry, not the `client_id` URL.
+
+### The client-driven case — `POST /oauth/revoke`
+
+RFC 7009's endpoint, mounted for you on the same router as `/oauth/token` and needing no session.
+It is the third of the three ways a connection ends, and the only one a piece of software rather than
+a person starts: a connector hands a token back because the user disconnected on *its* side.
+It takes `token` and `client_id`, as a form or as JSON, plus an optional `token_type_hint`.
+
+**Which token ends what is the decision to know about, and the two halves are deliberately
+asymmetric.**
+
+- **A refresh token ends the whole grant**, recorded with the reason `client_requested`. RFC 7009
+  §2.1 only says a server SHOULD do this; here the grant is the unit of connection, and a connector
+  calling this on user-disconnect wants the connection gone rather than one credential of it.
+- **An access token ends only its own row**, and §2.1's MAY is declined. Rotation does not end-date
+  the superseded *access* row, so the access token from before a refresh stays live until its TTL. A
+  tidy client that hands that old token back right after refreshing is doing exactly what this
+  endpoint is for — and under the MAY it would destroy the connection it had just renewed.
+
+**Every token gets `200` with an empty body** (§2.2): revoked, already invalid, expired, never
+issued, or belonging to a different client. There is no way to report that last one without
+confirming the token exists, so it takes the same answer as the rest. Do not add a body here to help
+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.
+
+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.
+
+## Configuration
+
+| Variable | Default | Notes |
+|---|---|---|
+| `OAUTH_ISSUER_URL` | — | Required at boot. https, or localhost for development. |
+| `OAUTH_RESOURCE_URL` | the issuer | The protected surface, as clients enter it. |
+| `OAUTH_SCOPES_SUPPORTED` | `profile email offline_access` | Without `offline_access` no client can request a refresh token. |
+| `OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `900` | Clamped to 60–3600, with a boot warning. |
+| `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_DEVICE_CODE_ENABLED` | `false` | Not implemented yet; named so the flag has one home. |
+| `OAUTH_DOCUMENTATION_URL` | — | Echoed into both documents. |
+
+All of it is read **once at boot**, so a running process has one answer and a clamp warns once.
+
+### Why token lifetimes are what they are
+
+A short access token is usually argued for on the grounds that revocation is otherwise slow.
+**That argument does not apply here.**
+Every request performs an active-only identity lookup, and a revoke writes `endedAt`, so revocation takes effect on the client's very next request whatever the stated lifetime.
+The only pressure on the access token's lifetime is blast radius if one leaks, which is why fifteen minutes is comfortable.
+
+The refresh token is long and *sliding*: each rotation mints a token with a fresh 90 days, so a connector in daily use never expires while one abandoned for a quarter does.
+
+## Key files
+
+| File | What it is |
+|---|---|
+| `prisma/schema/oauth-clients.prisma` | The `oauth_clients` table |
+| `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. |
+| `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 |
+| `views/oauth-disconnect-confirm.hbs` | The confirmation page a disconnect goes through |
+| `styles/oauth-server.css` | The `consent-*` and `connection-*` classes. Add it to your stylesheet entry point. |
+
+## Package exports
+
+`@boopkit/cap-oauth-server` provides:
+
+- `createClientRegistryService(delegate, options)` — `registerDynamic`, `resolveMetadataDocument`, `registerStaticClient`, `findByClientId`, `findByPublicId`, `suspend`, `unsuspend`, `updateRegistration`, `deleteRegistration`, `pruneAbandonedClients`
+- `matchRedirectUri(registered, presented)` and `matchesAnyRedirectUri(list, presented)`
+- `generateClientPublicId()`, `isValidClientPublicId(value)`
+- `buildAuthorizationServerMetadata(config)`, `buildProtectedResourceMetadata(config)`
+- `createDiscoveryRouter(config)`, `createRegistrationRouter(options)`, and the handler-set factories behind both
+- `createRegistrationRateLimiter(options)`
+- `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`
+- `createRevocationService(options)` — `revokeGrant`, `revokeClientForUser`, `revokeClient`
+- `createRevocationRouter(options)` — `POST /oauth/revoke`, and `createRevocationHandlers` behind it
+- `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
+- `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`
+- `ACCOUNT_COVERAGE_STATEMENT`, `REVOKED_BY_USER`, `REVOKED_BY_CLIENT`, `REVOKED_CLIENT_WIDE`
+- `ClientRegistryError` / `isClientRegistryError`, `OAuthError` / `isOAuthError`, `isStaleWriteError`
+
+## What is not here yet
+
+Named so nobody debugs their absence:
+
+- **Per-token audience binding.** A `resource` indicator is accepted, carried through the
+  authorization code and recorded on the grant, but no token carries an audience and nothing enforces
+  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.
+
+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.