@o3co/create-auth-provider 0.16.0 → 0.17.0-rc.2

package/templates/standalone/README.md

@@ -1,6 +1,6 @@
 # @o3co/auth-provider-standalone
 
-Last updated: 2026-09-26
+Last updated: 2026-10-06
 
 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`.
 
@@ -11,20 +11,27 @@ not a library: nothing imports it. `@o3co/create-auth-provider` copies it into
 a new project, and from then on the operator owns and edits the copy. It sits
 on top of the packages: it composes `@o3co/auth-provider-oauth`, `-session`,
 the Google and generic OpenID Connect federation adapters, `-federation-grants`,
-`-redis` and `-foundation` over `@o3co/auth-provider-core`.
+`-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 modules only this scaffold has — the signing key store, the client and
-  user repositories, the audit sink, the one shared Redis connection, the
-  in-memory user-session stores, code repository and federation token store,
-  and the federation config bridges — [`src/modules.mts`](src/modules.mts).
-  They are the scaffold's rather than a package's because each builds its
-  component from this template's configuration sections; a deployment that
-  wants another source wires its own module of the same shape;
+  [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 —
+  [`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 —
@@ -71,7 +78,7 @@ repository.
 - **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 replay seen-set, the user-session stores, the federation-token store, the consent stores and the federation-grant stores — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica. The same module provides the client of every other store the Redis package ships — the device-code store and the WebAuthn challenge store — so a deployment that adds the device grant or WebAuthn to `buildModules.mts` with a Redis store finds its client there. The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
+- **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
 
@@ -79,7 +86,7 @@ For a client marked `firstParty: true`, `GET /authorize` mints an authorization
 
 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. Every other client — one with no `firstParty` field and one carrying `false` alike — goes through the consent step: the user is asked on your consent page before a code is minted. That step needs a consent store, and the template ships none (`CONSENT_STORE_ADAPTER=none`), so on the defaults such a client is refused at `/authorize` with `unauthorized_client`; see [Consent Store](#consent-store) to serve it. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
+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
@@ -97,13 +104,13 @@ 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.
 
-**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.
+**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 rather than being silently ignored: the oauth module refuses the key as removed (`config-path-relocated`), and the variable as one bound to a removed key (`environment-variable-renamed`). Mark your clients, then delete the key and unset the variable.
 
 ## 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`. 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.
 
@@ -120,7 +127,11 @@ 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. 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. `/session/login` does not run on this component, nor does `POST /oauth/device/verification` once you add the device grant: each one's own attempt limit (`session.rateLimit.login`, `device-grant.rateLimit`) is counted on the attempt counter, and no limiter setting changes it.
+
+**The MFA routes' budget is the limiter's.** The MFA package ships no budget for its routes: every `/session/mfa` POST is limited per client address under the prefix `mfa` by the wired limiter alone. `config/reference.conf` gives both limiters `limits.mfa { limit = 60, windowSeconds = 300 }` (`core-rate-limiter-memory.limits.mfa`, `redis-rate-limiter.limits.mfa`), so switching `adapters.rateLimiter` keeps it. It is a default there, so the limiter the composition does not wire carries it without boot naming its section; change it for the wired limiter in `config/application.conf` or a layer of your own. Without an entry the limiter's `defaultLimit`, 60 per 60 s, applies. The MFA lock — attempts per transaction, the backoff, the weekly failures — is the MFA package's own and no limiter setting changes it.
+
+**Point `adapters.attemptCounter` at Redis.** It defaults to `"memory"`, which wires no counter: the login — and device verification, when you add the device grant — counts its attempts per process, so with N replicas `session.rateLimit.login` (and `device-grant.rateLimit`) allows N times its limit and resets on every deploy, and `CORE_DEPLOYMENT_MODE=multi` refuses the boot. `"redis"` (`ADAPTERS_ATTEMPT_COUNTER=redis`) installs `redisAttemptCounterModule` on the shared Redis socket. Its Redis must run `maxmemory-policy noeviction` (Redis's default): an evicted window would start the count over. The module refuses to boot on any other policy it reads; when the server will not tell it (`INFO` and `CONFIG` refused or renamed) it boots and warns `attempt_counter_durability_unchecked`, so confirm the policy where the server is configured. Both fail closed: while the counter cannot answer, `/session/login` and `POST /oauth/device/verification` answer `503`, whatever `redis-rate-limiter.failMode` says.
 
 **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
@@ -143,10 +154,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 }
@@ -154,9 +166,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
@@ -165,21 +177,23 @@ 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, a single-use client assertion or WebAuthn challenge replayable once per replica. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `RATE_LIMITER_ADAPTER=memory`). With the mode unset nothing is refused: every one of them is listed in a single `replica_unsafe_adapters` warning at boot. (The login and WebAuthn-options routes carry per-process fallback limiters that warn on their own, but only in a composition that wires no `rateLimiter` at all, which this template never does; see the operator runbook.) With `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica. This template does not install DPoP; a composition that adds it records every accepted proof in the same replay seen-set as `private_key_jwt` (`REPLAY_SEEN_SET_ADAPTER`), so it gets the same answer — `memory` is refused under `DEPLOYMENT_MODE=multi` and listed in the unset-mode warning, and the shipped `redis` shares DPoP's records across replicas — see the dpop package's [operator requirements](../../packages/dpop/README.md#operator-requirements).
+**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 WebAuthn-options route carries a per-process fallback limiter that warns on its own, but only in a composition that wires no `rateLimiter` at all, which this template never does. The login counts per process under `ADAPTERS_ATTEMPT_COUNTER=memory`: `multi` refuses the boot, naming the login, and an unset mode warns `attempt_counter_not_shared`; 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. `oauth.code.adapter` wins; the deprecated `repositories.code.type` (`CLIENT_CODE_TYPE`) is read, with a `config_key_deprecated` warning at boot, only when it is unset — which the shipped `config/application.conf` never leaves it. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is bound by `config/application.conf` but nothing reads it: the Redis code repository runs on the shared connection, so there is one Redis URL for every adapter.
-- The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `replaySeenSet.adapter` (`REPLAY_SEEN_SET_ADAPTER`); the template ships `"redis"` on the shared connection, and `memory` is refused under `DEPLOYMENT_MODE=multi` because a captured client assertion would replay once per replica.
-- The consent step for clients that are not first-party (#527) switches on `consentStore.adapter` (`CONSENT_STORE_ADAPTER`). It is off (`none`) by default; `memory` is refused under `DEPLOYMENT_MODE=multi`, because a consent granted on one replica would be asked for again on every other and a consent page's parked request would be unknown to the replica that receives the answer. `redis` (#561) keeps both on the shared connection. See [Consent Store](#consent-store).
-- The federation token store defaults to memory. Set `FEDERATION_TOKEN_STORE_TYPE=redis` (`federationTokenStore.type = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`. See [Federation Token Store](#federation-token-store).
-- Federation grants (#593), when enabled, keep two more stores: the grants themselves (`FEDERATION_GRANT_STORE_ADAPTER`) and acquisition's records (`FEDERATION_GRANT_INTENT_STORE_ADAPTER`). Both ship `redis` on the shared socket; `memory` for either is refused under `DEPLOYMENT_MODE=multi`, and Redis grants beside memory user-session stores are refused on any replica count, because the grants would outlive the boundary that ends them. See [Federation Grants](#federation-grants).
+- 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
 
@@ -189,26 +203,37 @@ shell that starts it — and it does not boot until that environment supplies:
 
 - `OAUTH_JWT_ISSUER` — this server's origin (`http` is accepted for a loopback
   host);
-- a signing key pair, `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH`
+- a signing key pair, `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` / `KEY_STORE_LOCAL_PUBLIC_KEY_PATH`
   (see [OAuth JWT](#oauth-jwt));
-- `SESSION_SECRET`, at least 32 bytes;
-- `CLIENT_USER_AUTHENTICATE_URL` and `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` —
+- `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_STORAGE_REDIS_URL`), and
-  opens one shared connection (`REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`) for the
+  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_SECURE=false` and a session cookie name without
+Plain HTTP also needs `SESSION_STORE_SECURE=false` and a session cookie name without
 the `__Host-` prefix (see [Session](#session)). And set
-`USER_SESSION_STORES_ADAPTER=redis`: the browser session store is in Redis, the
+`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
@@ -229,13 +254,14 @@ docker run -d --name auth-redis -p 127.0.0.1:6379:6379 redis:7.2-alpine
 
 # What boot requires (replace the user-service URLs with your Store's)
 export OAUTH_JWT_ISSUER=http://localhost:3000 \
-  OAUTH_JWT_PRIVATE_KEY_PATH=./jwt-private.pem \
-  OAUTH_JWT_PUBLIC_KEY_PATH=./jwt-public.pem \
-  SESSION_SECRET="$(openssl rand -hex 32)" \
-  SESSION_SECURE=false SESSION_NAME=auth.sid \
-  USER_SESSION_STORES_ADAPTER=redis \
-  CLIENT_USER_AUTHENTICATE_URL=http://localhost:8080/authenticate \
-  CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=http://localhost:8080/authenticate-by-token
+  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
@@ -256,63 +282,179 @@ 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 three layers, highest precedence first:
+`src/app.mts` loads configuration in layers, highest precedence first:
 
 1. **`config/{ENV}.conf`** — overlay for the current environment, where
    `ENV = CONFIG_ENV || NODE_ENV || "development"`.
 2. **`config/application.conf`** — this deployment's settings.
-3. **`reference.conf` of `@o3co/auth-provider-core`** — the library defaults,
-   resolved from the installed package
-   (`import.meta.resolve("@o3co/auth-provider-core/reference.conf")`, in
-   [`src/configPath.mts`](src/configPath.mts)). A key neither file above sets
-   takes its value from here.
+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), and the MFA
+   routes' budget in both rate limiters' sections
+   (`core-rate-limiter-memory.limits.mfa`, `redis-rate-limiter.limits.mfa`;
+   see [Multi-replica deployments](#multi-replica-deployments)). 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 what `buildModules` chooses them by — never a federation
+entry — from the two files above over the template's `config/reference.conf`
+alone (`readSwitches`). It reads `adapters` — which adapter fills each slot,
+the composition root's own section — 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. It reads whether federation grants are installed from
+`federation-grants.enabled` (`FEDERATION_GRANTS_ENABLED`, which
+`application.conf` binds for this), with core's `coerceBooleanFromEnv`: a
+value that does not read as `false` installs the federation-grants modules,
+so that boot refuses a bad value at `federation-grants.enabled` rather than
+the feature reading as off, and a setting at the section's old path,
+`federationGrants`, installs them too, for boot to refuse naming the new
+path. Boot is not handed `adapters` or `mfaMode`. Phase one reads no other
+key, and sees nothing a package's `reference.conf` alone sets — none is
+layered yet. A module you add to `buildModules` reads its own section at
+boot (`deps.section`), never when it is built. 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.
+What the template refuses of the configuration before boot — `adapters`,
+`mfaMode` and `logging` in phase one, and what it builds for boot below
+(`resolveForBoot`) — is a `BootError` under the reason boot raises for the
+same case (`config-path-relocated`, `environment-variable-renamed`,
+`config-validation-failed`, `module-section-path-invalid`;
+[`src/bootRefusal.mts`](src/bootRefusal.mts)), so an alert on a boot error's
+reason sees it too. Not every failure to start carries a reason: a
+`CONFIG_ENV` naming a file outside `config/` is a plain `Error`, a missing
+`{ENV}.conf` or a file HOCON cannot parse is the HOCON library's error, and
+a failure after boot, such as a port the listener cannot bind, is its own. Then it hands `createApp` the configuration as resolved over every
+loaded module's `reference.conf` (`resolveForBoot`), unparsed, with
+`core.sessionRequirements` as the MFA switch expects it written in — the
+configuration's list with `mfa` added when the switch installs MFA; a value
+that is not a list of names is handed on as written, for boot to refuse — 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`. Beside it, the template hands boot the
+configuration's defaults (`configDefaultsFor`): the same `reference.conf`
+files with neither of the two files above and no environment. Boot names a
+top-level section no loaded module owns by them, once, at warn, and keeps it:
+a section a loaded package's `reference.conf` sets for a module the
+composition does not load (`redis-clients` with no store on Redis, say) is
+silent while it is as that file sets it, and `config_sections_not_loaded`
+once your files or a variable change it — the setting reaches nothing; a
+section no loaded package sets is `config_sections_ignored`, which is where a
+misspelt section name shows. A renamed variable a loaded package's
+`reference.conf` captures and no loaded module declares is named
+`environment_variables_not_applied`. The [operator
+runbook](../../docs/operator-runbook.md) has a row for each.
 
 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_ATTEMPT_COUNTER` | `memory` | `adapters.attemptCounter`: the counter behind the login's attempt limit (and device verification's, when the device grant is added), `memory` (none: per process) 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. 1 to 256 characters with no control character; anything else fails boot, including a variable exported but empty (which used to sign under the kid `""`; tokens issued that way are refused once it is corrected, so their users sign in again) |
-| `OAUTH_JWT_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
-| `OAUTH_JWT_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
-| `OAUTH_JWT_PUBLIC_KEY` | — | PEM-encoded public key |
-| `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
@@ -324,11 +466,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.
@@ -339,43 +481,67 @@ 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; 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.
 
+The default's old name, `OAUTH_ACCESS_TOKEN_EXPIRES_IN` (config key
+`oauth.accessToken.expiresIn`), refuses boot set alone or beside
+`OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` at a different value; beside it at the
+same value, it boots. The old key refuses boot at any value. Move the value to
+the new name rather than deleting it: without it, the default is `3600`.
+
 ### Grant Types
 
 | 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. Both modules are
+always loaded and read their switches at boot, from the configuration boot
+parses; the template reads none of them before boot. `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`
 
@@ -383,7 +549,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:
@@ -394,19 +560,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:
 
@@ -416,7 +584,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
@@ -424,12 +592,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
@@ -455,17 +632,63 @@ 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.
+
+Every entry names its `type`, and boot hands each enabled entry to the module
+that handles that type, under the entry's name. The template always loads the
+two types it bundles — `google` (`@o3co/auth-provider-federation-google`) and
+`oidc` (`@o3co/auth-provider-federation-oidc`) — whatever the map says, and
+reads no entry itself: a key an entry carries is read, and a malformed one
+refused at its path (`core.federations.<name>.<key>`), by core and by the
+type's schema. An entry with no `type`, enabled or not, is refused at
+`core.federations.<name>.type` (`config-validation-failed`); an enabled entry
+of a type no loaded module handles refuses the boot
+(`federation-type-unhandled`), naming the entry.
+GitHub and Apple are not bundled: a deployment that wants one adds its
+package and its module to `buildModules` — GitHub's type module,
+`githubFederationTypeModule()`, with entries of `type = "github"`; Apple's
+per its [README](../../packages/federation-apple/README.md).
+
+`core.federations.google` ships with `type = "google"`. A second Google
+client is a second entry of that type, under its own name and with its own
+callback:
+
+```hocon
+core.federations {
+  google-work {
+    enabled = true
+    type = "google"
+    clientId = ${GOOGLE_WORK_CLIENT_ID}
+    clientSecret = ${GOOGLE_WORK_CLIENT_SECRET}
+    callbackURL = "https://auth.example.com/session/oauth/federation/google-work/callback"
+  }
+}
+```
+
+The keys a `google` entry takes beside the variables below — `redirectAllowlist`,
+`sessionDomain`, `authCallbackUrl`, `clientUrl`,
+`requireAuthorizationResponseIss`, `endSessionEndpoint` — are listed in full
+in [the package's README](../../packages/federation-google/README.md);
+`config/application.conf` shows every one of them but `endSessionEndpoint`.
+A key the type does not name refuses the entry.
+
 | 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 |
-| `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) |
+| `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
@@ -473,16 +696,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"
@@ -495,9 +718,8 @@ federations {
 }
 ```
 
-The section's `type` names the implementation. `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.
+The entry's `type` names the implementation, never its name: an entry named
+`google` with `type = "oidc"` is a generic OIDC federation named `google`.
 
 Every field the package accepts — `scopes`, `discovery` / `endpoints`,
 `privateKey`, `userInfo`, `idTokenSignedResponseAlg`, `clockToleranceSeconds` —
@@ -507,21 +729,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_BEARER_TOKEN` | — | Optional. The credential this server presents to the Store: every Store request carries `Authorization: Bearer <token>`. A bare token (no `Bearer ` prefix) of at least 32 bytes — `openssl rand -hex 32`. Unset, no `Authorization` header is sent (see below) |
-| `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
-| `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
+| `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
@@ -539,13 +767,13 @@ follows a `3xx`, so a URL that redirects fails every call — see
 **Who may call the Store.** What the token-based login and account linking
 send is an identifier, not a secret, so a Store that answers any caller
 resolves a known identity to its user — or links one to any account — for
-anyone who can reach it. Set `CLIENT_USER_BEARER_TOKEN` and have the Store
+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 `CLIENT_USER_TYPE=http` — this
+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_SECRET`), malformed, or exported but empty; it appears
+(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,
@@ -565,29 +793,38 @@ 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`); read, with a `config_key_deprecated` warning at boot, only when `oauth.code.adapter` is unset — the shipped config sets it |
-| `CLIENT_CODE_ENDPOINT_URI` | — | Legacy; bound to `repositories.code.redis.endpointUri` but not read — codes use the shared `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` connection |
-| `CLIENT_CODE_PASSWORD` | — | Redis password for code storage |
-| `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | Default authorization code lifetime in seconds |
+| `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
@@ -596,12 +833,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
 
@@ -617,29 +929,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
@@ -659,15 +977,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:
 
@@ -718,9 +1036,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
@@ -743,11 +1073,11 @@ 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_SESSION_STORES_KEY_PREFIX` | `ss:` | Outer prefix for user sessions, the subject session index, the subject-revocation boundaries and the session lifecycle records. |
+| `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:`.
@@ -756,24 +1086,26 @@ 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) |
 
 There is no deployment-wide client or callback URL: federation callback URLs
-are configured per federation (`FEDERATIONS_GOOGLE_CALLBACK_URL`,
-`FEDERATIONS_OIDC_CALLBACK_URL`).
+are configured per federation (`CORE_FEDERATIONS_GOOGLE_CALLBACK_URL`,
+`CORE_FEDERATIONS_OIDC_CALLBACK_URL`).
 
 ## Module Composition Order
 
 [`src/buildModules.mts`](src/buildModules.mts) is the single source of truth for which modules are composed and in what order — read it rather than a copy of it. The boot planner resolves `requires` / `provides` topologically, but it mounts routes and middleware in list order unless a module declares `before` / `after` — so position matters for anything that mounts. These are the rules to keep when you edit the list:
 
-1. **`sessionStoreModuleFor(config)` stays first.** It mounts the `express-session` middleware and declares no `before` / `after`, so its position in the list is what puts it ahead of every route that reads `req.session`. It is built from `config` so that `session.storage.type = "memory"` declares itself replica-unsafe.
-2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthModule` and any module of your own may all mount routes under `/oauth`. `oauthModule`'s router parses the bodies of its own routes only, so each module's requests reach its own parsers whatever the list order — provided every module under `/oauth` parses its own body and scopes its parsers to exactly its own paths, as the shipped ones do — a route (`router.all(path, parser)` or the route's own handler list), not `router.use(path, parser)`, which matches every path beneath `path` as well. The federation grants browser half orders itself after the session middleware with its own `after`.
-3. **One module per store slot.** Each adapter switch — `federationTokenStore.type`, `userSessionStores.adapter`, `rateLimiter.adapter`, `oauth.code.adapter`, `accessTokenDenylist.adapter`, `replaySeenSet.adapter`, `consentStore.adapter`, and the two federation-grant store switches — picks one of a memory / Redis pair. Both provide the same slot, so wiring both is a boot-time slot collision. `consentStore.adapter = "none"` wires neither, and the federation-grant stores are wired only while the feature is enabled.
-4. **The shared Redis connection comes with the first Redis-backed module.** `standaloneRedisClientsModule` opens the one ioredis connection every Redis adapter here uses, and is added whenever a composed module needs one. The refresh-token family store is on Redis in the shipped composition, so a deployment always has it; the in-memory family store is a test override (`overrides.refreshTokenFamilyModules`).
-5. **A federation adapter comes with its config bridge.** `googleFederationModule` with `googleFederationConfigModule` — only for an enabled `federations.google` section whose `type` is `google`, so a `type = "oidc"` section named `google` is not composed twice — and one `oidcFederationModule(name)` per enabled `type = "oidc"` section, with the one `oidcFederationConfigModule` they share. A bridge's provider throws when its section is absent, so the pair is included at composition time rather than gated inside it.
+1. **`sessionStoreModule` 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 declares its replica safety from its own section, so `session-store.storage.type = "memory"` is replica-unsafe and refused under `core.deployment.mode = "multi"`.
+2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthEndpointsModule` and any module of your own may all mount routes under `/oauth`. `oauthEndpointsModule`'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. **The federation types are always composed.** `googleFederationTypeModule()` and `oidcFederationTypeModule()` are listed whatever `core.federations` says: each contributes its type, and boot builds one federation per enabled entry of it, under the entry's name, so a federation is added or removed in configuration alone. Nothing in the list reads an entry. A module that contributes a federation under an entry's name directly beside an entry dispatched by its type is a boot-time `duplicate-contribute`: add a federation of another kind as a type module, and give its entries that type.
+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, 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).
+`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. The template composes core's `sessionLifecycleModule`: a login opens its session's record, a code exchange joins it, and both `POST /session/logout` and `POST /oauth/logout` close the session through the lifecycle, which revokes the session's refresh-token families and tells its relying parties. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
 
 ## Built-in Routes
 
@@ -809,11 +1141,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
@@ -822,19 +1156,32 @@ 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 that a plain-HTTP compose run (`make dev`) does
+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.
 
@@ -855,6 +1202,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
@@ -931,21 +1319,23 @@ unready one.
 
 ## Adding Custom Modules
 
-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:
+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: `oauthEndpointsModule`'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),
+ 		sessionStoreModule,
  		…
- 		...(federationGrantsEnabled ? [subjectRevocationServiceModule] : []),
+ 		...(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()`.
+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
 
@@ -955,9 +1345,22 @@ Keep the other rules there too: the session store module stays first, and a modu
 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) as `shutdown_cleanup_failed` (or `shutdown_cleanup_timed_out`) and reflected in the exit code; every stage is its own event — `shutdown_draining`, `shutdown_drain_deadline_exceeded`, `shutdown_server_close_failed`, `shutdown_complete`. A dispose that throws still exits; it never wedges the process. The line carries core's [`loggableError`](../../packages/core/README.md#logger) projection of the failure, never the error itself: `dispose()` rejects with an AggregateError of every cleanup's own error, and the line names each of them with its code (`aggregateErrors`, the first five) and nothing of what it holds — a store write that failed, with what it was writing, can be one of them.
+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.
 
@@ -984,8 +1387,9 @@ Keep the other rules there too: the session store module stays first, and a modu
 ### 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.
@@ -993,7 +1397,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.
 
@@ -1008,7 +1412,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
@@ -1021,40 +1425,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