@o3co/create-auth-provider 0.14.0 → 0.16.0

package/templates/standalone/README.md

@@ -1,21 +1,85 @@
 # @o3co/auth-provider-standalone
 
+Last updated: 2026-09-26
+
 Deployable server template for auth.provider. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-provider`.
 
+## Responsibility
+
+**Role.** The composition root and the starting point for a deployment. It is
+not a library: nothing imports it. `@o3co/create-auth-provider` copies it into
+a new project, and from then on the operator owns and edits the copy. It sits
+on top of the packages: it composes `@o3co/auth-provider-oauth`, `-session`,
+the Google and generic OpenID Connect federation adapters, `-federation-grants`,
+`-redis` and `-foundation` over `@o3co/auth-provider-core`.
+
+**Owns** the choices that are specific to one deployment:
+
+- which modules are composed, in what order, and which adapter fills each
+  store slot — [`src/buildModules.mts`](src/buildModules.mts) (see
+  [Module Composition Order](#module-composition-order));
+- the modules only this scaffold has — the signing key store, the client and
+  user repositories, the audit sink, the one shared Redis connection, the
+  in-memory user-session stores, code repository and federation token store,
+  and the federation config bridges — [`src/modules.mts`](src/modules.mts).
+  They are the scaffold's rather than a package's because each builds its
+  component from this template's configuration sections; a deployment that
+  wants another source wires its own module of the same shape;
+- where configuration comes from and how its layers stack —
+  [`src/configPath.mts`](src/configPath.mts) and [`config/`](config/);
+- the host process: the Express app, its security headers and startup —
+  [`src/app.mts`](src/app.mts); the health, readiness and metrics routes, the
+  composed router and core's terminal error handler after them, in the order
+  they are mounted — [`src/routes.mts`](src/routes.mts); the listener, which logs `server_listening`
+  (info, `port`) once its socket is bound, fails boot with the bind error
+  when it cannot be, and logs any later server error as `server_error`
+  (error) — [`src/listen.mts`](src/listen.mts). Every error this code logs — an unhandled
+  request error, the shared Redis connection's `error` event, a failed
+  shutdown — is logged as core's
+  [`loggableError`](../../packages/core/README.md#logger) projection, never the
+  error, which can carry what an upstream or Redis said (the connection's
+  error carries the `AUTH` handshake, password included, when the server
+  refuses it);
+- the concrete logger and audit stream (pino) —
+  [`src/logger.mts`](src/logger.mts) — and the metrics
+  ([`src/metrics.mts`](src/metrics.mts));
+- process lifecycle: signal handling with a drain deadline —
+  [`src/shutdown.mts`](src/shutdown.mts);
+- packaging: the `Dockerfile`, the compose files, the `Makefile`;
+- its tests: `src/__tests__/`, which `pnpm run test` and `make test` run against
+  this composition, and `tests/`, a separate black-box API suite with its own
+  `package.json`, run against a server that is already up (`API_BASE_URL`).
+  Among what `src/__tests__/` holds: every module this template can turn on
+  boots together and keeps the contracts that exist only when they meet — one
+  discovery document, each module's body rules in either mount order, a store
+  or repository outage answered 503 and logged once — pinned by
+  `all-modules-composition.test.mts`.
+
+**Does not own** the HTTP API, the grants, the token format, how each store
+behaves, or the config schema — the packages do. Change those upstream, not
+here.
+
+**Why separate.** Everything above is a per-deployment decision, so it is kept
+out of the published libraries and put in a tree the operator is expected to
+modify. It is `"private": true` and never published itself; it reaches users
+only through the scaffolder. A scaffolded copy carries this README too; its
+relative links into `../../docs` and `../../packages` resolve only inside this
+repository.
+
 ## Requirements
 
 - **Node.js** `>=22.0.0`
 - **`bcrypt` native binary**: this template depends transitively on `bcrypt@6.x`, which ships **prebuilt N-API binaries** for `darwin-arm64`, `darwin-x64`, `linux-x64` (glibc and musl), `linux-arm64` (glibc and musl), `linux-arm`, `win32-x64`, and `win32-arm64`. On these platforms `pnpm install` succeeds without compiling from source, and no extra toolchain is required (the `darwin-*`, `node:*-alpine`, and `node:*-bookworm` images all match a shipped prebuild). On platforms or libc/arch combinations that have no matching prebuild, `pnpm install` falls back to compiling, which then requires a C++ compiler and Python (the standard Node.js native-addon toolchain): Debian/Ubuntu `apt-get install build-essential python3`, Alpine `apk add make g++ python3`, macOS `xcode-select --install`. The pnpm 10 `onlyBuiltDependencies` allowlist for `bcrypt` lives in `pnpm-workspace.yaml` — pnpm ≥10.29 reads it only from there, in single-package projects too. `create-auth-provider` writes that file into the project it scaffolds (inside this monorepo, the allowlist sits in the workspace root's `pnpm-workspace.yaml`); without it a fresh `pnpm install` silently skips the install hook on those platforms.
 - **Redis 7.2 LTS or later** for any Redis-backed adapter (refresh token family store, code repository, federation token store, session store). The `pExpireGT` flag pair on which several adapters depend was introduced in Redis 7.0+; 7.2 LTS is the tested floor. Tested against AWS ElastiCache for Redis 7.2, Upstash Redis, Redis Cloud 7.2, and self-managed `redis:7.2-alpine`.
-- **ioredis** `^6.0.0` (direct runtime dependency). Every `@o3co/auth-provider-redis` adapter this template wires — refresh-token families, authorization codes, rate-limit counters, the access-token denylist, the user-session stores, the federation-token store — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica (`makeIoredisClients`). The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
+- **ioredis** `^6.0.0` (direct runtime dependency). Every `@o3co/auth-provider-redis` adapter this template wires — refresh-token families, authorization codes, rate-limit counters, the access-token denylist, the replay seen-set, the user-session stores, the federation-token store, the consent stores and the federation-grant stores — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica. The same module provides the client of every other store the Redis package ships — the device-code store and the WebAuthn challenge store — so a deployment that adds the device grant or WebAuthn to `buildModules.mts` with a Redis store finds its client there. The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
 
 ## First-party clients
 
-`GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
+For a client marked `firstParty: true`, `GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
 
 That is a coherent model for a **first-party** OP — one where every registered client is operated by you — and it is coherent nowhere else. A page you do not control can force a top-level navigation to `/authorize?client_id=X&redirect_uri=...&code_challenge=<theirs>`, a logged-in user's browser mints a code bound to *their* session, it is delivered to X's registered `redirect_uri`, and whoever chose the `code_challenge` redeems it for tokens carrying that user's identity.
 
-So the assumption is enforced rather than assumed. A client must carry `firstParty: true` in its registration to use `/authorize`; anything else is refused with `unauthorized_client`. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
+So the assumption is enforced rather than assumed. Every other client — one with no `firstParty` field and one carrying `false` alike — goes through the consent step: the user is asked on your consent page before a code is minted. That step needs a consent store, and the template ships none (`CONSENT_STORE_ADAPTER=none`), so on the defaults such a client is refused at `/authorize` with `unauthorized_client`; see [Consent Store](#consent-store) to serve it. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
 
 ```yaml
 # config/clients.yaml
@@ -31,9 +95,9 @@ A machine client can authenticate with a key instead of a shared secret (#484):
 [oauth package README](../../packages/oauth/README.md#client-authentication-private_key_jwt-rfc-7523-22).
 Nothing secret lives in `clients.yaml` for such a client.
 
-**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident. The step that changes the former is a consent screen, tracked separately.
+**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident.
 
-**Migrating.** Registrations that predate the field are refused at `/authorize` until you mark them — a client with no `firstParty` field and one carrying an explicit `false` are treated alike. Mark every client you operate before pointing it at `/authorize`; there is no admit-with-warning window. The one-time `oauth.authorize.allowUnmarkedClients` migration flag was removed before it ever shipped in a release, and a config or environment still setting it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
+**Unmarked registrations.** A registration without the field is not first-party: on the defaults it is refused at `/authorize` until you mark it, with no admit-with-warning window. Mark every client you operate before pointing it at `/authorize`. `oauth.authorize.allowUnmarkedClients` is not a setting: a config or environment that sets it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
 
 ## Multi-replica deployments
 
@@ -41,9 +105,9 @@ The [operator runbook](../../docs/operator-runbook.md) covers the operational si
 
 When running multiple instances of the standalone server behind a load balancer, point `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
 
-**Set `HTTP_TRUST_PROXY` to your proxy's address behind a load balancer.** It defaults to `false`, which makes `req.ip` the *load balancer's* address rather than the client's. Every rate limit keyed by IP — the OAuth endpoint limiters and the `POST /session/login` brute-force guard — then shares **one bucket across all users**: the first 20 login attempts from anyone exhaust the window and every subsequent user gets `429`. The failure reads like an attack rather than a misconfiguration, which is what makes it expensive to diagnose at 3am. Set it whenever anything terminates TLS or proxies in front of this service, and make sure that hop is the one setting `X-Forwarded-For`.
+**Set `HTTP_TRUST_PROXY` to your proxy's address behind a load balancer.** It defaults to `false`, which makes `req.ip` the *load balancer's* address rather than the client's. Every rate limit keyed by IP — the OAuth endpoint limiters and the `POST /session/login` brute-force guard — then shares **one bucket across all users**: the first 20 login attempts from anyone exhaust the window and every subsequent user gets `429`. The failure reads like an attack rather than a misconfiguration, which is what makes it expensive to diagnose at 3am. Set it whenever anything terminates TLS or proxies in front of this service, and make sure that hop is the one setting `X-Forwarded-For`. An audit event with no `ip` means the request's address was not an address — `req.ip` came from an `X-Forwarded-For` that held something else — so check that `HTTP_TRUST_PROXY` trusts only the hop that sets the header.
 
-Since #292 it takes four shapes, all of them Express's own:
+It takes four shapes, all of them Express's own:
 
 | Value | Meaning |
 |---|---|
@@ -56,7 +120,7 @@ Since #292 it takes four shapes, all of them Express's own:
 
 An allowlist is a network control, not a cryptographic one. The edge must also **strip** inbound `X-Forwarded-*` headers rather than appending to them, and the hop between it and this process must not be reachable by anyone able to spoof a source address.
 
-**Point `rateLimiter.adapter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. Since #270 the login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `rateLimit.login`; both adapters seed their own `limits.login` from it, so there is nothing to restate.
+**Point `rateLimiter.adapter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. The login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `rateLimit.login`; both adapters seed their own `limits.login` from it, so there is nothing to restate.
 
 **Behind a BFF, raise `limits.token` before you need to.** The OAuth-endpoint
 rate limits key on `req.ip` (`packages/core/src/ratelimit/guard.mts` builds the
@@ -101,7 +165,7 @@ raising it globally to accommodate one topology would weaken it for the other.
 Put the throttling that protects the BFF's *own* users in front of the BFF,
 where per-user identity still exists.
 
-**Set `DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, DPoP proof-replay detection forking. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too; before #455 they booted under `multi`. Since #474 that includes express-session's own store under `SESSION_STORAGE_TYPE=memory` and the login / WebAuthn-options rate limiters when no shared `rateLimiter` is wired; with the mode unset those three warn instead (see the operator runbook). With the mode unset you get one `replica_unsafe_adapters` warning at boot instead; with `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica.
+**Set `DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, a single-use client assertion or WebAuthn challenge replayable once per replica. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `RATE_LIMITER_ADAPTER=memory`). With the mode unset nothing is refused: every one of them is listed in a single `replica_unsafe_adapters` warning at boot. (The login and WebAuthn-options routes carry per-process fallback limiters that warn on their own, but only in a composition that wires no `rateLimiter` at all, which this template never does; see the operator runbook.) With `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica. This template does not install DPoP; a composition that adds it records every accepted proof in the same replay seen-set as `private_key_jwt` (`REPLAY_SEEN_SET_ADAPTER`), so it gets the same answer — `memory` is refused under `DEPLOYMENT_MODE=multi` and listed in the unset-mode warning, and the shipped `redis` shares DPoP's records across replicas — see the dpop package's [operator requirements](../../packages/dpop/README.md#operator-requirements).
 
 Be aware of what this check *cannot* do: if you scale to N replicas without ever setting `DEPLOYMENT_MODE`, nothing fails. A process holding all its state in its own memory has no shared medium through which to notice peers — the condition is undetectable from inside exactly when it is true. Set the variable as part of scaling, not after something breaks.
 
@@ -111,39 +175,101 @@ Other multi-replica considerations covered by the default modules:
 
 - The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORAGE_TYPE=redis` with `SESSION_STORAGE_REDIS_URL` (`session.storage.redis.url`) pointing at the shared instance.
 - The user-session stores switch on `userSessionStores.adapter = "redis"` (`USER_SESSION_STORES_ADAPTER`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` configures.
-- The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. The older `repositories.code.type = "redis"` (`CLIENT_CODE_TYPE`) switch is still honoured with a deprecation warning at boot. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is still bound by `config/application.conf` but nothing reads it: the Redis code repository has run on the shared connection since the `{ endpointUri }` builder shape was retired, so there is one Redis URL for every adapter and that variable is legacy.
+- The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. `oauth.code.adapter` wins; the deprecated `repositories.code.type` (`CLIENT_CODE_TYPE`) is read, with a `config_key_deprecated` warning at boot, only when it is unset — which the shipped `config/application.conf` never leaves it. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is bound by `config/application.conf` but nothing reads it: the Redis code repository runs on the shared connection, so there is one Redis URL for every adapter.
 - The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `replaySeenSet.adapter` (`REPLAY_SEEN_SET_ADAPTER`); the template ships `"redis"` on the shared connection, and `memory` is refused under `DEPLOYMENT_MODE=multi` because a captured client assertion would replay once per replica.
 - The consent step for clients that are not first-party (#527) switches on `consentStore.adapter` (`CONSENT_STORE_ADAPTER`). It is off (`none`) by default; `memory` is refused under `DEPLOYMENT_MODE=multi`, because a consent granted on one replica would be asked for again on every other and a consent page's parked request would be unknown to the replica that receives the answer. `redis` (#561) keeps both on the shared connection. See [Consent Store](#consent-store).
 - The federation token store defaults to memory. Set `FEDERATION_TOKEN_STORE_TYPE=redis` (`federationTokenStore.type = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`. See [Federation Token Store](#federation-token-store).
+- Federation grants (#593), when enabled, keep two more stores: the grants themselves (`FEDERATION_GRANT_STORE_ADAPTER`) and acquisition's records (`FEDERATION_GRANT_INTENT_STORE_ADAPTER`). Both ship `redis` on the shared socket; `memory` for either is refused under `DEPLOYMENT_MODE=multi`, and Redis grants beside memory user-session stores are refused on any replica count, because the grants would outlive the boundary that ends them. See [Federation Grants](#federation-grants).
 
 ## Usage
 
+`pnpm run debug` runs `src/app.mts` under `tsx watch` on this machine. It reads
+no `.env` file — its configuration is `config/` plus the environment of the
+shell that starts it — and it does not boot until that environment supplies:
+
+- `OAUTH_JWT_ISSUER` — this server's origin (`http` is accepted for a loopback
+  host);
+- a signing key pair, `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH`
+  (see [OAuth JWT](#oauth-jwt));
+- `SESSION_SECRET`, at least 32 bytes;
+- `CLIENT_USER_AUTHENTICATE_URL` and `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` —
+  your user service ("the Store"), `https`, or `http` on a loopback host. Boot
+  checks their form, not that anything answers; logins fail until something
+  does (see [User Repository](#user-repository));
+- a Redis it can reach at `redis://localhost:6379`. The shipped configuration
+  keeps the browser session store there (`SESSION_STORAGE_REDIS_URL`), and
+  opens one shared connection (`REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`) for the
+  refresh-token families, the authorization codes, the access-token denylist
+  and the replay seen-set — and for the user-session stores, with the setting
+  below.
+
+Plain HTTP also needs `SESSION_SECURE=false` and a session cookie name without
+the `__Host-` prefix (see [Session](#session)). And set
+`USER_SESSION_STORES_ADAPTER=redis`: the browser session store is in Redis, the
+user-session stores default to memory, and `tsx watch` restarts the process on
+every save — split, a restart leaves the browser's session pointing at a
+`UserSession` that is gone, and `/authorize` loops (see [Docker](#docker)).
+
+The key pair below is generated with Node, which every machine running this
+already has. `openssl genpkey -algorithm ed25519` works too, with OpenSSL 1.1.1
+or later — not with the LibreSSL that macOS ships as `/usr/bin/openssl`.
+
 ```bash
-# Install dependencies
 pnpm install
 
-# Copy environment file and fill in required values
-cp .env.example .env
+# A signing key pair (Ed25519) and a local Redis
+node -e '
+const { generateKeyPairSync } = require("node:crypto");
+const fs = require("node:fs");
+const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+fs.writeFileSync("jwt-private.pem", privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
+fs.writeFileSync("jwt-public.pem", publicKey.export({ type: "spki", format: "pem" }));
+'
+docker run -d --name auth-redis -p 127.0.0.1:6379:6379 redis:7.2-alpine
+
+# What boot requires (replace the user-service URLs with your Store's)
+export OAUTH_JWT_ISSUER=http://localhost:3000 \
+  OAUTH_JWT_PRIVATE_KEY_PATH=./jwt-private.pem \
+  OAUTH_JWT_PUBLIC_KEY_PATH=./jwt-public.pem \
+  SESSION_SECRET="$(openssl rand -hex 32)" \
+  SESSION_SECURE=false SESSION_NAME=auth.sid \
+  USER_SESSION_STORES_ADAPTER=redis \
+  CLIENT_USER_AUTHENTICATE_URL=http://localhost:8080/authenticate \
+  CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=http://localhost:8080/authenticate-by-token
 
 # Start in development mode (hot reload)
 pnpm run debug
 
-# Build and start in production mode
+# Build, then run the compiled server (CONFIG_ENV or NODE_ENV selects config/<env>.conf)
 pnpm run build
-pnpm start
+pnpm run start
 ```
 
+`.env` is read only by the compose files (`env_file`). `make dev`
+(`docker compose up --build`) runs the same debug server in a container beside
+a Redis service, with its environment from `.env` — copied from
+`.env.example`, whose Redis URLs name that service. Values there are resolved
+inside the container, which holds no key files: only `src/`, `config/`, the
+package manifests and what installing and building them produced. A key path or
+a `localhost` URL that works on the host does not work there. The deployable
+image and its compose file are under [Docker](#docker).
+
 ## Configuration
 
 Configuration is loaded from `config/application.conf` (HOCON format). Each value can be overridden with the corresponding environment variable.
 
 ### Environment-specific config overlay
 
-`src/app.mts` loads configuration in two layers:
+`src/app.mts` loads configuration in three layers, highest precedence first:
 
-1. **`config/application.conf`** — base defaults for the app.
-2. **`config/{ENV}.conf`** — overlay for the current environment, where
+1. **`config/{ENV}.conf`** — overlay for the current environment, where
    `ENV = CONFIG_ENV || NODE_ENV || "development"`.
+2. **`config/application.conf`** — this deployment's settings.
+3. **`reference.conf` of `@o3co/auth-provider-core`** — the library defaults,
+   resolved from the installed package
+   (`import.meta.resolve("@o3co/auth-provider-core/reference.conf")`, in
+   [`src/configPath.mts`](src/configPath.mts)). A key neither file above sets
+   takes its value from here.
 
 Values in the overlay take precedence over `application.conf`. The scaffold
 ships with `development.conf` and `production.conf`. To add another
@@ -181,7 +307,7 @@ fail fast rather than silently falling back to defaults.
 | `OAUTH_CIMD_STALE_IF_ERROR_MS` | `300000` | How long a registration already validated is still served after a revalidation that failed for a reason that is not the document's (a DNS blip, a 5xx, a timeout) — an outage should not break a working client. A document that was *rejected* is dropped immediately. `0` disables it. |
 | `OAUTH_CIMD_NEGATIVE_CACHE_MS` | `60000` | How long a refusal is remembered, so the same `client_id` is not resolved and fetched again on every request. Short, so a client that fixes its document is not locked out. |
 | `OAUTH_CIMD_MAX_CONCURRENT_FETCHES` | `8` | How many documents may be in flight at once, across every `client_id`. Bounds what an unauthenticated caller can make this server dial. |
-| `OAUTH_JWT_KID` | `v0` | Key ID included in the JWT header |
+| `OAUTH_JWT_KID` | `v0` | Key ID included in the JWT header. 1 to 256 characters with no control character; anything else fails boot, including a variable exported but empty (which used to sign under the kid `""`; tokens issued that way are refused once it is corrected, so their users sign in again) |
 | `OAUTH_JWT_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
 | `OAUTH_JWT_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
 | `OAUTH_JWT_PUBLIC_KEY` | — | PEM-encoded public key |
@@ -213,7 +339,7 @@ every relying party must be handed the shared secret — which also lets it
 |---|---|---|
 | `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` | `3600` | Access token lifetime in seconds that every grant mints when the request asks for none. Whole positive number, at most one year (`31536000`). |
 | `OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN` | the default | The most a token-exchange request's `expires_in` parameter can obtain; a larger request is clamped to it. Unset means the default, so no token is extended unless you set this. A default above it is a boot failure naming both keys. It also bounds how long an exchanged token outlives a revocation at a resource server that validates it offline. |
-| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | **Deprecated** alias of `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` (config key `oauth.accessToken.expiresIn`, of `oauth.accessToken.defaultExpiresIn`), read only while the new one is unset. Move the value to the new variable. |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | **Deprecated** alias of `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` (config key `oauth.accessToken.expiresIn`, of `oauth.accessToken.defaultExpiresIn`), read only while the new one is unset; while it still decides the default, boot logs `config_key_deprecated` (warn). Move the value to the new variable. |
 | `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | Refresh token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
 
 Exporting one of these as an empty string is a boot failure, not a fallback:
@@ -335,6 +461,7 @@ all — no headers, no `Vary`, nothing changed.
 | `FEDERATIONS_GOOGLE_CLIENT_ID` | — | Google OAuth client ID |
 | `FEDERATIONS_GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
 | `FEDERATIONS_GOOGLE_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/google/callback` | Google OAuth callback URL |
+| `FEDERATIONS_GOOGLE_ACCESS_TYPE` | unset (`offline`) | `offline`: every sign-in shows Google's consent screen and every session gets a refresh token. `online`: consent on the first sign-in only, and no refresh token at all. See [federation-google](../../packages/federation-google/README.md#refresh-tokens-and-the-consent-screen) |
 
 ### OIDC Federation (any OpenID Connect provider)
 
@@ -391,6 +518,8 @@ is documented in [its README](../../packages/federation-oidc/README.md).
 | `CLIENT_USER_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
 | `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
 | `CLIENT_USER_LINK_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store links a federated identity at (#482); enables `?link=1` on the federation start route. **https required** |
+| `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store answers who holds an upstream identity at (#613, federation grants' check 5). With it, declare what the Store covers in `repositories.user.http.federatedIdentityLookupCoverage` (HOCON). **https required** |
+| `CLIENT_USER_BEARER_TOKEN` | — | Optional. The credential this server presents to the Store: every Store request carries `Authorization: Bearer <token>`. A bare token (no `Bearer ` prefix) of at least 32 bytes — `openssl rand -hex 32`. Unset, no `Authorization` header is sent (see below) |
 | `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
 | `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
 
@@ -403,11 +532,42 @@ only for a loopback host — `localhost`, an address in `127.0.0.0/8`, or `[::1]
 deployment does not control end to end. Boot fails if either URL, the timeout,
 or the response cap is unusable, rather than at the first login attempt.
 
+Each URL must be the endpoint that answers, not one that redirects: no request
+follows a `3xx`, so a URL that redirects fails every call — see
+[What the Store must enforce itself](../../packages/foundation/README.md#what-the-store-must-enforce-itself).
+
+**Who may call the Store.** What the token-based login and account linking
+send is an identifier, not a secret, so a Store that answers any caller
+resolves a known identity to its user — or links one to any account — for
+anyone who can reach it. Set `CLIENT_USER_BEARER_TOKEN` and have the Store
+answer every request whose `Authorization` is not exactly `Bearer <that token>`
+with `401` and `WWW-Authenticate: Bearer error="invalid_token"` (or `403` and
+`error="insufficient_scope"`). The one token goes to every Store URL above, so
+those endpoints must be one trust domain. With `CLIENT_USER_TYPE=http` — this
+template's default — boot fails if the token is weaker than 32 bytes
+(measured like `SESSION_SECRET`), malformed, or exported but empty; it appears
+in no error this server throws. With that challenge, a token the Store does not
+accept is an outage on every Store call: logins answer
+`503 temporarily_unavailable` and log an error naming the refused credential,
+not the token, and so do federation-grants connects
+(`federation_grant_callback_unavailable`). A `401` or `403` without the
+challenge keeps its old meaning — at login "no such user", at a `?link=1`
+link a refusal, and at the federation-grants identity lookup an outage like
+any other non-`2xx` — so a mismatch then shows only as every login failing
+and every link refused; and a Store must not put a `Bearer` challenge on a
+user's wrong password or a link it refuses. A Store that cannot be reached,
+closes the connection before a complete response, or answers with a malformed
+HTTP response is logged as such, with at most a transport code
+(`ECONNREFUSED`, `UND_ERR_SOCKET`, `ERR_SSL_WRONG_VERSION_NUMBER`, …), and
+never with what the transport quoted. Without the token, admit only this server to the Store
+by network policy or platform mutual TLS. Rotation, what each caller logs, and
+what the Store checks are in the same foundation README section.
+
 ### Code Repository
 
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); honoured with a boot warning |
+| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); read, with a `config_key_deprecated` warning at boot, only when `oauth.code.adapter` is unset — the shipped config sets it |
 | `CLIENT_CODE_ENDPOINT_URI` | — | Legacy; bound to `repositories.code.redis.endpointUri` but not read — codes use the shared `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` connection |
 | `CLIENT_CODE_PASSWORD` | — | Redis password for code storage |
 | `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | Default authorization code lifetime in seconds |
@@ -443,6 +603,139 @@ socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`.
 |---|---|---|
 | `CONSENT_STORE_ADAPTER` | `none` | Consent store for clients that are not first-party (#527): `none` (such clients are refused), `memory` (single replica) or `redis` (shared, #561) |
 
+### Federation Grants
+
+Offline delegation of an upstream IdP's tokens (#593): a user consents once
+that a client — a backend, an agent — may obtain access tokens for one
+upstream connection on their behalf, and the client obtains them over HTTP
+later, with the user not present. A grant **survives logout**; a credential
+change ends it through the subject-revocation service. Off by default, and
+off installs nothing. The routes and what each answer means are in the
+[package README](../../packages/federation-grants/README.md); what each IdP
+needs before it issues a refresh token is in
+[`docs/offline-access.md`](../../packages/federation-grants/docs/offline-access.md).
+
+| Variable | Default | Description |
+|---|---|---|
+| `FEDERATION_GRANTS_ENABLED` | `false` | Installs the routes, the two stores below and the subject-revocation service |
+| `FEDERATION_GRANTS_CONSENT_URL` | — | The deployment's consent page for grants: a path, or an absolute URL on the provider's origin. No default — enabling grants is a statement that the page exists, and boot refuses without it |
+| `FEDERATION_GRANTS_IDENTITY_LOOKUP` | `required` | Whether the connect callback refuses an upstream account already linked to another local user. `required` needs a user repository that covers every connection's registration (below); `unsupported` records that the check is not made |
+| `FEDERATION_GRANT_STORE_ADAPTER` | `redis` | Where grants live: `memory` (one replica; lost on restart, every user reconnects) or `redis` (the shared socket) |
+| `FEDERATION_GRANT_INTENT_STORE_ADAPTER` | `redis` | Where acquisition's records live — the intent a backend lodged, the consent challenge, the connect transaction: `memory` (one replica; a restart loses flows in progress and nothing else) or `redis` |
+| `FEDERATION_GRANTS_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused in production/staging and under `DEPLOYMENT_MODE=multi` unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` |
+| `FEDERATION_GRANTS_ALLOW_KEEP_ON_SUBJECT_REVOCATION` | `false` | Whether a subject-wide revocation may be *asked* to leave established grants standing. An allowance, not an instruction |
+| `REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX` | `fg:` | Key namespace of the Redis grant store |
+
+**Two things have no environment form**, because a list is HOCON's: the
+connections, and the encryption key ring. Write them in a deployment-owned
+layer — `config/production.conf`, say:
+
+```hocon
+federationGrants {
+  encryptionKeys = [
+    # The first key seals; every listed key opens. GRANT_KEY_2026_09 is a name
+    # you choose (openssl rand -base64 32), not a template override.
+    { id = "2026-09", key = ${GRANT_KEY_2026_09} }
+  ]
+  connections {
+    files {
+      federation = "entra-files"   # an enabled federations.<name> of type "oidc", with an app registration of its own
+      scopes = ["openid", "profile", "offline_access", "Files.Read"]
+      boundary = "production"
+      maxAccessTokenLifetime = 3600
+      # The grant flow's own callback on this provider's origin — not the
+      # federation's login callback.
+      callbackURL = "https://auth.example/session/federation-grants/callback/files"
+      allowScopeSubsets = false
+      identityClaims = ["oid", "tid"]
+    }
+  }
+}
+```
+
+**What boot refuses**, each named, rather than met by a user mid-flow: no
+consent page; a connection without `callbackURL`, on a federation that is not
+enabled, or on one whose adapter lacks the delegated capability — only the
+generic OIDC adapter has it, so a Google connection is a `type = "oidc"`
+federation; `required` with a user repository that does not cover a
+connection's registration; Redis grants beside memory user-session stores
+(`USER_SESSION_STORES_ADAPTER=memory` — the grants would outlive the boundary
+that ends them; both compose files set `redis`); the Redis grant store under
+`encryptionMode = "required"` with no key in the ring (the memory store seals
+nothing and needs none); `memory` for either store under `DEPLOYMENT_MODE=multi`.
+
+**The user repository.** Under `required`, boot asks the repository whether it
+covers each connection's registration, and the connect callback asks it who
+holds the upstream account. The template's `http` repository asks your Store
+(#613): set `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` to the
+endpoint, and declare what that endpoint covers — one entry per registration,
+with the claims the Store's strategy needs — in a HOCON layer:
+
+```hocon
+repositories.user.http.federatedIdentityLookupCoverage = [
+  { provider = "entra-files", issuer = "https://login.microsoftonline.com/<tenant>/v2.0",
+    clientId = "<the grants app registration>", requiredClaims = ["tid", "oid"] }
+]
+```
+
+Boot then holds every connection to it: one whose registration is not
+declared, or whose `identityClaims` misses a required claim, is refused by
+name. The wire contract the Store implements — and what "unlinked" obliges it
+to have checked — is in the
+[foundation README](../../packages/foundation/README.md#the-identity-lookup-613);
+the Store is not asked at boot. The bundled in-memory repository covers no
+registration. Without a covering Store, set
+`FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported` — the recorded decision not to
+refuse an upstream account another local user already holds. With no
+connection configured nothing is required.
+
+**Registering a client.** In `config/clients.yaml`, a confidential client that
+may hold grants names the connections it may ask for and where the browser
+may be returned. Neither its `allowedRedirectUris` nor `firstParty` grants
+either:
+
+```yaml
+worker:
+  tokenEndpointAuthMethod: "client_secret_basic"
+  clientSecret: "$2b$10$…"
+  allowedFederationGrantConnections: ["files"]
+  federationGrantRedirectUris: ["https://worker.example/connected"]
+```
+
+**The flow, from the client's side.** `POST /oauth/federation-grants`
+(client-authenticated) lodges an intent for a `sub` and answers a `grant_id`
+and a `connect_uri`; the client sends the user's browser there. The provider
+signs the user in if needed, shows your consent page, sends them to the
+upstream, and returns the browser to the client's `redirect_uri` with
+`grant_id` and `state` — never a token. The client then calls
+`/oauth/federation-grants/:grantId/token`, `/status` and `/revoke` with its
+own credentials and the user's `sub`, with no user present.
+
+**The consent page** is yours, same-origin with the provider, and its contract
+is `/oauth/consent`'s, so one page can serve both. `GET
+/session/federation-grants/consent?challenge=…` answers JSON: `client_id`,
+`client_name`, `connection`, `scopes`, `resource`, `grant_expires_in` (a
+duration after approval, not a date), `continues_after_logout` (which the page
+must show), and `expires_in` (what is left of the flow). `POST` with
+`challenge` and `decision` (`accept` | `deny`) answers `303` — to the upstream,
+or back to the client. Every acquisition and renewal goes through it.
+
+**The login page** is the one `ENDPOINTS_LOGIN_URL` names, reached with
+`redirect_to=<the connect link>`; it signs the user in and navigates back to
+that link unchanged, as it does for `/oauth/authorize`. Do not submit the link
+to `POST /session/login` as its `redirect_to`: that route's exact-match
+allowlist is for landing pages and refuses a per-flow handle.
+
+**Operating it.** Rotate the key ring by the procedure in the
+[operator runbook](../../docs/operator-runbook.md) — new key last, then first,
+old key kept 365 days. A shutdown gives cleanup 45 seconds while the feature
+is on — more if you raise `upstreamHardTimeoutMs`, `persistRetryBudgetMs` or
+`lockWaitMs`, since the allowance is their sum plus a margin — and both
+compose files give the process 60; see
+[Shutdown guarantees](#shutdown-guarantees). Disabling the feature is not
+revoking: grants stay in Redis until revoked, so end them first, and keep the
+keys and the revocation boundaries through any temporary shutdown.
+
 ### Redis Namespacing
 
 For multi-tenant Redis clusters, set deployment-specific key prefixes so two
@@ -466,37 +759,25 @@ Use values that include the deployment name, for example `tenant-a:ss:`,
 | `ENDPOINTS_LOGIN_URL` | `/login` | URL of the login page (for redirects) |
 | `ENDPOINTS_CONSENT_URL` | `/consent` | URL of the consent page a client that is not first-party is routed through, with `?challenge=<id>` (#527) |
 
-`ENDPOINTS_CLIENT_URL` and `ENDPOINTS_AUTH_CALLBACK_URL` were removed (IH-10) —
-no production consumer read them, and the config lines leaked values into
-`AppConfig` that nothing consumed. Federation callback URLs are configured
-per-provider (`FEDERATIONS_GOOGLE_CALLBACK_URL`).
+There is no deployment-wide client or callback URL: federation callback URLs
+are configured per federation (`FEDERATIONS_GOOGLE_CALLBACK_URL`,
+`FEDERATIONS_OIDC_CALLBACK_URL`).
 
 ## Module Composition Order
 
-`src/buildModules.mts` is the single source of truth for the manifest; this is its order. The boot planner resolves `requires` / `provides` topologically, so list position matters only where a module says so — `sessionStoreModule` must stay first, because it wires the `express-session` middleware every session-consuming route needs. Entries marked *adapter switch* are one of a memory/Redis pair, chosen by config; both provide the same slot, so exactly one is wired.
-
-1. **`sessionStoreModule`** (`@o3co/auth-provider-session`) — `express-session` middleware and its store (`session.storage.type`)
-2. **`oauthModule`** — `POST /oauth/token`, `POST /oauth/introspect`, `POST /oauth/revoke`, `GET /oauth/authorize`, and OIDC discovery when an issuer is configured
-3. **`oauthSessionModule`** — session grant (exchanges an authenticated session for a token)
-4. **`oauthAuthorizationModule`** — authorization-code and refresh-token grants
-5. **`jwksModule`** (`@o3co/auth-provider-core`) — `GET /.well-known/jwks.json` (or `oauth.jwt.jwksPath`); a signing provider publishes its verification keys whether or not an issuer is set
-6. **`sessionModule`** — `POST /session/login`, `POST /session/logout`, `GET/POST /session/oauth/federation/*`. `/session/logout` deletes the `UserSession` record (so `/oauth/introspect` and `/oauth/userinfo` stop honouring tokens minted from that session), the subject index and the federation entries — but it does **not** revoke refresh-token families; `POST /oauth/logout` is the endpoint that runs the full cascade. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
-7. **`googleFederationModule`** + **`googleFederationConfigModule`** — only when `federations.google.enabled = true`
-8. **`keyStoreModule`** — the signing key store from `oauth.jwt.signingKey`
-9. **`repositoriesModule`** — client and user repositories from `repositories.client` / `repositories.user`
-10. **`auditSinkModule`** — always wired; `audit.sink.type` picks `logger` (default) or `console`
-11. **`standaloneRedisClientsModule`** — the one shared ioredis connection; present whenever any switch below is `"redis"`
-12. **`redisFederationTokenStoreModule`** / **`inMemoryFederationTokenStoreModule`** — *adapter switch*: upstream federation tokens per session (`federationTokenStore.type`; see [Multi-replica deployments](#multi-replica-deployments))
-13. **`redisSessionStoresModule`** / **`inMemorySessionStoresModule`** — *adapter switch*: user-session stores (`userSessionStores.adapter`)
-14. **`redisRateLimiterModule`** / **`memoryRateLimiterModule`** — *adapter switch*: the rate limiter behind the OAuth endpoints and `POST /session/login` (`rateLimiter.adapter`)
-15. **`redisCodeRepositoryModule`** / **`inMemoryCodeRepositoryModule`** — *adapter switch*: authorization codes (`oauth.code.adapter`)
-16. **`redisAccessTokenDenylistModule`** / **`memoryAccessTokenDenylistModule`** — *adapter switch*: RFC 7009 access-token denylist (`accessTokenDenylist.adapter`)
-17. **`redisRefreshTokenFamilyStoreModule`** — refresh-token families; Redis unless a test override swaps in the memory store
-18. **`defaultRefreshTokenFamilyRotationModule`**, **`defaultRefreshTokenFamilyRevocationModule`** — rotation and revocation policies over the family store
+[`src/buildModules.mts`](src/buildModules.mts) is the single source of truth for which modules are composed and in what order — read it rather than a copy of it. The boot planner resolves `requires` / `provides` topologically, but it mounts routes and middleware in list order unless a module declares `before` / `after` — so position matters for anything that mounts. These are the rules to keep when you edit the list:
+
+1. **`sessionStoreModuleFor(config)` stays first.** It mounts the `express-session` middleware and declares no `before` / `after`, so its position in the list is what puts it ahead of every route that reads `req.session`. It is built from `config` so that `session.storage.type = "memory"` declares itself replica-unsafe.
+2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthModule` and any module of your own may all mount routes under `/oauth`. `oauthModule`'s router parses the bodies of its own routes only, so each module's requests reach its own parsers whatever the list order — provided every module under `/oauth` parses its own body and scopes its parsers to exactly its own paths, as the shipped ones do — a route (`router.all(path, parser)` or the route's own handler list), not `router.use(path, parser)`, which matches every path beneath `path` as well. The federation grants browser half orders itself after the session middleware with its own `after`.
+3. **One module per store slot.** Each adapter switch — `federationTokenStore.type`, `userSessionStores.adapter`, `rateLimiter.adapter`, `oauth.code.adapter`, `accessTokenDenylist.adapter`, `replaySeenSet.adapter`, `consentStore.adapter`, and the two federation-grant store switches — picks one of a memory / Redis pair. Both provide the same slot, so wiring both is a boot-time slot collision. `consentStore.adapter = "none"` wires neither, and the federation-grant stores are wired only while the feature is enabled.
+4. **The shared Redis connection comes with the first Redis-backed module.** `standaloneRedisClientsModule` opens the one ioredis connection every Redis adapter here uses, and is added whenever a composed module needs one. The refresh-token family store is on Redis in the shipped composition, so a deployment always has it; the in-memory family store is a test override (`overrides.refreshTokenFamilyModules`).
+5. **A federation adapter comes with its config bridge.** `googleFederationModule` with `googleFederationConfigModule` — only for an enabled `federations.google` section whose `type` is `google`, so a `type = "oidc"` section named `google` is not composed twice — and one `oidcFederationModule(name)` per enabled `type = "oidc"` section, with the one `oidcFederationConfigModule` they share. A bridge's provider throws when its section is absent, so the pair is included at composition time rather than gated inside it.
+
+`jwksModule` (from core) is always composed: a provider that signs tokens publishes its verification keys whether or not an issuer is configured. What each route module mounts is in its package's README. One behaviour to know when composing: `sessionModule`'s `POST /session/logout` deletes the `UserSession` record (so `/oauth/introspect` and `/oauth/userinfo` stop honouring tokens minted from that session), the subject index and the federation entries — but it does **not** revoke refresh-token families; `POST /oauth/logout` is the endpoint that runs the full cascade. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
 
 ## Built-in Routes
 
-`src/app.mts` mounts these on the host app ahead of the composed auth router, so they keep answering while the auth pipeline is degraded — which is when an operator needs them. The JWKS route is not one of them: `jwksModule` contributes it (see above).
+`src/routes.mts` mounts these on the host app ahead of the composed auth router, so they keep answering while the auth pipeline is degraded — which is when an operator needs them — and core's terminal error handler after all of them, so an error one of them lets through is answered as the auth routes' are (`500 server_error`, logged once as `unhandled_request_error`). The JWKS route is not one of them: `jwksModule` contributes it (see above).
 
 | Method | Path | Description |
 |---|---|---|
@@ -553,8 +834,8 @@ merely stored badly. The same applies to `.env`; keep both out of git.
 
 The production file also pins `SESSION_SECURE=true` and the `__Host-` cookie
 name in its `environment:` block, which wins over `env_file`. `.env.example`
-ships `SESSION_SECURE=false` so a plain-HTTP local run works, and this file
-requires that same `.env` — behind the TLS it assumes, a non-Secure session
+ships `SESSION_SECURE=false` so that a plain-HTTP compose run (`make dev`) does
+not trip the `__Host-` cookie check, and this file requires that same `.env` — behind the TLS it assumes, a non-Secure session
 cookie is the session handed to anyone who can read one plaintext hop.
 
 The image installs with `pnpm install --frozen-lockfile`, so a committed
@@ -564,7 +845,7 @@ the result. Rebuilding the same source then produces the same dependency tree.
 
 The production image sets `ENV HTTP_PORT=3000` and uses it for both `EXPOSE`
 and the Docker-native healthcheck against `/_healthcheck`. The HOCON config
-also reads `${?HTTP_PORT}` for `http.port`, so `app.listen()` and the
+also reads `${?HTTP_PORT}` for `http.port`, so the listener and the
 healthcheck cannot drift apart. To run on a different port:
 
 ```bash
@@ -621,7 +902,8 @@ changing the image.
 ```
 
 The failure's *reason* is deliberately absent from the body and goes to the log
-instead (`readiness_probe_failed`, with the full per-check detail). A driver
+instead (`readiness_probe_failed`, with each failing check's error as core's
+`loggableError` projection). A driver
 error reads `connect ECONNREFUSED 10.0.3.14:6379` — an internal host and port —
 and this endpoint is unauthenticated because an orchestrator has no credentials
 to present. Set `includeErrorDetail: true` on `createReadinessRouter` only when
@@ -637,9 +919,10 @@ rules.
 Probes are registered by whichever builder opened the connection, so the list
 reflects what this deployment actually wired: the shared ioredis client
 (`redis`) and the connect-redis session client (`session-store`) when the
-Redis adapters are selected, and **nothing at all** for a memory-only
-deployment — which is therefore always ready, because it has no dependency to
-be unready for.
+Redis adapters are selected, and **nothing at all** for a composition with no
+Redis-backed module — which would therefore always be ready, having no
+dependency to be unready for. The shipped composition is never that: its
+refresh-token families are always in Redis, so `redis` is always probed.
 
 `http.readinessTimeoutMs` (env `HTTP_READINESS_TIMEOUT_MS`, default `1000`)
 is the per-probe deadline. Keep it below the orchestrator's own probe timeout;
@@ -648,43 +931,22 @@ unready one.
 
 ## Adding Custom Modules
 
-To add a custom module, import it in `src/buildModules.mts` and include it in the `modules` array passed to `createApp`:
-
-```typescript
-// src/buildModules.mts
-import { myCustomModule } from "./modules/my-custom-module.mjs";
-
-export function buildModules(config: AppConfig, overrides: BuildModulesOverrides = {}): Module[] {
-  const googleEnabled =
-    (config.federations?.google as { enabled?: boolean } | undefined)?.enabled === true;
-
-  return [
-    oauthModule({ config }),
-    oauthSessionModule({ config }),
-    oauthAuthorizationModule({ config }),
-    sessionModule,
-    ...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
-    myCustomModule, // add here
-    overrides.keyStoreModule ?? keyStoreModule,
-    overrides.repositoriesModule ?? repositoriesModule,
-    overrides.storesModule ?? storesModule,
-  ];
-}
-
-// src/app.mts
-const handle = await createApp({
-  modules: buildModules(config),
-  bootstrapComponents: {
-    config,
-    pathResolver: import.meta.resolve,
-  },
-});
-
-app.use(handle.router);
-const server = app.listen(config.http.port);
-installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
+To add a custom module, import it in `src/buildModules.mts` and add it to the array `buildModules` returns. The boot planner resolves dependencies by what modules `require` and `provide`, but it mounts routes and middleware in list order wherever no `before` / `after` says otherwise. So position matters for middleware that other routes depend on — the session store module, rule 1 of [Module Composition Order](#module-composition-order). A route under a prefix another module also uses, such as `/oauth`, needs no particular position (rule 2), provided it parses its own body and scopes its parsers to exactly its own paths: `oauthModule`'s router parses only its own routes', and a parser that ran for every request under the prefix would read other modules' bodies for them. A module that mounts nothing of the first kind can go at the end:
+
+```diff
+ // src/buildModules.mts
++import { myCustomModule } from "./my-custom-module.mjs";
+ …
+ 	return [
+ 		sessionStoreModuleFor(config),
+ 		…
+ 		...(federationGrantsEnabled ? [subjectRevocationServiceModule] : []),
++		myCustomModule,
+ 	];
 ```
 
+Keep the other rules there too: the session store module stays first, and a module that fills a store slot replaces that slot's adapter switch rather than being added beside it. [`src/app.mts`](src/app.mts) needs no change: it passes `buildModules(config, …)` to `createApp`, mounts the router `createApp` returns, and wires the server's lifetime — `installGracefulShutdown` (below) drains it and calls `handle.dispose()`.
+
 ### Shutdown guarantees
 
 `src/shutdown.mts` is deliberately part of the scaffold rather than a dependency (#290): for the component that terminates every user session, *"does SIGTERM wait for in-flight requests, and for how long?"* has to be answerable from the code you deploy.
@@ -693,18 +955,20 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 2. **New connections stop immediately**, and idle keep-alive sockets are released — they hold the server open with no request behind them, so a quiet server would otherwise wait out the whole deadline for nothing.
 3. **In-flight requests get `drainTimeoutMs`** (default **10s**) to finish.
 4. **Past the deadline the remaining connections are cut and the process exits non-zero.** An orchestrator that only ever sees `0` cannot tell a clean drain from one that ran out of time.
-5. **`cleanup` runs after draining, before exit** — `handle.dispose()`, i.e. reverse-topological component cleanup plus the Redis/timer drain. A failure there is logged through this service's own logger (NDJSON, like every other line) and reflected in the exit code. A dispose that throws still exits; it never wedges the process.
+5. **`cleanup` runs after draining, before exit** — `handle.dispose()`, i.e. reverse-topological component cleanup plus the Redis/timer drain. A failure there is logged through this service's own logger (NDJSON, like every other line) as `shutdown_cleanup_failed` (or `shutdown_cleanup_timed_out`) and reflected in the exit code; every stage is its own event — `shutdown_draining`, `shutdown_drain_deadline_exceeded`, `shutdown_server_close_failed`, `shutdown_complete`. A dispose that throws still exits; it never wedges the process. The line carries core's [`loggableError`](../../packages/core/README.md#logger) projection of the failure, never the error itself: `dispose()` rejects with an AggregateError of every cleanup's own error, and the line names each of them with its code (`aggregateErrors`, the first five) and nothing of what it holds — a store write that failed, with what it was writing, can be one of them.
+
+6. **With federation grants on, `cleanup` gets the longest refresh tail plus a margin** (`cleanupAllowanceFor` in `src/shutdown.mts`): `federationGrants.upstreamHardTimeoutMs` + `persistRetryBudgetMs` + `lockWaitMs` + 12 s, never below 45 s — exactly 45 s under the shipped budgets (25 + 3 + 5 + 12) — instead of inheriting the drain's ten, because the dispose waits for a rotated upstream credential's write. Raise a budget and the allowance grows with it; raise your orchestrator's grace to match. Off, the cleanup budget stays the drain's.
 
-**Size `drainTimeoutMs` below your orchestrator's kill grace period** — Kubernetes `terminationGracePeriodSeconds` and compose `stop_grace_period` are both 30s by default. The point is to close on your terms before `SIGKILL` arrives on someone else's.
+**Size `drainTimeoutMs` and `cleanupTimeoutMs` together below your orchestrator's kill grace period.** Kubernetes `terminationGracePeriodSeconds` is 30s by default and compose's `stop_grace_period` is 10s; with federation grants on, the worst case is drain (10s) + cleanup (45s) = 55s, so **set the grace to 60s or more** — the shipped compose files do, and a Kubernetes deployment must set `terminationGracePeriodSeconds: 60` itself, or a rolling restart SIGKILLs the process in the middle of the write the cleanup exists to finish. The point is to close on your terms before `SIGKILL` arrives on someone else's.
 
 ## npm Scripts
 
 | Script | Description |
 |---|---|
 | `pnpm run build` | Compile TypeScript to `dist/` |
-| `pnpm start` | Start the compiled server |
+| `pnpm run start` | Start the compiled server |
 | `pnpm run debug` | Start with hot reload via `tsx watch` (development mode) |
-| `pnpm test` | Run tests with Vitest |
+| `pnpm run test` | Typecheck (`tsc --noEmit`), then run the tests with Vitest |
 
 ## See Also