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

package/templates/standalone/README.md

@@ -1,6 +1,6 @@
 # @o3co/auth-provider-standalone
 
-Last updated: 2026-10-03
+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`.
 
@@ -26,7 +26,7 @@ the Google and generic OpenID Connect federation adapters, `-federation-grants`,
   slot), the signing key store, the client and user repositories, the audit
   sink, the one shared
   Redis connection, the in-memory user-session stores, code repository and
-  federation token store, and the federation config bridges —
+  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
@@ -104,7 +104,7 @@ 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
 
@@ -112,6 +112,8 @@ The [operator runbook](../../docs/operator-runbook.md) covers the operational si
 
 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.
 
+**That Redis must run `maxmemory-policy noeviction`** (Redis's default). The Redis stores whose keys must stay until they expire — the attempt counter, the user-session stores' lifecycle store, the federation token store and the MFA stores — read the policy at boot (`INFO memory`, then `CONFIG GET maxmemory-policy`), and refuse to boot on any other policy or on one the server will not report. If the connection's user may not run `INFO` or `CONFIG` (an ACL-restricted user, or a managed service that renames them) and you know the server runs `noeviction`, set `REDIS_CLIENTS_ASSUME_NO_EVICTION=true` (`redis-clients.assumeNoEviction`, default `false`). It is read only while the policy cannot be read: a policy the server reports always takes precedence, so it never lets an `allkeys-*` or `volatile-*` server through.
+
 **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.
 
 It takes four shapes, all of them Express's own:
@@ -127,7 +129,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 `adapters.rateLimiter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. The login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `session.rateLimit.login`; the session module contributes them as the `login` budget both adapters read, so there is nothing to restate.
+**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 also refuses on a policy the server will not report, unless `REDIS_CLIENTS_ASSUME_NO_EVICTION=true` (above). 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
@@ -173,9 +179,9 @@ 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 `CORE_DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, a single-use client assertion or WebAuthn challenge replayable once per replica. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`ADAPTERS_USER_SESSION_STORES=memory`), the authorization-code repository (`ADAPTERS_CODE_REPOSITORY=memory`) and the federation token store (`ADAPTERS_FEDERATION_TOKEN_STORE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORE_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `ADAPTERS_RATE_LIMITER=memory`). With the mode unset nothing is refused: every one of them is listed in a single `replica_unsafe_adapters` warning at boot. (The login and WebAuthn-options routes carry per-process fallback limiters that warn on their own, but only in a composition that wires no `rateLimiter` at all, which this template never does; see the operator runbook.) With `CORE_DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica. This template does not install DPoP; a composition that adds it records every accepted proof in the same replay seen-set as `private_key_jwt` (`ADAPTERS_REPLAY_SEEN_SET`), so it gets the same answer — `memory` is refused under `CORE_DEPLOYMENT_MODE=multi` and listed in the unset-mode warning, and the shipped `redis` shares DPoP's records across replicas — see the dpop package's [operator requirements](../../packages/dpop/README.md#operator-requirements).
+**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.
+The variable sets `core.deployment.mode`. `DEPLOYMENT_MODE`, its old name, refuses boot while it is set, alone or beside `CORE_DEPLOYMENT_MODE` at any value: unset it.
 
 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.
 
@@ -296,7 +302,10 @@ Configuration is loaded from `config/application.conf` (HOCON format), over the
    `http.cors`), `key-store`, the shared Redis connection's `redis-clients`,
    `repositories`, the in-process code repository's
    `standalone-in-memory-code-repository` and `audit-sink` — and of the
-   composition root's own `adapters` and `mfaMode` (below). Set a deployment's own value in
+   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`,
@@ -311,35 +320,61 @@ It reads the two files above once, under one snapshot of the environment
 [`src/configPath.mts`](src/configPath.mts)) — so a file replaced, or a
 variable changed, while the process starts cannot make boot parse something
 other than what the modules were chosen by. First, before it knows its
-modules, it reads the switches `buildModules` chooses them by — the
-federations, the features — and the `sessionRequirements` it derives the
-session requirements it expects from, from the two files above over core's
-`reference.conf` alone (`readSwitches`, with core's transitional reader),
-parsing those paths (`SWITCHES`) and nothing else. It reads `adapters` — which
-adapter fills each slot, the composition root's own section — from the two
-files above over the template's `config/reference.conf`, with the template's
-own schema (`readAdapters`): a selection still written at the path it moved
-from, or a variable renamed with it, is refused there, before any module is
-chosen, naming the new path and variable. It reads the MFA switch `mfaMode`
+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. Boot is not handed `adapters` or `mfaMode`. It sees nothing
-a package's `reference.conf` alone sets — none is layered yet — and a module
-you add to `buildModules` that reads its configuration when it is built adds
-the paths it reads to `SWITCHES`. The log level is read before boot too, as
+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. Then it hands `createApp` the configuration as resolved over every
-loaded module's `reference.conf` (`resolveForBoot`), unparsed, with the session
-requirements phase one derived written in, and the `mfa` section as the MFA
-switch decides it (see [Multi-factor authentication](#multi-factor-authentication)):
+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`. A top-level section no
-loaded module owns is kept and logged once at boot as
-`config_sections_ignored`: that is where a misspelt section name shows.
+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`, `production.conf` and `mailpit.conf` (the
@@ -359,6 +394,7 @@ 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` |
@@ -376,9 +412,8 @@ fails before boot, naming it.
 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.
+…) set, alone or beside the new one at any value, fails before boot, naming
+the new path and variable: unset the old variable.
 
 ### HTTP
 
@@ -447,7 +482,6 @@ 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`). |
 
 Each is read only as decimal digits. Exporting one as an empty string is a
@@ -457,6 +491,11 @@ boot failure, not a fallback (HOCON resolves `FOO=` to `""`), and so is a hex
 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 while it is set, alone or beside
+`OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` at any value. 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 |
@@ -468,11 +507,11 @@ other grant ignores it and mints the default.
 | `OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED` | `false` | Enable the jwt-bearer grant type (RFC 7523) |
 
 Each switch is its module's key — `oauth-session.enabled`, and
-`oauth-authorization.grants.<grant>.enabled` for the others — which the
-template reads before boot, from its own files and the environment, to choose
-the modules. `OAUTH_GRANTS_<GRANT>_ENABLED`, the old names, refuse boot set
-alone or beside the new name at a different value; beside it at the same value,
-they boot.
+`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 while they are set, alone or beside the new name at
+any value.
 
 ### Session
 
@@ -492,8 +531,8 @@ they boot.
 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.
+variables, refuse boot while they are set, alone or beside the new name at any
+value.
 
 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
@@ -598,8 +637,46 @@ 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.
+`FEDERATIONS_OIDC_*` variable set, alone or beside its new name at any 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 |
 |---|---|---|
@@ -641,9 +718,8 @@ core.federations {
 }
 ```
 
-The entry's `type` names the implementation. `core.federations.google` without a
-`type` is the built-in Google federation; with `type = "oidc"` it is a generic
-OIDC instance named `google`, and the built-in module is not composed.
+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` —
@@ -730,8 +806,8 @@ its own.
 
 `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.
+renamed one set, alone or beside its new name at any value, and a removed one
+set at all, fails boot naming what to set instead.
 
 ### Federation Token Store
 
@@ -798,7 +874,7 @@ 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_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 accepted only where `CONFIG_ENV` and `NODE_ENV`, each where set, say `development` or `test`, and is refused 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` |
@@ -997,7 +1073,7 @@ 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. |
+| `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. |
@@ -1021,15 +1097,15 @@ are configured per federation (`CORE_FEDERATIONS_GOOGLE_CALLBACK_URL`,
 
 [`src/buildModules.mts`](src/buildModules.mts) is the single source of truth for which modules are composed and in what order — read it rather than a copy of it. The boot planner resolves `requires` / `provides` topologically, but it mounts routes and middleware in list order unless a module declares `before` / `after` — so position matters for anything that mounts. These are the rules to keep when you edit the list:
 
-1. **`sessionStoreModuleFor(config)` stays first.** It mounts the `express-session` middleware and declares no `before` / `after`, so its position in the list is what puts it ahead of every route that reads `req.session`. It is built from `config` so that `session-store.storage.type = "memory"` declares itself replica-unsafe.
-2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthModule` and any module of your own may all mount routes under `/oauth`. `oauthModule`'s router parses the bodies of its own routes only, so each module's requests reach its own parsers whatever the list order — provided every module under `/oauth` parses its own body and scopes its parsers to exactly its own paths, as the shipped ones do — a route (`router.all(path, parser)` or the route's own handler list), not `router.use(path, parser)`, which matches every path beneath `path` as well. The federation grants browser half orders itself after the session middleware with its own `after`.
+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. **A federation adapter comes with its config bridge.** `googleFederationModule` with `googleFederationConfigModule` — only for an enabled `core.federations.google` entry whose `type` is `google`, so a `type = "oidc"` section named `google` is not composed twice — and one `oidcFederationModule(name)` per enabled `type = "oidc"` section, with the one `oidcFederationConfigModule` they share. A bridge's provider throws when its section is absent, so the pair is included at composition time rather than gated inside it.
-7. **The mail sender follows the environment.** `@o3co/auth-provider-standard`'s development sender, which logs each code, where the configuration was selected as `development`; its module installs only where that name, and `CONFIG_ENV` and `NODE_ENV` wherever they are set, each read `development` or `test`, and refuses the boot otherwise, or where `core.deployment.mode` is `multi`. Under any other name, the SMTP sender's module, whose section is `standard-smtp-mail-sender` ([the package's README](../../packages/standard/README.md)); its sender is built only where something reads the `mailSender` slot, and there the boot needs `STANDARD_SMTP_MAIL_SENDER_HOST` and `STANDARD_SMTP_MAIL_SENDER_FROM`. While `MFA_MODE` is `off` nothing reads the slot, so the template boots without them; with MFA on, the MFA module and the operator reset read it. A sender of your own replaces this choice: pass its module where [`src/app.mts`](src/app.mts) calls `buildModules`, as `buildModules(switches, { environment: env, logger, mailSenderModules: [mySenderModule] })`. Given, `mailSenderModules` is installed under every environment name and the bundled sender is not, so the two never both provide the slot; an empty list installs no sender, and a module that needs one (the MFA email factor, or the MFA module with `requireEmailProof = "always"`) then refuses the boot.
+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
 
@@ -1138,6 +1214,10 @@ development sender, which only logs each code:
 docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 ```
 
+Before the first run, write a key of your own into `.env` as
+`MFA_ENCRYPTION_KEY` (`openssl rand -base64 32`): this run does not use the
+development sample key, and without a key the boot is refused.
+
 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
@@ -1148,9 +1228,11 @@ 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.
+  rule 7). [`config/mailpit.conf`](config/mailpit.conf) does not include
+  `development.conf`, whose one setting is the MFA sample key: the MFA
+  package accepts that key only where every environment name set says
+  `development` or `test`. The key ring's first key is `MFA_ENCRYPTION_KEY`,
+  as the MFA package's `reference.conf` binds it.
 - 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`,
@@ -1243,14 +1325,14 @@ 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 || mfaInstalled ? [subjectRevocationServiceModule] : []),
 +		myCustomModule,

package/templates/standalone/config/application.conf

@@ -28,12 +28,11 @@
 # `oauth-authorization.grants.clientCredentials.enabled = true` in their own
 # layer.
 #
-# The template reads these switches before it chooses its modules, from its
-# own files, so this file writes every switch and binds its variable: one set
-# only in the package's reference.conf would read as unset there, and a
-# variable bound only there would install no grant. The env-override line is
-# repeated after each value because a layer's own value wins over a variable
-# bound below it.
+# The modules read these switches at boot, from the configuration boot parses;
+# the template reads none of them before. This file writes the template's
+# choices and binds each variable again: the env-override line is repeated
+# after each value because a layer's own value wins over a variable bound
+# below it.
 #
 # PKCE is mandatory for every authorization-code client and `S256` is the only
 # method the provider accepts -- fixed policy (OAuth 2.1 §4.1.1 / RFC 9700
@@ -94,8 +93,9 @@ oauth {
   # /authorize refuses any client not marked `firstParty: true` in
   # clients.yaml — the template's example clients are marked. There is no
   # opt-out: the one-time `allowUnmarkedClients` migration flag is removed,
-  # and a config or environment still setting it fails at boot with
-  # migration instructions (via the tombstone in core's reference.conf).
+  # and a config or environment still setting it fails at boot: the oauth
+  # module refuses the key as removed, and an exported
+  # OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS as the variable of a removed key.
   # POST /oauth/revoke revokes access tokens by writing their `jti` to the
   # denylist wired below, and boot FAILS if that denylist is missing — an
   # RFC 7009 endpoint must answer 200, so an unwired denylist would tell every
@@ -154,30 +154,20 @@ core.sessionRequirements.expected = []
 # the recorded decision not to make that check) — each refused at boot when
 # missing. Connections and the Redis grant store's key ring have no
 # environment form; write them in a deployment-owned HOCON layer (README:
-# Federation Grants). The template reads `federation-grants.enabled` before it
-# chooses its modules, from its own files, which is why this file binds
-# FEDERATION_GRANTS_ENABLED too.
-federation-grants {
-  enabled = false
-  enabled = ${?FEDERATION_GRANTS_ENABLED}
-  identityLookup = "required"
-  identityLookup = ${?FEDERATION_GRANTS_IDENTITY_LOOKUP}
-  consent {
-    url = ${?FEDERATION_GRANTS_CONSENT_URL}
-  }
-}
-
-# The Redis grant store seals every credential; "required" needs its key ring,
-# `redis-federation-grant-store.encryptionKeys`.
-redis-federation-grant-store {
-  encryptionMode = "required"
-  encryptionMode = ${?REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE}
-}
+# Federation Grants). The section's defaults and its other variables
+# (FEDERATION_GRANTS_IDENTITY_LOOKUP, FEDERATION_GRANTS_CONSENT_URL) are the
+# federation-grants package's reference.conf, and the Redis grant store's
+# (REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE, "required" by default) the
+# Redis package's: each is layered only where a module of its package is
+# installed. The
+# template reads `federation-grants.enabled` before it chooses its modules,
+# from its own files, which is why this file binds FEDERATION_GRANTS_ENABLED;
+# unset, it writes nothing, and the feature is off.
+federation-grants.enabled = ${?FEDERATION_GRANTS_ENABLED}
 
 # The session store's section: the session cookie and the store
-# express-session keeps sessions in. The template reads `storage` before it
-# chooses its modules (a memory store declares itself replica-unsafe), from
-# its own files, which is why this file binds SESSION_STORE_STORAGE_TYPE too.
+# express-session keeps sessions in. A memory store declares itself
+# replica-unsafe from this section.
 session-store {
   secret = ${?SESSION_STORE_SECRET}
   # A `__Host-` name requires Secure, Path=/ and no Domain attribute. If
@@ -218,10 +208,11 @@ session {
   # ignored. The federation flow has a separate list per provider (see
   # `core.federations` below).
   redirectAllowlist = []
-  # Rate limiting for POST /session/login (brute-force protection), in
-  # windowMs (milliseconds); the session module contributes it as the `login`
-  # budget, kept in this layer so operators can tweak it. It does NOT govern
-  # OAuth endpoint rate limiting: the `rateLimiter` component
+  # POST /session/login's own attempt limit (brute-force protection), in
+  # windowMs (milliseconds), counted on the attempt counter
+  # (`adapters.attemptCounter`); kept in this layer so operators can tweak
+  # it. No rate limiter changes it. It does NOT govern OAuth endpoint rate
+  # limiting: the `rateLimiter` component
   # (memoryRateLimiterModule or redisRateLimiterModule) reads its own section,
   # `core-rate-limiter-memory` / `redis-rate-limiter` (with `windowSeconds`
   # instead of `windowMs`). Switch via `adapters.rateLimiter = "memory" |
@@ -233,15 +224,28 @@ session {
   }
 }
 
+# The MFA routes' budget, 60 per 300 s, is config/reference.conf's, given to
+# both limiters so that switching `adapters.rateLimiter` keeps it. Change it
+# for the limiter this deployment wires, in its own section:
+#
+#   redis-rate-limiter.limits.mfa { limit = 30, windowSeconds = 300 }
+
 # The federations, in core's own section, 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>.
+# variable named after its path, CORE_FEDERATIONS_<NAME>_<KEY>. Each entry
+# names its `type`, and boot hands an enabled entry to the module that handles
+# that type: the template loads the `google` and `oidc` types, so an entry of
+# either type under any name is a federation of its own. An entry without a
+# `type`, enabled or not, refuses the boot, and so does an enabled entry of a
+# type no loaded module handles.
 core.federations {
   # Template ships a Google federation declaration disabled-by-default.
-  # Operators enable + populate credentials via env vars.
+  # Operators enable + populate credentials via env vars. A second Google
+  # client is another entry with `type = "google"` and its own callbackURL.
   google {
     enabled = false
     enabled = ${?CORE_FEDERATIONS_GOOGLE_ENABLED}
+    type = "google"
     clientId = ${?CORE_FEDERATIONS_GOOGLE_CLIENT_ID}
     clientSecret = ${?CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET}
     callbackURL = "http://localhost:3000/session/oauth/federation/google/callback"
@@ -343,4 +347,5 @@ http {
 redis-clients {
   url = ${?REDIS_CLIENTS_URL}
   password = ${?REDIS_CLIENTS_PASSWORD}
+  assumeNoEviction = ${?REDIS_CLIENTS_ASSUME_NO_EVICTION}
 }

package/templates/standalone/config/clients.yaml.example

@@ -50,6 +50,14 @@
 #   verifier itself as the challenge and so proves nothing against anyone who
 #   can read the authorization request. Set it only for a legacy client that
 #   genuinely cannot compute SHA-256, and treat it as a migration deadline.
+#
+# `allowExchangeOfTokensIssuedToOthers`: read only where the token-exchange
+#   module (@o3co/auth-provider-oauth-token-exchange) is installed, which this
+#   template does not do by default. Token exchange requires the caller to be
+#   an audience of the subject token by default: the token's `azp` is the
+#   client, or its `aud` contains it. `true` lets this one client exchange
+#   tokens issued to other clients (a gateway, an on-behalf-of service). Only
+#   a strict `true` counts.
 
 # A machine client that authenticates with a key pair (#484). Nothing here is
 # secret: the private half stays with the client, which signs an assertion

package/templates/standalone/config/development.conf

@@ -10,8 +10,8 @@
 # The MFA key ring's development key: the MFA package's published sample key
 # (MFA_DEVELOPMENT_SAMPLE_KEY), which everyone holds. It stands in for
 # MFA_ENCRYPTION_KEY here: to use a key of your own in development, write it
-# in place of this one. It is refused where the configuration is selected as
-# production or staging, where NODE_ENV is either, and under
+# in place of this one. It is accepted only where the configuration's name and
+# NODE_ENV, each where set, say development or test, and is refused under
 # `core.deployment.mode = "multi"`; boot warns while it is in use
 # (mfa_development_sample_key_in_use). Read only while MFA_MODE installs MFA.
 mfa.encryptionKeys = [{ key = "bzNjbzptZmE6ZGV2ZWxvcG1lbnQtc2FtcGxlLWtleSE=" }]

package/templates/standalone/config/mailpit.conf

@@ -1,8 +1,13 @@
 # Environment overlay for a development run whose mail goes to Mailpit
 # (docker-compose.mailpit.yml). Loaded when CONFIG_ENV is "mailpit".
 #
-# The development overlay under another name: the template installs the
-# sender that logs each code only where the configuration is selected as
-# "development", and the SMTP sender under any other name. For development
-# only; a deployment names its own relay.
-include "development.conf"
+# The template installs the sender that logs each code only where the
+# configuration is selected as "development", and the SMTP sender under any
+# other name. For development only; a deployment names its own relay.
+#
+# It does not include development.conf, whose one setting is the MFA
+# development sample key: the MFA package accepts that key only where every
+# environment name set says development or test, and this run is selected as
+# "mailpit". The key ring's first key is MFA_ENCRYPTION_KEY, as the MFA
+# package's reference.conf binds it: write a key of your own
+# (openssl rand -base64 32) into .env; without one the boot is refused.