@o3co/create-auth-provider 0.15.0 → 0.17.0-rc.1

package/templates/standalone/README.md

@@ -1,21 +1,92 @@
 # @o3co/auth-provider-standalone
 
+Last updated: 2026-10-03
+
 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`,
+`-mfa`, `-redis`, `-foundation` and `-standard`'s mail senders 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 choice read from
+  its own keys, the `adapters` section ([`src/adapters.mts`](src/adapters.mts))
+  and the MFA switch `mfaMode` ([`src/mfaSwitch.mts`](src/mfaSwitch.mts));
+- the modules only this scaffold has — `logging` and `http` (the host
+  process's own settings, with its CORS list, and core's `httpSettings`
+  slot), 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), with the defaults of the sections they
+  own in [`config/reference.conf`](config/reference.conf). 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_STORE_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 (`ADAPTERS_CONSENT_STORE=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,19 +102,19 @@ 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
 
 The [operator runbook](../../docs/operator-runbook.md) covers the operational side end to end — boot refusals, probes, dependency failures, alerts, Redis sizing, key rotation. This section is the multi-replica checklist.
 
-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.
+When running multiple instances of the standalone server behind a load balancer, point `REDIS_CLIENTS_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 +127,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 `adapters.rateLimiter` 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 `session.rateLimit.login`; the session module contributes them as the `login` budget both adapters read, 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
@@ -79,10 +150,11 @@ its address is the honest answer to "who called". There is no per-user identity
 in these requests to key on.
 
 The knob is the per-endpoint budget. Both limiter adapters take
-`limits { <prefix> { limit, windowSeconds } }`, keyed by the endpoint prefix:
+`limits { <prefix> { limit, windowSeconds } }` in their own sections, keyed by
+the endpoint prefix:
 
 ```hocon
-redisRateLimiter {
+redis-rate-limiter {
   limits {
     token     { limit = 600, windowSeconds = 60 }
     introspect { limit = 600, windowSeconds = 60 }
@@ -90,9 +162,9 @@ redisRateLimiter {
 }
 ```
 
-(`memoryRateLimiter.limits` for the memory adapter, same shape.) Size it from
+(`core-rate-limiter-memory.limits` for the memory adapter, same shape.) Size it from
 your BFF's peak sign-ins and refreshes per minute with headroom, and remember
-that under `rateLimiter.adapter = "redis"` the budget is shared across replicas
+that under `adapters.rateLimiter = "redis"` the budget is shared across replicas
 — which is what you want here, and what makes the number mean something.
 
 The defaults are deliberately left alone: 60/60 s per source IP is a sensible
@@ -101,93 +173,254 @@ 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 `CORE_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 (`ADAPTERS_USER_SESSION_STORES=memory`), the authorization-code repository (`ADAPTERS_CODE_REPOSITORY=memory`) and the federation token store (`ADAPTERS_FEDERATION_TOKEN_STORE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORE_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `ADAPTERS_RATE_LIMITER=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 `CORE_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` (`ADAPTERS_REPLAY_SEEN_SET`), so it gets the same answer — `memory` is refused under `CORE_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).
+
+The variable sets `core.deployment.mode`. `DEPLOYMENT_MODE`, its old name, refuses boot set alone or beside `CORE_DEPLOYMENT_MODE` at a different value; beside it at the same value, it boots.
 
-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.
+Be aware of what this check *cannot* do: if you scale to N replicas without ever setting `CORE_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.
 
-**Access-token revocation needs a denylist, and the template ships one.** `POST /oauth/revoke` revokes an access token by writing its `jti` to the `accessTokenDenylist`, which token verification and introspection consult. Boot *fails* if the endpoint is mounted with no denylist behind it: RFC 7009 obliges the endpoint to answer `200`, so an unwired denylist would tell you a token is revoked while it keeps working until it expires. `accessTokenDenylist.adapter` defaults to `"redis"` here (`ACCESS_TOKEN_DENYLIST_ADAPTER=memory` for single-instance local work) and shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`, so it costs no extra connection. A deployment that genuinely does not revoke access tokens sets `OAUTH_REVOCATION_ACCESS_TOKEN=unsupported` instead; the endpoint then answers `unsupported_token_type` for `token_type_hint=access_token`. **Refresh-token revocation works in either case and never needed a denylist.**
+**Access-token revocation needs a denylist, and the template ships one.** `POST /oauth/revoke` revokes an access token by writing its `jti` to the `accessTokenDenylist`, which token verification and introspection consult. Boot *fails* if the endpoint is mounted with no denylist behind it: RFC 7009 obliges the endpoint to answer `200`, so an unwired denylist would tell you a token is revoked while it keeps working until it expires. `adapters.accessTokenDenylist` defaults to `"redis"` here (`ADAPTERS_ACCESS_TOKEN_DENYLIST=memory` for single-instance local work) and shares the ioredis socket configured by `REDIS_CLIENTS_URL`, so it costs no extra connection. A deployment that genuinely does not revoke access tokens sets `OAUTH_REVOCATION_ACCESS_TOKEN=unsupported` instead; the endpoint then answers `unsupported_token_type` for `token_type_hint=access_token`. **Refresh-token revocation works in either case and never needed a denylist.**
 
 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 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).
+- The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORE_STORAGE_TYPE=redis` with `SESSION_STORE_STORAGE_REDIS_URL` (`session-store.storage.redis.url`) pointing at the shared instance.
+- The user-session stores switch on `adapters.userSessionStores = "redis"` (`ADAPTERS_USER_SESSION_STORES`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REDIS_CLIENTS_URL` configures.
+- The authorization-code repository switches on `adapters.codeRepository` (`ADAPTERS_CODE_REPOSITORY`); the template ships `"redis"`, on that same connection, so there is one Redis URL for every adapter. The Redis repository's own settings are its section, `redis-code-repository`; the in-process one's, `standalone-in-memory-code-repository` (see [Code Repository](#code-repository)).
+- The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `adapters.replaySeenSet` (`ADAPTERS_REPLAY_SEEN_SET`); the template ships `"redis"` on the shared connection, and `memory` is refused under `CORE_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 `adapters.consentStore` (`ADAPTERS_CONSENT_STORE`). It is off (`none`) by default; `memory` is refused under `CORE_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 `ADAPTERS_FEDERATION_TOKEN_STORE=redis` (`adapters.federationTokenStore = "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 `REDIS_CLIENTS_URL`. See [Federation Token Store](#federation-token-store).
+- Federation grants (#593), when enabled, keep two more stores: the grants themselves (`ADAPTERS_FEDERATION_GRANT_STORE`) and acquisition's records (`ADAPTERS_FEDERATION_GRANT_INTENT_STORE`). Both ship `none`, which an enabled feature refuses at boot naming the store: select `redis` (the shared socket) or `memory` for each; `memory` for either is refused under `CORE_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, `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` / `KEY_STORE_LOCAL_PUBLIC_KEY_PATH`
+  (see [OAuth JWT](#oauth-jwt));
+- `SESSION_STORE_SECRET`, at least 32 bytes;
+- `REPOSITORIES_USER_HTTP_AUTHENTICATE_URL` and `REPOSITORIES_USER_HTTP_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_STORE_STORAGE_REDIS_URL`), and
+  opens one shared connection (`REDIS_CLIENTS_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_STORE_SECURE=false` and a session cookie name without
+the `__Host-` prefix (see [Session](#session)). And set
+`ADAPTERS_USER_SESSION_STORES=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)).
+MFA is on by default, and its two stores default to memory too: set
+`ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`
+for the same reason, or every save empties them while the sessions survive —
+or `MFA_MODE=off` to run without MFA (see
+[Multi-factor authentication](#multi-factor-authentication)).
+
+It also reads the client registry, `config/clients.yaml` (`REPOSITORIES_CLIENT_YAML_PATH`). That
+file is per-deployment: the scaffold creates an empty one, and `.gitignore`
+keeps it out of the project's repository, so a fresh clone has none and boot
+fails naming the path until you create it — from `config/clients.yaml.example`,
+or empty for a registry with no clients.
+
+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 \
+  KEY_STORE_LOCAL_PRIVATE_KEY_PATH=./jwt-private.pem \
+  KEY_STORE_LOCAL_PUBLIC_KEY_PATH=./jwt-public.pem \
+  SESSION_STORE_SECRET="$(openssl rand -hex 32)" \
+  SESSION_STORE_SECURE=false SESSION_STORE_NAME=auth.sid \
+  ADAPTERS_USER_SESSION_STORES=redis \
+  ADAPTERS_MFA_FACTOR_STORE=redis ADAPTERS_MFA_TRANSACTION_STORE=redis \
+  REPOSITORIES_USER_HTTP_AUTHENTICATE_URL=http://localhost:8080/authenticate \
+  REPOSITORIES_USER_HTTP_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.
+Configuration is loaded from `config/application.conf` (HOCON format), over the defaults in the packages' `reference.conf` files and the template's own `config/reference.conf`. 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 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. **the `reference.conf` of each package the loaded modules come from**, then
+   **`@o3co/auth-provider-core`'s** — the defaults, resolved from the
+   installed packages: each module declares its package's file, and core's
+   `moduleReferences(modules)` lists them, core's last. The template's own
+   modules declare `config/reference.conf`, which holds the defaults of the
+   sections they own — `logging`, `http` (with its CORS list,
+   `http.cors`), `key-store`, the shared Redis connection's `redis-clients`,
+   `repositories`, the in-process code repository's
+   `standalone-in-memory-code-repository` and `audit-sink` — and of the
+   composition root's own `adapters` and `mfaMode` (below). Set a deployment's own value in
+   the two files above, not there. `config/reference.conf` binds each of these
+   keys' variables beside its default, so a value either file above sets wins
+   over the variable, except for `HTTP_PORT`, `HTTP_TRUST_PROXY`,
+   `HTTP_CORS_ALLOWED_ORIGINS` and `REDIS_CLIENTS_URL` /
+   `REDIS_CLIENTS_PASSWORD`, which `application.conf` binds again in its last
+   lines, so each of those wins over a value that file sets above them. A key
+   neither file above sets takes its value from here.
+
+It reads the two files above once, under one snapshot of the environment
+(`readOwnLayers`), and builds two phases from that one read
+([#728](https://github.com/o3co/auth.provider/issues/728);
+[`src/configPath.mts`](src/configPath.mts)) — so a file replaced, or a
+variable changed, while the process starts cannot make boot parse something
+other than what the modules were chosen by. First, before it knows its
+modules, it reads the switches `buildModules` chooses them by — the
+federations, the features — and the `sessionRequirements` it derives the
+session requirements it expects from, from the two files above over core's
+`reference.conf` alone (`readSwitches`, with core's transitional reader),
+parsing those paths (`SWITCHES`) and nothing else. It reads `adapters` — which
+adapter fills each slot, the composition root's own section — from the two
+files above over the template's `config/reference.conf`, with the template's
+own schema (`readAdapters`): a selection still written at the path it moved
+from, or a variable renamed with it, is refused there, before any module is
+chosen, naming the new path and variable. It reads the MFA switch `mfaMode`
+(`MFA_MODE`), the composition root's own key, the same way, with the
+template's own schema (`readMfaSwitch`), and beside them the user
+repository's HTTP settings, unparsed, which the Store-backed MFA factor store
+is built over. Boot is not handed `adapters` or `mfaMode`. It sees nothing
+a package's `reference.conf` alone sets — none is layered yet — and a module
+you add to `buildModules` that reads its configuration when it is built adds
+the paths it reads to `SWITCHES`. The log level is read before boot too, as
+the `logging` module's section, with that module's schema, over the template's
+`reference.conf` (`readLogging`): the logger exists before boot, since the
+template logs while it reads its configuration and chooses its modules. Then it hands `createApp` the configuration as resolved over every
+loaded module's `reference.conf` (`resolveForBoot`), unparsed, with the session
+requirements phase one derived written in, and the `mfa` section as the MFA
+switch decides it (see [Multi-factor authentication](#multi-factor-authentication)):
+boot parses it once, with every loaded module's schema. What
+the template reads after boot — the trusted hops, the port, the readiness
+deadline — it reads from the `http` module: core's `httpSettings` slot and the
+template's `httpHostSettings`. A top-level section no
+loaded module owns is kept and logged once at boot as
+`config_sections_ignored`: that is where a misspelt section name shows.
 
 Values in the overlay take precedence over `application.conf`. The scaffold
-ships with `development.conf` and `production.conf`. To add another
+ships with `development.conf`, `production.conf` and `mailpit.conf` (the
+development overlay under the name the
+[Mailpit overlay](#mailpit-for-the-smtp-sender-development-only) selects). To add another
 environment (e.g. `staging`), create `config/staging.conf` and set
 `CONFIG_ENV=staging`. A missing `{ENV}.conf` is a boot-time error — typos
 fail fast rather than silently falling back to defaults.
 
+### Adapters
+
+Which adapter fills each slot is the composition root's own choice, its own
+section `adapters`, read before any module is chosen (above). Each key has its
+variable; a value the template does not know, or a key it does not declare,
+fails before boot, naming it.
+
+| Variable | Default | Description |
+|---|---|---|
+| `ADAPTERS_RATE_LIMITER` | `memory` | `adapters.rateLimiter`: `memory` or `redis`. See [Multi-replica deployments](#multi-replica-deployments) |
+| `ADAPTERS_USER_SESSION_STORES` | `memory` | `adapters.userSessionStores`: the user-session stores, `memory` or `redis`. Keep it with `SESSION_STORE_STORAGE_TYPE` (see [Docker](#docker)) |
+| `ADAPTERS_ACCESS_TOKEN_DENYLIST` | `redis` | `adapters.accessTokenDenylist`: `memory` or `redis` |
+| `ADAPTERS_REPLAY_SEEN_SET` | `redis` | `adapters.replaySeenSet`: the replay seen-set behind `private_key_jwt`, `memory` or `redis` |
+| `ADAPTERS_CONSENT_STORE` | `none` | `adapters.consentStore`: `none`, `memory` or `redis`. See [Consent Store](#consent-store) |
+| `ADAPTERS_FEDERATION_TOKEN_STORE` | `memory` | `adapters.federationTokenStore`: `memory` or `redis`. See [Federation Token Store](#federation-token-store) |
+| `ADAPTERS_FEDERATION_GRANT_STORE` | `none` | `adapters.federationGrantStore`: `none`, `memory` or `redis`. See [Federation Grants](#federation-grants) |
+| `ADAPTERS_FEDERATION_GRANT_INTENT_STORE` | `none` | `adapters.federationGrantIntentStore`: `none`, `memory` or `redis`. See [Federation Grants](#federation-grants) |
+| `ADAPTERS_MFA_FACTOR_STORE` | `memory` | `adapters.mfaFactorStore`: `memory` (development and test only), `redis` or `store` (the Store's endpoints), read while `MFA_MODE` installs MFA. See [Multi-factor authentication](#multi-factor-authentication) |
+| `ADAPTERS_MFA_TRANSACTION_STORE` | `memory` | `adapters.mfaTransactionStore`: `memory` (development and test only) or `redis`, read while `MFA_MODE` installs MFA |
+| `ADAPTERS_CODE_REPOSITORY` | `redis` | `adapters.codeRepository`: the authorization-code repository, `memory` or `redis`. See [Code Repository](#code-repository) |
+| `ADAPTERS_CLIENT_REPOSITORY` | `yaml` | `adapters.clientRepository`: `yaml`, or `static` (core's alias of `yaml`). See [Client Repository](#client-repository) |
+| `ADAPTERS_USER_REPOSITORY` | `http` | `adapters.userRepository`: `http`, `yaml` or `static` (core's alias of `yaml`). See [User Repository](#user-repository) |
+| `ADAPTERS_AUDIT_SINK` | `logger` | `adapters.auditSink`: where security events go, `logger` (pino-enveloped NDJSON on stdout) or `console` (bare event JSON). There is no `none`. See [Audit trail](#audit-trail) |
+
+A selection still written where it was — `rateLimiter.adapter`,
+`oauth.code.adapter`, `audit.sink.type`, `repositories.user.type` and the
+like — or a variable renamed with it (`RATE_LIMITER_ADAPTER`, `CLIENT_TYPE`,
+…) set alone or to a different value, fails before boot, naming the new path
+and variable; the old variable beside the new one at the same value is
+accepted.
+
 ### HTTP
 
 | Variable | Default | Description |
 |---|---|---|
-| `HTTP_PORT` | `3000` | Port the server listens on |
+| `HTTP_PORT` | `3000` | Port the server listens on, `0` to `65535` in decimal digits; `0` lets the OS choose a free one. Set but empty, it fails boot |
 | `HTTP_TRUST_PROXY` | `false` | Express `trust proxy`: `false`, an address/CIDR list (`10.0.0.0/8,loopback`), a hop count (`1`), or `true`. **Required behind a load balancer** — otherwise every IP-keyed rate limit shares one bucket across all users. Prefer naming the proxy over `true`. See [Multi-replica deployments](#multi-replica-deployments) |
 | `HTTP_READINESS_TIMEOUT_MS` | `1000` | Per-probe deadline for `/readyz` (see [Health endpoints](#health-endpoints)) |
-| `LOG_LEVEL` | `info` | Minimum level emitted: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`. Does **not** gate the audit trail — see [Audit trail](#audit-trail) |
-| `AUDIT_SINK_TYPE` | `logger` | Where security events go: `logger` (pino-enveloped NDJSON on stdout) or `console` (bare event JSON). There is no `none`. See [Audit trail](#audit-trail) |
+| `LOGGING_LEVEL` | `info` | Minimum level emitted: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`. Does **not** gate the audit trail — see [Audit trail](#audit-trail) |
 
 ### OAuth JWT
 
+The signing key is the `key-store` module's section: `key-store.provider`
+(`KEY_STORE_PROVIDER`, `local`) and the local key store's `key-store.local`
+(`KEY_STORE_LOCAL_*`). The issuer and the token format stay under `oauth.jwt`.
+
 | Variable | Default | Description |
 |---|---|---|
-| `OAUTH_JWT_ALGORITHM` | `EdDSA` | JWT signing algorithm: `EdDSA`, `ES256`, `RS256` or `HS256`. The default is asymmetric so `/.well-known/jwks.json` publishes a real verification key. |
-| `OAUTH_JWT_SECRET` | — | Signing secret, **HMAC (`HS256`) only**. At least 32 bytes (256 bits) of random material — `openssl rand -hex 32`. Hex/base64 values are measured **decoded**, so a 32-character hex string counts as 16 bytes and is refused. |
+| `KEY_STORE_LOCAL_ALGORITHM` | `EdDSA` | JWT signing algorithm: `EdDSA`, `ES256`, `RS256` or `HS256`. The default is asymmetric so `/.well-known/jwks.json` publishes a real verification key. |
+| `KEY_STORE_LOCAL_SECRET` | — | Signing secret, **HMAC (`HS256`) only**. At least 32 bytes (256 bits) of random material — `openssl rand -hex 32`. Hex/base64 values are measured **decoded**, so a 32-character hex string counts as 16 bytes and is refused. |
 | `OAUTH_JWT_ISSUER` | **(required)** | Canonical issuer URL stamped as `iss` on every token. Must be absolute `https` (`http` only for a loopback host), with no query or fragment. Boot fails when unset — it is never derived from the `Host` header. |
 | `OAUTH_REQUIRE_EMAIL_VERIFIED` | `false` | Refuse to issue tokens for a user until the Store publishes `emailVerified: true`. Enforced at `/authorize` and on the `session` grant. Verification itself is the Store's job — this only reads the result. |
-| `OAUTH_CIMD_ENABLED` | `false` | Accept Client ID Metadata Documents (#529): a client whose `client_id` is the `https` URL of its own registration, the model MCP hosts use. Such a client is public, never first-party — it goes through the consent step, so wire `CONSENT_STORE_ADAPTER`. |
-| `OAUTH_CIMD_ALLOWED_SCOPES` | — | Comma-separated: what any such client may obtain (its document's `scope` is intersected with this). Empty admits none. |
-| `OAUTH_CIMD_ALLOWED_AUDIENCES` | — | Comma-separated: the resource servers it may mint for (RFC 8707 `resource`). Empty admits only its own `client_id`. |
-| `OAUTH_CIMD_ALLOWED_HOSTS` | — | Comma-separated hosts a document may live on: exact, or `.suffix` for a domain and its subdomains. Empty admits any public host. |
-| `OAUTH_CIMD_DENIED_HOSTS` | — | Comma-separated hosts refused even when allowed above. |
-| `OAUTH_CIMD_MAX_BYTES` | `5120` | Byte cap on a document (the draft recommends 5 KB). |
-| `OAUTH_CIMD_TIMEOUT_MS` | `5000` | Fetch timeout. |
-| `OAUTH_CIMD_CACHE_MAX_AGE_MS` | `600000` | Upper bound on how long a valid document is served from cache; `Cache-Control: max-age` may shorten it. |
-| `OAUTH_CIMD_MAX_CACHE_ENTRIES` | `256` | How many documents are remembered at once. The keys are chosen by an unauthenticated caller, so the map is bounded. |
-| `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_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 |
-| `OAUTH_JWT_PUBLIC_KEY_PATH` | — | Path to PEM public key file |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ENABLED` | `false` | Accept Client ID Metadata Documents (#529): a client whose `client_id` is the `https` URL of its own registration, the model MCP hosts use. Such a client is public, never first-party — it goes through the consent step, so wire `ADAPTERS_CONSENT_STORE`. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_SCOPES` | — | Comma-separated: what any such client may obtain (its document's `scope` is intersected with this). Empty admits none. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_AUDIENCES` | — | Comma-separated: the resource servers it may mint for (RFC 8707 `resource`). Empty admits only its own `client_id`. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_HOSTS` | — | Comma-separated hosts a document may live on: exact, or `.suffix` for a domain and its subdomains. Empty admits any public host. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_DENIED_HOSTS` | — | Comma-separated hosts refused even when allowed above. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_BYTES` | `5120` | Byte cap on a document (the draft recommends 5 KB). |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_TIMEOUT_MS` | `5000` | Fetch timeout. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_CACHE_MAX_AGE_MS` | `600000` | Upper bound on how long a valid document is served from cache; `Cache-Control: max-age` may shorten it. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_CACHE_ENTRIES` | `256` | How many documents are remembered at once. The keys are chosen by an unauthenticated caller, so the map is bounded. |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_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. |
+| `KEY_STORE_LOCAL_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) |
+| `KEY_STORE_LOCAL_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
+| `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
+| `KEY_STORE_LOCAL_PUBLIC_KEY` | — | PEM-encoded public key |
+| `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` | — | Path to PEM public key file |
 | `OAUTH_JWT_LEGACY_TYP_ACCEPT` | `false` | Accept tokens whose `typ` header is absent. `false` rejects them, treating a typ-less token as the misconfiguration or downgrade attempt it usually is. Set `true` only for a bounded migration window while v0.4.x tokens are still in circulation. |
+| `JWKS_PATH` | `/.well-known/jwks.json` | Where the verification keys are published under the issuer, and what discovery advertises as `jwks_uri` (`jwks.path`). An absolute path with no `//`, dot-segment, query, fragment, backslash, percent-encoding or control character. |
+| `JWKS_CACHE_MAX_AGE` | `300` | The JWKS response's `Cache-Control: public, max-age`, in seconds (`jwks.cacheMaxAge`). Keep it well below the key-overlap window, so a rotated key reaches caching verifiers in time. |
 
 **Signing keys are required.** The default algorithm is `EdDSA` and there is no
 key-material default: a deployment that sets none fails at boot naming the keys
@@ -199,11 +432,11 @@ openssl genpkey -algorithm ed25519 -out jwt-private.pem
 openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 ```
 
-then point `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH` at them
-(or inline the PEMs via `OAUTH_JWT_PRIVATE_KEY` / `OAUTH_JWT_PUBLIC_KEY`).
+then point `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` / `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` at them
+(or inline the PEMs via `KEY_STORE_LOCAL_PRIVATE_KEY` / `KEY_STORE_LOCAL_PUBLIC_KEY`).
 
-`HS256` is still selectable (`OAUTH_JWT_ALGORITHM=HS256` plus a ≥32-byte
-`OAUTH_JWT_SECRET`), but understand what it costs: a symmetric key has no
+`HS256` is still selectable (`KEY_STORE_LOCAL_ALGORITHM=HS256` plus a ≥32-byte
+`KEY_STORE_LOCAL_SECRET`), but understand what it costs: a symmetric key has no
 public half, so `/.well-known/jwks.json` answers `404 jwks_not_published` and
 every relying party must be handed the shared secret — which also lets it
 **mint** tokens, not merely verify them.
@@ -214,12 +447,12 @@ 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:
-HOCON resolves `FOO=` to `""`, which coerces to `0`, and a zero lifetime mints
-tokens that have already expired.
+Each is read only as decimal digits. Exporting one as an empty string is a
+boot failure, not a fallback (HOCON resolves `FOO=` to `""`), and so is a hex
+(`0x10`), exponent (`1e3`), sign (`+5`) or fraction (`5.0`).
 
 Only token exchange (RFC 8693) reads an `expires_in` request parameter; every
 other grant ignores it and mints the default.
@@ -228,29 +461,48 @@ other grant ignores it and mints the default.
 
 | Variable | Default | Description |
 |---|---|---|
-| `OAUTH_GRANTS_SESSION_ENABLED` | `true` | Enable the session grant type |
-| `OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED` | `true` | Enable the authorization code grant type |
-| `OAUTH_GRANTS_REFRESH_TOKEN_ENABLED` | `true` | Enable the refresh token grant type |
+| `OAUTH_SESSION_ENABLED` | `true` | Enable the session grant type |
+| `OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED` | `true` | Enable the authorization code grant type |
+| `OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED` | `true` | Enable the refresh token grant type |
+| `OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED` | `false` | Enable the client credentials grant type |
+| `OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED` | `false` | Enable the jwt-bearer grant type (RFC 7523) |
+
+Each switch is its module's key — `oauth-session.enabled`, and
+`oauth-authorization.grants.<grant>.enabled` for the others — which the
+template reads before boot, from its own files and the environment, to choose
+the modules. `OAUTH_GRANTS_<GRANT>_ENABLED`, the old names, refuse boot set
+alone or beside the new name at a different value; beside it at the same value,
+they boot.
 
 ### Session
 
 | Variable | Default | Description |
 |---|---|---|
-| `SESSION_SECRET` | — | **Required.** Signs the cookie that *is* the authenticated session, so guessing it forges logins. At least 32 bytes (256 bits) — `openssl rand -hex 32`. Measured **decoded**, same rule as `OAUTH_JWT_SECRET`. |
-| `SESSION_NAME` | `__Host-auth.session` | Session cookie name. The default uses the `__Host-` prefix and therefore requires `SESSION_SECURE=true` and no `SESSION_DOMAIN`. |
-| `SESSION_MAX_AGE` | `3600000` | Session cookie max age in milliseconds. Whole positive number, at most one year (`31536000000`). |
-| `SESSION_SECURE` | `true` | Set `Secure` flag on session cookie |
-| `SESSION_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`). `none` **requires** `SESSION_SECURE=true` — browsers drop a `SameSite=None` cookie that is not `Secure`, so boot refuses the combination rather than letting every login fail silently in the client. |
-| `SESSION_DOMAIN` | — | Cookie domain (unset by default) |
-| `SESSION_CSRF_TTL_SECONDS` | `7200` | Lifetime of an issued CSRF token, in seconds. Integer, 1–86400; boot fails otherwise (an *empty* value coerces to `0` and would silently disable the token arm). |
-| `SESSION_STORAGE_TYPE` | `redis` | Session store backend: `redis` or `memory`. `memory` is per process and is refused under `DEPLOYMENT_MODE=multi` like the other in-memory stores (#474) |
-| `SESSION_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
-| `SESSION_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
-
-If you set `SESSION_SECURE=false` for local HTTP development or set `SESSION_DOMAIN`
-for shared-domain cookies, also set `SESSION_NAME` to a non-`__Host-` value such as
-`auth.sid`. The server fails fast when a `__Host-` cookie name is combined with
-attributes that browsers reject for that prefix.
+| `SESSION_STORE_SECRET` | — | **Required.** Signs the cookie that *is* the authenticated session, so guessing it forges logins. At least 32 bytes (256 bits) — `openssl rand -hex 32`. Measured **decoded**, same rule as `KEY_STORE_LOCAL_SECRET`. |
+| `SESSION_STORE_NAME` | `__Host-auth.session` | Session cookie name. The default uses the `__Host-` prefix and therefore requires `SESSION_STORE_SECURE=true` and no `SESSION_STORE_DOMAIN`. |
+| `SESSION_STORE_MAX_AGE` | `3600000` | Session cookie max age in milliseconds. Whole positive number, at most one year (`31536000000`). |
+| `SESSION_STORE_SECURE` | `true` | Set `Secure` flag on session cookie |
+| `SESSION_STORE_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`). `none` **requires** `SESSION_STORE_SECURE=true` — browsers drop a `SameSite=None` cookie that is not `Secure`, so boot refuses the combination rather than letting every login fail silently in the client. |
+| `SESSION_STORE_DOMAIN` | — | Cookie domain (unset by default) |
+| `SESSION_CSRF_TTL_SECONDS` | `7200` | Lifetime of an issued CSRF token, in seconds. Whole number in decimal digits, 1–86400; boot fails otherwise, an *empty* or blank value included. |
+| `SESSION_STORE_STORAGE_TYPE` | `redis` | Session store backend: `redis` or `memory`. `memory` is per process and is refused under `CORE_DEPLOYMENT_MODE=multi` like the other in-memory stores (#474) |
+| `SESSION_STORE_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
+| `SESSION_STORE_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
+
+The cookie and its store are the session store's section, `session-store`; the
+CSRF token's lifetime, the login page and the login's budget are the session
+module's, `session`. `SESSION_<KEY>`, the old names of the `SESSION_STORE_*`
+variables, refuse boot set alone or beside the new name at a different value;
+beside it at the same value, they boot.
+
+If you set `SESSION_STORE_SECURE=false` for local HTTP development or set `SESSION_STORE_DOMAIN`
+for shared-domain cookies, also set `SESSION_STORE_NAME` to a non-`__Host-` value such as
+`auth.sid` — with `SESSION_STORE_SECURE=false`, one with no prefix: a `__Secure-` name
+needs `SESSION_STORE_SECURE=true` too. The server fails fast when a `__Host-` or
+`__Secure-` cookie name is combined with attributes that browsers reject for that
+prefix (in any case), on a `SESSION_STORE_NAME` that is not a cookie name (an RFC 6265
+token: no space, `;` or other separator), and on a `SESSION_STORE_DOMAIN` that is not a
+host name (a scheme, a port or a path).
 
 #### CSRF on `/session/login` and `/session/logout`
 
@@ -258,7 +510,7 @@ Both routes accept a request carrying **either** a same-origin (or trusted)
 `Origin` / `Referer`, **or** a valid double-submit CSRF token, and reject one
 carrying neither (#272). Browsers satisfy this automatically; a scripted client
 calls `GET /session/csrf` first and sends the returned `csrf_token` back as
-both the `<SESSION_NAME>.csrf` cookie and an `x-csrf-token` header (or a
+both the `<SESSION_STORE_NAME>.csrf` cookie and an `x-csrf-token` header (or a
 `csrf_token` form field).
 
 Two configuration notes:
@@ -269,19 +521,21 @@ Two configuration notes:
   request.
 - If your login UI is served from a **different origin** than the provider,
   list that origin under `session.csrf.trustedOrigins` in your HOCON config.
-  `cors.allowedOrigins` does not confer CSRF trust — see
+  A listed origin can also answer federation-grant consents and device
+  verification, so a client's origin is never listed (the federation-grants
+  ADR's D7). `http.cors.allowedOrigins` does not confer CSRF trust — see
   [CORS](#cors) for what it does confer.
 
 ### CORS
 
 | Variable | Default | Description |
 |---|---|---|
-| `CORS_ALLOWED_ORIGINS` | *(empty — CORS off)* | Comma-separated list of browser origins allowed to read the token, userinfo, revocation and discovery/JWKS responses |
+| `HTTP_CORS_ALLOWED_ORIGINS` | *(empty — CORS off)* | Comma-separated list of browser origins allowed to read the token, userinfo, revocation and discovery/JWKS responses |
 
 A browser app served from a different origin than this provider — an SPA on
 `https://app.example.com` against a provider on `https://auth.example.com` —
 cannot call the token endpoint at all unless that origin is on
-`cors.allowedOrigins`. Set it and the provider answers preflights and stamps
+`http.cors.allowedOrigins`. Set it and the provider answers preflights and stamps
 `Access-Control-Allow-Origin` on the five endpoints a browser has a legitimate
 reason to call cross-origin:
 
@@ -291,7 +545,7 @@ reason to call cross-origin:
 | `/oauth/userinfo` | `GET`, `POST` | OIDC Core §5.3 defines both |
 | `/oauth/revoke` | `POST` | RFC 7009 §2.1 — a public client revoking its own tokens on sign-out |
 | `/.well-known/openid-configuration` | `GET` | Discovery, fetched by browser client libraries |
-| `/.well-known/jwks.json` | `GET` | Same; follows `oauth.jwt.jwksPath` when you override it |
+| `/.well-known/jwks.json` | `GET` | Same; follows `jwks.path` when you override it |
 
 `/oauth/introspect` and `/oauth/authorize` are deliberately **not** included.
 Introspection is server-to-server and already refuses public clients, so no
@@ -299,12 +553,21 @@ browser could use it; `/authorize` is a top-level navigation rather than a
 `fetch`, and CORS has no say over where a browser may navigate.
 
 ```hocon
-cors {
+http.cors {
   allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
 }
 ```
 
-or `CORS_ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173`.
+or `HTTP_CORS_ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173`.
+Those are the two spellings; a value that is neither — a number, an
+object, a boolean, which only a configuration file can write — fails boot
+naming `http.cors.allowedOrigins` rather than reading as no origins.
+
+The list is part of the `http` module's section, with its default in
+`config/reference.conf`. The `http` module hands it to core's CORS middleware
+in the `httpSettings` slot, beside the trusted hops, and core reads the slot,
+not the configuration: a composition with no `httpSettings` provider mounts
+no CORS.
 
 **Matching is exact string equality against the `Origin` header**, and every
 shape that could not match fails at boot naming its index rather than sitting
@@ -330,16 +593,25 @@ all — no headers, no `Vary`, nothing changed.
 
 ### Google Federation
 
+The federations are core's: `core.federations`, one map keyed by the name
+each is reached at (`/session/oauth/federation/<name>`). A key of one is bound
+to the variable named after its path, `CORE_FEDERATIONS_<NAME>_<KEY>`. The map
+written at the top level (`federations { ... }`) refuses boot, naming each
+key's path under `core.federations`; a `FEDERATIONS_GOOGLE_*` or
+`FEDERATIONS_OIDC_*` variable set alone, or beside its new name at a different
+value, is refused before any module is chosen.
+
 | Variable | Default | Description |
 |---|---|---|
-| `FEDERATIONS_GOOGLE_ENABLED` | `false` | Enable Google OAuth federation |
-| `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 |
+| `CORE_FEDERATIONS_GOOGLE_ENABLED` | `false` | Enable Google OAuth federation |
+| `CORE_FEDERATIONS_GOOGLE_CLIENT_ID` | — | Google OAuth client ID |
+| `CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
+| `CORE_FEDERATIONS_GOOGLE_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/google/callback` | Google OAuth callback URL |
+| `CORE_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)
 
-One instance ships in `config/application.conf` under `federations.oidc`
+One instance ships in `config/application.conf` under `core.federations.oidc`
 (`@o3co/auth-provider-federation-oidc`, #524): Okta, Entra ID, Auth0, Keycloak
 or your own tenant, selected by issuer. Discovery runs at boot and a failure
 refuses boot. The identity handed to the Store is `oidc:<sub>`; an identity
@@ -347,16 +619,16 @@ the Store does not know is refused with 401 — nothing is provisioned.
 
 | Variable | Default | Description |
 |---|---|---|
-| `FEDERATIONS_OIDC_ENABLED` | `false` | Enable the OIDC federation |
-| `FEDERATIONS_OIDC_ISSUER` | — | Issuer identifier (https), exactly as the IdP writes `iss` |
-| `FEDERATIONS_OIDC_CLIENT_ID` | — | Client ID registered at the IdP |
-| `FEDERATIONS_OIDC_CLIENT_SECRET` | — | Client secret (`client_secret_basic`); set `privateKey` in the config file for `private_key_jwt` instead |
-| `FEDERATIONS_OIDC_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/oidc/callback` | Where the IdP sends the browser back |
+| `CORE_FEDERATIONS_OIDC_ENABLED` | `false` | Enable the OIDC federation |
+| `CORE_FEDERATIONS_OIDC_ISSUER` | — | Issuer identifier (https), exactly as the IdP writes `iss` |
+| `CORE_FEDERATIONS_OIDC_CLIENT_ID` | — | Client ID registered at the IdP |
+| `CORE_FEDERATIONS_OIDC_CLIENT_SECRET` | — | Client secret (`client_secret_basic`); set `privateKey` in the config file for `private_key_jwt` instead |
+| `CORE_FEDERATIONS_OIDC_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/oidc/callback` | Where the IdP sends the browser back |
 
 A second IdP is another section with `type = "oidc"` and its own callback:
 
 ```hocon
-federations {
+core.federations {
   okta {
     enabled = true
     type = "oidc"
@@ -369,7 +641,7 @@ federations {
 }
 ```
 
-The section's `type` names the implementation. `federations.google` without a
+The entry's `type` names the implementation. `core.federations.google` without a
 `type` is the built-in Google federation; with `type = "oidc"` it is a generic
 OIDC instance named `google`, and the built-in module is not composed.
 
@@ -381,20 +653,27 @@ is documented in [its README](../../packages/federation-oidc/README.md).
 
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_TYPE` | `yaml` | Client store backend: `yaml` |
-| `CLIENT_PATH` | `./config/clients.yaml` | Path to the YAML client registry |
+| `ADAPTERS_CLIENT_REPOSITORY` | `yaml` | Client store backend: `yaml`, or `static`, core's alias of `yaml`, which reads `repositories.client.static.path` (no default) |
+| `REPOSITORIES_CLIENT_YAML_PATH` | `./config/clients.yaml` | Path to the YAML client registry |
+
+The registry is per-deployment configuration: `.gitignore` keeps
+`config/clients.yaml` out of git and `.dockerignore` keeps it out of the image,
+and the production compose file mounts it (see [Docker](#docker)).
 
 ### User Repository
 
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_USER_TYPE` | `http` | User repository backend: `http` |
-| `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_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
-| `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
+| `ADAPTERS_USER_REPOSITORY` | `http` | User repository backend: `http`, or `yaml` for local work (`static`, core's alias of `yaml`, reads `repositories.user.static.path`, with no default) |
+| `REPOSITORIES_USER_YAML_PATH` | `./config/users.yaml` | The YAML user file the `yaml` backend reads |
+| `REPOSITORIES_USER_HTTP_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
+| `REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
+| `REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store links a federated identity at (#482); enables `?link=1` on the federation start route. **https required** |
+| `REPOSITORIES_USER_HTTP_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** |
+| `REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` | — | Optional. URL the Store keeps the MFA enrollment witness at (the MFA ADR's D12): with it, a lost factor store cannot open a first binding. The Store must then answer `mfaEnrolled` on both authenticate URLs. Unset, a boot with MFA on warns (`mfa_enrollment_witness_unwritable`). **https required** |
+| `REPOSITORIES_USER_HTTP_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) |
+| `REPOSITORIES_USER_HTTP_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
+| `REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
 
 Both user-authentication URLs carry **plaintext user credentials** to the
 upstream store, so both must be absolute `https://` URLs. `http://` is accepted
@@ -405,31 +684,71 @@ 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 `REPOSITORIES_USER_HTTP_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 `ADAPTERS_USER_REPOSITORY=http` — this
+template's default — boot fails if the token is weaker than 32 bytes
+(measured like `SESSION_STORE_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
 
+`adapters.codeRepository` (`ADAPTERS_CODE_REPOSITORY`) chooses the
+repository; each reads its own section. The Redis one runs on the shared
+connection `REDIS_CLIENTS_URL` configures, so it takes no URL or password of
+its own.
+
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); honoured with a boot warning |
-| `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 |
+| `REDIS_CODE_REPOSITORY_DEFAULT_EXPIRES_IN` | `600` | `redis-code-repository.defaultExpiresIn`: the Redis repository's default authorization-code lifetime, in seconds |
+| `REDIS_CODE_REPOSITORY_KEY_PREFIX` | `oauth:code:` | `redis-code-repository.keyPrefix`: the Redis repository's key namespace (see [Redis Namespacing](#redis-namespacing)) |
+| `STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN` | `600` | `standalone-in-memory-code-repository.defaultExpiresIn`: the in-process repository's, a positive whole number of seconds |
+
+`CLIENT_CODE_DEFAULT_EXPIRES_IN` and `CLIENT_CODE_KEY_PREFIX` were renamed
+with them, and `CLIENT_CODE_ENDPOINT_URI` and `CLIENT_CODE_PASSWORD` removed. A
+renamed one set alone, or beside its new name at a different value, and a
+removed one set at all, fails boot naming what to set instead.
 
 ### Federation Token Store
 
 The upstream IdP tokens (a Google refresh token, say) held on behalf of a
 session. Memory by default, which forks per replica and is refused under
-`DEPLOYMENT_MODE=multi`; the Redis store shares the socket configured by
-`REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` and encrypts records at rest, so it
+`CORE_DEPLOYMENT_MODE=multi`; the Redis store shares the socket configured by
+`REDIS_CLIENTS_URL` and encrypts records at rest, so it
 needs a key.
 
 | Variable | Default | Description |
 |---|---|---|
-| `FEDERATION_TOKEN_STORE_TYPE` | `memory` | Federation token store backend: `memory` or `redis` |
+| `ADAPTERS_FEDERATION_TOKEN_STORE` | `memory` | Federation token store backend: `memory` or `redis` |
 | `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` | — | AES-256-GCM key for records at rest: 32 bytes, base64-encoded (`openssl rand -base64 32`). **Required** with `redis` unless the mode below is `allow-plaintext` |
-| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused when the config was selected by a production/staging environment (`CONFIG_ENV` or `NODE_ENV`) and under `DEPLOYMENT_MODE=multi` in any environment, unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` is also set — development only |
+| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused when the config was selected by a production/staging environment (`CONFIG_ENV` or `NODE_ENV`) and under `CORE_DEPLOYMENT_MODE=multi` in any environment, unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` is also set — development only |
 
 `ttl` (seconds; keep it above the upstream refresh-token lifetime) and the #291
-`scanFallback` migration flag live under `redisFederationTokenStore` in a
+`scanFallback` migration flag live under `redis-federation-token-store` in a
 config layer rather than behind an environment variable.
 
 ### Consent Store
@@ -438,12 +757,87 @@ Where an end-user's consent to a client that is not first-party is recorded,
 together with the `/authorize` request parked while the consent page asks
 (#527, #552). One switch wires both. `none` by default: such clients are
 refused and only first-party clients are served. `memory` forks per replica and
-is refused under `DEPLOYMENT_MODE=multi`; `redis` (#561) shares both over the
-socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`.
+is refused under `CORE_DEPLOYMENT_MODE=multi`; `redis` (#561) shares both over the
+socket configured by `REDIS_CLIENTS_URL`.
 
 | Variable | Default | Description |
 |---|---|---|
-| `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) |
+| `ADAPTERS_CONSENT_STORE` | `none` | Consent store for clients that are not first-party (#527): `none` (such clients are refused), `memory` (single replica) or `redis` (shared, #561) |
+
+### Multi-factor authentication
+
+A second factor after a password login, and a step-up when a relying party
+asks for one at `/authorize` — the [MFA package](../../packages/mfa/README.md).
+`MFA_MODE` is the template's own switch, `mfaMode`
+([`config/reference.conf`](config/reference.conf)): `required`, the default
+(every password login has a second factor), and `optional` (a user with a
+factor is challenged, nobody is forced) install the MFA module, the TOTP, recovery-code and email factors (email off
+unless `MFA_EMAIL_FACTOR_ENABLED`), the operator reset
+(`handle.components.mfaReset`), the session package's login completion and
+the two MFA stores `adapters` selects. The template then adds `mfa` to
+`core.sessionRequirements.expected`, names it
+`core.sessionRequirements.secondFactorAuthority` and writes `mfa.mode` from
+the switch, so
+a composition that asks for a second factor and cannot enforce one is refused
+at boot rather than let a password alone sign in; `off` installs nothing of
+MFA. A value that is none of the three is refused before boot, naming
+`mfaMode` and `MFA_MODE`.
+
+**On by default.** In development (`make dev`) MFA needs nothing more: the
+sample key in `config/development.conf`, the sender that logs each code, and
+`docker-compose.yml`'s Redis for the two stores. Outside development a
+deployment either sets what MFA needs — the two stores on `redis` (or the
+factors in the `store`), `MFA_ENCRYPTION_KEY` and the SMTP relay
+(`STANDARD_SMTP_MAIL_SENDER_HOST` and `_FROM`, or a sender of its own through
+`buildModules`' `mailSenderModules`) — or sets `MFA_MODE=off`. Until it
+decides, the boot is refused before the app is created: the stores' refusal
+comes first, naming each of those and `MFA_MODE=off`. The MFA page is never
+refused: `MFA_PAGE_URL` defaults to `/mfa`, which the deployment must serve,
+in development too, or every password login stops there.
+
+| Variable | Default | Description |
+|---|---|---|
+| `MFA_MODE` | `required` | `mfaMode`: `required`, `optional` or `off` |
+| `MFA_ENCRYPTION_KEY` | — | The MFA key ring's first key, which seals every factor's data: canonical base64 of 32 bytes (`openssl rand -base64 32`). Required with MFA on. Under `CONFIG_ENV=development`, `config/development.conf` puts the MFA package's published sample key in its place: write your own key there instead, since this variable set beside that ring refuses the boot. The sample key is refused under `CONFIG_ENV` or `NODE_ENV` `production` or `staging` and under `CORE_DEPLOYMENT_MODE=multi` |
+| `MFA_PAGE_URL` | `/mfa` | The deployment's MFA page, where a login's second factor and a step-up start. The template ships no page: the page contract is the [MFA package's](../../packages/mfa/README.md#the-routes) |
+| `MFA_STORE_TIMEOUT_MS` | `5000` | `mfa.storeTimeoutMs`, one Store call's time: at least every store's own per-call timeout. Below `REPOSITORIES_USER_HTTP_TIMEOUT` where the Store is called (`ADAPTERS_USER_REPOSITORY=http`, or the factors in the Store) the boot is refused, so raise the two together; above 37500 ms it is refused too |
+| `STANDARD_SMTP_MAIL_SENDER_HOST` | — | The SMTP relay outside development, where MFA mails the account-email proof and the email factor's codes. With MFA on, the boot needs it and `STANDARD_SMTP_MAIL_SENDER_FROM` |
+| `STANDARD_SMTP_MAIL_SENDER_FROM` | — | The one sender address of that mail |
+| `STANDARD_SMTP_MAIL_SENDER_PORT` | `587` | The relay's port |
+| `STANDARD_SMTP_MAIL_SENDER_SECURE` | `starttls` | `starttls`, `tls`, or `none` to a loopback relay only |
+| `STANDARD_SMTP_MAIL_SENDER_USER` | — | The relay account, with `STANDARD_SMTP_MAIL_SENDER_PASSWORD` |
+| `STANDARD_SMTP_MAIL_SENDER_PASSWORD` | — | That account's password |
+
+The rest of the MFA settings — each factor's, the lock, a transaction's life
+— are the MFA package's, with their variables, in its
+[README](../../packages/mfa/README.md#configuration). A few things to know:
+
+- **The stores.** `memory`, the shipped selection, is for development and
+  test alone: a restart loses every factor, lock and recorded email proof,
+  after which whoever holds a password can bind a factor of their own. With
+  MFA on it is refused before boot unless the configuration's name, and
+  `CONFIG_ENV` and `NODE_ENV` wherever set, each say `development` or
+  `test`, and core refuses it under `CORE_DEPLOYMENT_MODE=multi`. Production
+  needs `redis` for both, or `store` for the factors: `redis` shares the
+  socket `REDIS_CLIENTS_URL` opens; `store` (factors only) keeps them behind the Store's four endpoints
+  (`FOUNDATION_MFA_FACTOR_STORE_*`,
+  [foundation's README](../../packages/foundation/README.md)), sent the same
+  bearer token as the user repository.
+- **The enrollment witness.** With `ADAPTERS_USER_REPOSITORY=http`, set
+  `REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` ([User Repository](#user-repository));
+  without it, boot warns once (`mfa_enrollment_witness_unwritable`).
+- **`acr`.** With MFA on, the template adds `"urn:o3co:acr:mfa" = ["mfa"]`
+  to `oauth.authorize.acrValues`, unless your configuration writes that
+  entry, and discovery advertises it. With MFA off it adds nothing: the acr
+  table and discovery are what they are without MFA.
+- **The mail in development.** Under `CONFIG_ENV=development` the template's
+  sender logs each code (`mail_code_issued`) and sends nothing. To run the
+  SMTP sender and read what it sends, use the
+  [Mailpit overlay](#mailpit-for-the-smtp-sender-development-only).
+- **One switch.** A file that writes `mfaMode` while `MFA_MODE` is set to
+  something else, and a configuration that writes `mfa.mode` other than
+  what the switch says, are refused before boot, naming the keys. While MFA
+  is off, nothing the configuration writes under `mfa` is handed to boot.
 
 ### Federation Grants
 
@@ -459,29 +853,35 @@ needs before it issues a refresh token is in
 
 | Variable | Default | Description |
 |---|---|---|
-| `FEDERATION_GRANTS_ENABLED` | `false` | Installs the routes, the two stores below and the subject-revocation service |
+| `FEDERATION_GRANTS_ENABLED` | `false` | Installs the routes, the two stores selected below (none until selected) 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` |
+| `ADAPTERS_FEDERATION_GRANT_STORE` | `none` | Where grants live: `none` (no store; an enabled feature refuses boot naming it), `memory` (one replica; lost on restart, every user reconnects) or `redis` (the shared socket) |
+| `ADAPTERS_FEDERATION_GRANT_INTENT_STORE` | `none` | Where acquisition's records live — the intent a backend lodged, the consent challenge, the connect transaction: `none` (no store; an enabled feature refuses boot naming it), `memory` (one replica; a restart loses flows in progress and nothing else) or `redis` |
+| `REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused in production/staging and under `CORE_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 |
+| `REDIS_FEDERATION_GRANT_INTENT_STORE_KEY_PREFIX` | `fg:` | Key namespace of the Redis intent store; set it with the grant store's — the template refuses to boot with the grant store's set and this one left at its default |
 
-**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:
+The feature's own settings are the `federation-grants {}` section; the Redis
+grant store's — its key ring, its encryption mode, its prefix — are
+`redis-federation-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 {
+redis-federation-grant-store {
   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} }
   ]
+}
+
+federation-grants {
   connections {
     files {
-      federation = "entra-files"   # an enabled federations.<name> of type "oidc", with an app registration of its own
+      federation = "entra-files"   # an enabled core.federations.<name> of type "oidc", with an app registration of its own
       scopes = ["openid", "profile", "offline_access", "Files.Read"]
       boundary = "production"
       maxAccessTokenLifetime = 3600
@@ -501,15 +901,15 @@ 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
+(`ADAPTERS_USER_SESSION_STORES=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`.
+nothing and needs none); `memory` for either store under `CORE_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
+(#613): set `REPOSITORIES_USER_HTTP_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:
 
@@ -560,9 +960,21 @@ is `/oauth/consent`'s, so one page can serve both. `GET
 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
+or back to the client. Every acquisition and renewal goes through it. The
+answer is held to the session module's CSRF policy: post it as a form from the
+page, and serve the page with `Referrer-Policy: same-origin` — not
+`no-referrer`, whether by the header, `<meta name="referrer">` or
+`rel="noreferrer"` on the form, under which the browser sends `Origin: null`
+and the answer is refused. This app's `helmet()` sends `no-referrer` on every
+response, so a page it serves sets `Referrer-Policy: same-origin` on its own
+route. Behind a proxy, `HTTP_TRUST_PROXY` names it, and it forwards
+`X-Forwarded-Proto` and `X-Forwarded-Host` (or keeps the browser's `Host`). A
+user agent that sends neither `Origin` nor `Referer` echoes the token
+`GET /session/csrf` hands out, as for `POST /session/login`; a page may always
+include it, since it counts only when neither is sent. The package README has
+the rule.
+
+**The login page** is the one `SESSION_LOGIN_PAGE_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
@@ -586,10 +998,10 @@ auth.provider instances cannot collide in the same database:
 | Variable | Default | Description |
 |---|---|---|
 | `REDIS_SESSION_STORES_KEY_PREFIX` | `ss:` | Outer prefix for user sessions, RP registry, session-family index, and session-federation index. |
-| `REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
-| `CLIENT_CODE_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
+| `REDIS_REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
+| `REDIS_CODE_REPOSITORY_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
 | `REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX` | `ft:` | Prefix for federation token records, their per-session index and their lock keys. |
-| `REDIS_CONSENT_STORE_KEY_PREFIX` | `consent:` | Prefix for consent records and for parked consent requests with their per-session index (`CONSENT_STORE_ADAPTER=redis`, #561). |
+| `REDIS_CONSENT_STORE_KEY_PREFIX` | `consent:` | Prefix for consent records and for parked consent requests with their per-session index (`ADAPTERS_CONSENT_STORE=redis`, #561). |
 
 Use values that include the deployment name, for example `tenant-a:ss:`,
 `tenant-a:rtfam:`, `tenant-a:code:`, `tenant-a:ft:`, and `tenant-a:consent:`.
@@ -598,40 +1010,30 @@ Use values that include the deployment name, for example `tenant-a:ss:`,
 
 | Variable | Default | Description |
 |---|---|---|
-| `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) |
+| `SESSION_LOGIN_PAGE_URL` | `/login` | URL of the login page (for redirects) |
+| `OAUTH_CONSENT_PAGE_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 (`CORE_FEDERATIONS_GOOGLE_CALLBACK_URL`,
+`CORE_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-store.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 — `adapters.federationTokenStore`, `adapters.userSessionStores`, `adapters.rateLimiter`, `adapters.codeRepository`, `adapters.accessTokenDenylist`, `adapters.replaySeenSet`, `adapters.consentStore`, the two federation-grant store switches and the two MFA store switches — picks one of a memory / Redis pair (or, for the MFA factors, the Store). Both provide the same slot, so wiring both is a boot-time slot collision. `adapters.consentStore = "none"` wires neither, the federation-grant stores are wired only while the feature is enabled, and the MFA stores only while `MFA_MODE` installs MFA.
+4. **The shared Redis connection comes with the first Redis-backed module.** `standaloneRedisClientsModule` opens the one ioredis connection every Redis adapter here uses, from its own section (`redis-clients`), 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. **The template's own settings modules are always composed.** `loggingModule` and `httpModule` own `logging {}` and `http {}`, the CORS list among `http`'s keys (`http.cors.allowedOrigins`). `httpModule` provides core's `httpSettings`, which is authoritative, so no `overrideComponents` entry replaces it while the module is loaded; it also provides the template's `httpHostSettings`, which `app.mts` reads after boot for the port and the readiness deadline. The logger is built before boot from the `logging` section (`readLogging`), not by a module, and handed to boot as the `logger` component.
+6. **A federation adapter comes with its config bridge.** `googleFederationModule` with `googleFederationConfigModule` — only for an enabled `core.federations.google` entry 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.
+7. **The mail sender follows the environment.** `@o3co/auth-provider-standard`'s development sender, which logs each code, where the configuration was selected as `development`; its module installs only where that name, and `CONFIG_ENV` and `NODE_ENV` wherever they are set, each read `development` or `test`, and refuses the boot otherwise, or where `core.deployment.mode` is `multi`. Under any other name, the SMTP sender's module, whose section is `standard-smtp-mail-sender` ([the package's README](../../packages/standard/README.md)); its sender is built only where something reads the `mailSender` slot, and there the boot needs `STANDARD_SMTP_MAIL_SENDER_HOST` and `STANDARD_SMTP_MAIL_SENDER_FROM`. While `MFA_MODE` is `off` nothing reads the slot, so the template boots without them; with MFA on, the MFA module and the operator reset read it. A sender of your own replaces this choice: pass its module where [`src/app.mts`](src/app.mts) calls `buildModules`, as `buildModules(switches, { environment: env, logger, mailSenderModules: [mySenderModule] })`. Given, `mailSenderModules` is installed under every environment name and the bundled sender is not, so the two never both provide the slot; an empty list installs no sender, and a module that needs one (the MFA email factor, or the MFA module with `requireEmailProof = "always"`) then refuses the boot.
+
+`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 |
 |---|---|---|
@@ -663,11 +1065,13 @@ make test
 The `docker-compose.yml` starts the auth server together with a Redis container. Configure environment variables in `.env`.
 
 `docker-compose.yml` is a **development** file: it builds the `develop` target and bind-mounts `./src` and `./config`, so deploying it ships a hot-reload server running your working tree. The deployable shape is
-[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target, no source mounts, restart policies, a network-internal persistent Redis, and a **required** `.env` (a boot without a real `SESSION_SECRET` must fail loudly). Its header comments state what it deliberately leaves to you: TLS termination in front, and the [multi-replica](#multi-replica-deployments) steps before any `--scale`.
+[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target, no source mounts, restart policies, a network-internal persistent Redis, and a **required** `.env` (a boot without a real `SESSION_STORE_SECRET` must fail loudly). Its header comments state what it deliberately leaves to you: TLS termination in front, and the [multi-replica](#multi-replica-deployments) steps before any `--scale`.
 
 `HTTP_TRUST_PROXY` is an explicit `${HTTP_TRUST_PROXY:?…}` entry there, so `docker compose up` **refuses to start** until you name the hop in `.env`. That is deliberate: there is no address the file could default to that would not silently trust a hop you never chose, and without the variable the Secure cookie the file pins is never set, the CSRF origin check 403s every browser POST, and every IP-keyed rate limit shares one bucket.
 
-Every store whose records must outlive one process is named in that file's `environment:` block rather than inherited — including `USER_SESSION_STORES_ADAPTER=redis`, which has to travel with `SESSION_STORAGE_TYPE=redis`. `DEPLOYMENT_MODE=single` will not tell you when it does not: the replica guard answers "can these stores be shared", not "do these two stores have the same lifetime". Split them and a restart leaves every browser holding a surviving express-session that still reads `isAuthenticated` with no `UserSession` behind it — `/authorize` bounces to login, the cookie bounces it back, and the loop clears only when the user deletes the cookie.
+Every store whose records must outlive one process is named in that file's `environment:` block rather than inherited — including `ADAPTERS_USER_SESSION_STORES=redis`, which has to travel with `SESSION_STORE_STORAGE_TYPE=redis`. `CORE_DEPLOYMENT_MODE=single` will not tell you when it does not: the replica guard answers "can these stores be shared", not "do these two stores have the same lifetime". Split them and a restart leaves every browser holding a surviving express-session that still reads `isAuthenticated` with no `UserSession` behind it — `/authorize` bounces to login, the cookie bounces it back, and the loop clears only when the user deletes the cookie.
+
+The two MFA stores are the exception, since MFA is on by default and whether to keep it is the deployment's decision: the production file leaves them at `memory`, which the template refuses in production before boot, naming the stores, `MFA_ENCRYPTION_KEY`, the SMTP relay, `MFA_PAGE_URL` and `MFA_MODE=off`. Set them in `.env` — `ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`, on the file's persistent Redis, with the rest of [Multi-factor authentication](#multi-factor-authentication) — or set `MFA_MODE=off`. `docker-compose.yml` keeps both on its Redis, so that a hot reload does not empty them while the sessions survive.
 
 ```bash
 # The signing keys are a required input: EdDSA is the default and there is no
@@ -676,20 +1080,33 @@ openssl genpkey -algorithm ed25519 -out jwt-private.pem
 openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 chmod 600 jwt-private.pem
 
+# The client registry is a required input too: the scaffold's
+# config/clients.yaml, or one made from config/clients.yaml.example.
+
 docker compose -f docker-compose.production.yml up -d --build
 ```
 
 **Keys in containers.** The pem pair reaches the container as a compose
 **secret**, mounted read-only at `/run/secrets/`, and the compose file points
-`OAUTH_JWT_*_KEY_PATH` there. Do not park them in `config/`: the `Dockerfile`
-`COPY`s that directory, so a key placed there is baked into an image layer and
-travels with every push — a key you then have to rotate rather than one you
-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
+`KEY_STORE_LOCAL_*_KEY_PATH` there. Do not park them in `config/`: the `Dockerfile`
+`COPY`s that directory. `.dockerignore` keeps every `*.pem` and `*.key` out of
+the build context, as `.gitignore` keeps them out of git, but a key under any
+other name placed there is baked into an image layer and travels with every
+push — a key you then have to rotate rather than one you merely stored badly.
+The same applies to `.env`; keep both out of git.
+
+**The client registry in containers.** `config/clients.yaml` arrives the same
+way, as the compose secret `client_registry`, with `REPOSITORIES_CLIENT_YAML_PATH` pointed at it.
+It is per-deployment and may hold client secrets, so `.dockerignore` keeps it
+out of the build context: no image carries a registry, and an image built from
+a working copy is the same as one built from a clean checkout. Compose refuses
+to start until the file exists. Run the image some other way and you mount it
+and set `REPOSITORIES_CLIENT_YAML_PATH` yourself.
+
+The production file also pins `SESSION_STORE_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_STORE_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
@@ -699,7 +1116,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
@@ -709,6 +1126,47 @@ docker run -e HTTP_PORT=8080 -p 8080:8080 my-auth-provider
 `EXPOSE` is image metadata and does not publish ports by itself, so the
 explicit `-p` mapping is still required.
 
+### Mailpit for the SMTP sender (development only)
+
+[`docker-compose.mailpit.yml`](docker-compose.mailpit.yml) is an overlay on
+`docker-compose.yml` that adds [Mailpit](https://mailpit.axllent.org/), a mail
+catcher, so a development run with MFA on sends its mail — the account-email
+proof, the email factor's codes — through the SMTP sender instead of the
+development sender, which only logs each code:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
+```
+
+Read the mail at <http://localhost:8025>. Mailpit keeps it and delivers
+nothing onward. A plain `docker compose up` (`make dev`) starts no Mailpit, and
+the production file names none. It is for development only: a deployment
+names a real relay with the `STANDARD_SMTP_MAIL_SENDER_*` variables
+([Multi-factor authentication](#multi-factor-authentication)).
+
+What the overlay sets on the app service:
+
+- `CONFIG_ENV=mailpit`. Under `development` the template installs the sender
+  that logs each code ([Module Composition Order](#module-composition-order),
+  rule 7). [`config/mailpit.conf`](config/mailpit.conf) includes
+  `development.conf`, so the run is otherwise the development one, the MFA
+  sample key included.
+- Nothing of `MFA_MODE`: MFA is on as the template ships it, or as your
+  `.env` sets it. With MFA off nothing sends mail.
+- `ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`,
+  on the compose Redis, as `docker-compose.yml` sets them: under a name other
+  than `development` or `test` the MFA stores may not be kept in memory.
+- `STANDARD_SMTP_MAIL_SENDER_HOST=localhost`,
+  `STANDARD_SMTP_MAIL_SENDER_PORT=1025`, `STANDARD_SMTP_MAIL_SENDER_SECURE=none`
+  and `STANDARD_SMTP_MAIL_SENDER_FROM=auth@example.com`. The SMTP sender sends
+  in plaintext only to a loopback host, so Mailpit runs in the app container's
+  network namespace (`network_mode: service:app`) and listens on its
+  `localhost`; the app service therefore publishes Mailpit's web UI, on
+  loopback.
+
+It is an overlay rather than a compose profile because a profile only adds
+services: it cannot change the app service's environment or ports.
+
 ### Health endpoints
 
 Two routes, answering two different questions. Both are mounted on the host
@@ -756,7 +1214,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
@@ -772,9 +1231,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;
@@ -783,43 +1243,24 @@ 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 || mfaInstalled ? [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()`. The exception is a mail sender of your own: it goes in through the `mailSenderModules` override in that call (rule 7), not into the list, where it would collide with the bundled sender on the `mailSender` slot.
+
+A module that contributes a session requirement changes what "logged in" means, so its name goes in `core.sessionRequirements.expected`, which `config/application.conf` ships as `[]`. Boot compares the list with what the modules register. A name listed that nothing registers refuses the boot (`session-requirement-missing`), and so does a registered requirement the list leaves out (`session-requirements-undeclared`). When `MFA_MODE` installs MFA, the template adds `mfa` to the list (`expectedSessionRequirements`, [`src/configPath.mts`](src/configPath.mts)), keeping the names you wrote, and writes `core.sessionRequirements.secondFactorAuthority = "mfa"` beside it; a value of your own there other than `mfa` is refused before boot. The MFA module it installs registers `mfa` and declares the second-factor authority. Core refuses a declared authority whose requirement does not declare it (`second-factor-authority-not-declared`), a second requirement named `mfa`, and a second requirement declaring the authority (`duplicate-second-factor-authority`), so a module you add cannot stand in for it. Install MFA through `MFA_MODE`, not by adding its modules to the list: the template would install them a second time.
+
 ### 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.
@@ -828,9 +1269,22 @@ 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 (see the table below). 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. **`cleanup` gets at least the allowance the modules registered**: `handle.cleanupAllowanceMs`, the longest tail a module registered its cleanup with, which `src/app.mts` hands `installGracefulShutdown` as `cleanupAllowanceMs: () => handle.cleanupAllowanceMs`, read when the signal arrives; cleanup's budget is the longer of it and the drain's ten, and `shutdown_draining` logs it as `cleanupTimeoutMs`. An allowance that is not a whole number of milliseconds from 1 to 2147483647 is ignored. The template reads no module's settings to size it. With federation grants on, the package registers its drain's tail as `federation-grants.upstreamHardTimeoutMs` + `persistRetryBudgetMs` + `lockWaitMs` + 12 s, never below 45 s — exactly 45 s under the shipped budgets (25 + 3 + 5 + 12) — 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, nothing registers an allowance and the cleanup budget stays the drain's.
 
-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.
+Each stage logs one line:
+
+| Event | Level | Fields |
+|---|---|---|
+| `shutdown_draining` | info | `drainTimeoutMs`, `cleanupTimeoutMs` |
+| `shutdown_drain_deadline_exceeded` | error | `drainTimeoutMs` |
+| `shutdown_server_close_failed` | error | `err` |
+| `shutdown_cleanup_timed_out` | error | `cleanupTimeoutMs` |
+| `shutdown_cleanup_failed` | error | `err` |
+| `shutdown_complete` | info | `reason`, `drain`, `exitCode` |
+
+`err` is the `loggableError` projection. `drain` is how the drain ended: `drained`, `drain-timeout` or `close-failed` (a listener that did not come down is not a clean drain, and exits non-zero). `reason` is what decided `exitCode`: the drain's outcome, or `cleanup-timeout` / `cleanup-failed` when the cleanup then timed out or threw, so `reason: "drained"` never sits beside a non-zero code.
 
 **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.
 
@@ -839,9 +1293,9 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 | 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
 
@@ -857,8 +1311,9 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 ### Logging
 
 The provider logs newline-delimited JSON on stdout via [pino](https://getpino.io),
-which is what a log aggregator ingests without a parser. `LOG_LEVEL` (HOCON
-`logging.level`) sets the threshold; `trace` and `debug` carry request-shaped
+which is what a log aggregator ingests without a parser. `LOGGING_LEVEL` (HOCON
+`logging.level`, the `logging` module's section, read before boot with that
+module's schema) sets the threshold; `trace` and `debug` carry request-shaped
 detail and are off by default, and pino drops sub-threshold calls before
 formatting, so they cost nothing in production rather than being emitted and
 filtered downstream.
@@ -866,7 +1321,7 @@ filtered downstream.
 The logger is wired into the boot planner's `logger` component slot, so every
 module that declares `optional: ["logger"]` — oauth, session, dpop, mtls,
 token-exchange — logs through this one instance. Filling that slot is what makes
-`LOG_LEVEL` reach them; a composition root that leaves it empty gets each
+`LOGGING_LEVEL` reach them; a composition root that leaves it empty gets each
 module's own `consoleLogger` default instead, and configuring a level changes
 nothing.
 
@@ -881,7 +1336,7 @@ shape, so a pino-compatible logger needs no adapter.
 
 Security-relevant events — who authenticated, what was issued, what was refused,
 and when the rate limiter could not answer — go to the sink named by
-`audit.sink.type` (env `AUDIT_SINK_TYPE`). The template ships `"logger"`, which
+`adapters.auditSink` (env `ADAPTERS_AUDIT_SINK`). The template ships `"logger"`, which
 writes one event per line through the same pino stream as everything else:
 
 ```json
@@ -894,40 +1349,46 @@ The event type is also the message, so alert on the name — `authorize.rejected
 `token.issued.failure`, `rate_limit.unavailable` — the same way you would on
 `session_store_redis_error`.
 
-`AUDIT_SINK_TYPE=console` selects core's built-in sink instead: the bare event
+`ADAPTERS_AUDIT_SINK=console` selects core's built-in sink instead: the bare event
 as one JSON object per line, with no log envelope, for a pipeline that wants the
 event and nothing else.
 
-**`LOG_LEVEL` does not gate the audit trail.** The audit stream's level is fixed
+**`LOGGING_LEVEL` does not gate the audit trail.** The audit stream's level is fixed
 at `info`. `warn` is an ordinary production setting and `silent` a legitimate
 one, and either silencing this would delete the record of every authentication
 and issuance while looking like a logging preference. Where audit events go is
-chosen by `audit.sink.type` — and that selector has **no `"none"`**. An unknown
-type fails boot naming the sinks that are registered, rather than producing a
-deployment with no audit trail.
+chosen by `adapters.auditSink` — and that selector has **no `"none"`**. An unknown
+sink fails boot naming the sinks that are registered, rather than producing a
+deployment with no audit trail. A composition that installs no sink on purpose
+says so in core's own section, `core.declaredAbsent = ["auditSink"]`; this
+template always installs one.
 
 To point it at a real sink — SIEM, log pipeline, message bus — register a
-builder in `auditSinkModule` (`src/modules.mts`) and name it in config; its
-options ride along in the same block:
+builder in `auditSinkModuleFor` (`src/modules.mts`) and select it; its options
+are the `audit-sink` module's section, under the sink's name:
 
 ```ts
 factory.register("splunk-hec", (cfg) => createSplunkSink(cfg));
 ```
 
 ```hocon
-audit {
-  sink {
-    type = "splunk-hec"
-    splunk-hec { endpoint = ${?SPLUNK_HEC_URL}, token = ${?SPLUNK_HEC_TOKEN} }
-  }
+adapters.auditSink = "splunk-hec"
+audit-sink {
+  splunk-hec { endpoint = ${?SPLUNK_HEC_URL}, token = ${?SPLUNK_HEC_TOKEN} }
 }
 ```
 
+To add an audit destination beside the configured one, contribute
+`auditHooks` from your own module; core fans out `auditSink` and `auditHooks`
+together.
+
 Sinks are fire-and-forget by contract: core dispatches without awaiting and
 swallows rejections, so a slow or failing sink cannot add latency to — or
 fail — an auth flow. The flip side is that a sink which cannot deliver drops
-events silently, and those drops are not counted yet — see **Not published
-yet** under Metrics below.
+the event. On its own a sink's failure is swallowed silently; once a module
+contributes `auditHooks`, the fan-out logs each failing call at error as
+`audit_sink_failed`, with the sink's position and the event's `type`. The
+drops are not counted yet — see **Not published yet** under Metrics below.
 
 ### Metrics