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

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
 
@@ -127,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 `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 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
@@ -173,7 +177,7 @@ raising it globally to accommodate one topology would weaken it for the other.
 Put the throttling that protects the BFF's *own* users in front of the BFF,
 where per-user identity still exists.
 
-**Set `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.
 
@@ -296,7 +300,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 +318,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 +392,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` |
@@ -447,7 +481,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 +490,12 @@ 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 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 |
@@ -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 set alone or beside the new name at a different
+value; beside it at the same value, they boot.
 
 ### Session
 
@@ -601,6 +640,44 @@ 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 |
 |---|---|---|
 | `CORE_FEDERATIONS_GOOGLE_ENABLED` | `false` | Enable Google OAuth federation |
@@ -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` —
@@ -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
 
@@ -1243,14 +1319,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"

package/templates/standalone/config/reference.conf

@@ -1,6 +1,7 @@
 # Defaults of the standalone template's own modules (src/modules.mts), each in
 # the section named after its module, and of its own `adapters` and
-# `mfaMode`, each key with its variable, named after its path. Layered
+# `mfaMode`, each key with its variable, named after its path, and the MFA
+# routes' budget in each rate limiter's section (below `mfaMode`). Layered
 # beneath application.conf and {env}.conf: set a deployment's own values
 # there, not here. A value either file sets wins over
 # the variable bound here, except for HTTP_PORT, HTTP_TRUST_PROXY,
@@ -217,9 +218,16 @@ audit-sink {}
 # replica, and `core.deployment.mode = "multi"` refuses each memory store by
 # name. Each Redis store shares the one socket `redis-clients` opens.
 adapters {
-  # The OAuth endpoints' and /session/login's rate-limit counters.
+  # The rate-limit counters: the OAuth endpoints' and the MFA routes'.
   rateLimiter = "memory"
   rateLimiter = ${?ADAPTERS_RATE_LIMITER}
+  # The counter behind /session/login's own attempt limit
+  # (session.rateLimit.login), and device verification's
+  # (device-grant.rateLimit) when the device grant is added. `memory` wires
+  # none: each counts per process, which `core.deployment.mode = "multi"`
+  # refuses. `redis` needs a server whose maxmemory-policy is `noeviction`.
+  attemptCounter = "memory"
+  attemptCounter = ${?ADAPTERS_ATTEMPT_COUNTER}
   # The four user-session stores and the subject-level revocation pair. They
   # must be on Redis whenever express-session's store is, or a restart leaves
   # every browser a session whose user session is gone.
@@ -294,6 +302,17 @@ adapters {
 mfaMode = "required"
 mfaMode = ${?MFA_MODE}
 
+# The MFA routes' budget: the one setting this file writes in sections of
+# modules other than the template's own. Every /session/mfa POST is limited
+# per client address under the prefix `mfa` (`mfa:ip:<ip>`) by the wired
+# limiter alone: the MFA package ships no budget of its own. Both limiters
+# carry it, so switching `adapters.rateLimiter` keeps it; written here, beside
+# each package's own defaults, the limiter not wired has it as a default
+# rather than as a setting nothing reads. Without an entry the limiter's
+# `defaultLimit` (60 per 60 s) applies. The MFA lock is separate and unchanged.
+core-rate-limiter-memory.limits.mfa { limit = 60, windowSeconds = 300 }
+redis-rate-limiter.limits.mfa { limit = 60, windowSeconds = 300 }
+
 # The old paths of these sections refuse boot naming the new ones: `cors`,
 # `oauth.jwt.signingKey`, `refreshTokenFamilyStore.redis`,
 # `repositories.code` and `audit.sink`; the old adapter switches

package/templates/standalone/docker-compose.production.yml

@@ -142,8 +142,8 @@ services:
       SESSION_STORE_STORAGE_TYPE: redis
       SESSION_STORE_STORAGE_REDIS_URL: redis://redis:6379
       # The UserSession stores: the provider's own record of who is signed in,
-      # which RPs a session has touched, and the family / federation indexes
-      # hanging off it. They MUST be on Redis whenever the express-session
+      # the subject index and revocation boundaries beside it, and the session
+      # lifecycle records. They MUST be on Redis whenever the express-session
       # store above is, and this line is the fix for what happens when they
       # are not.
       #
@@ -161,6 +161,9 @@ services:
       # The memory rate limiter is per-process and evadable under bucket
       # exhaustion (see README) — production points it at Redis.
       ADAPTERS_RATE_LIMITER: redis
+      # The counter behind the login's own attempt limit: on Redis, a restart
+      # does not reset it. Redis must keep `maxmemory-policy noeviction`.
+      ADAPTERS_ATTEMPT_COUNTER: redis
       # The federation token store is deliberately left at its `memory`
       # default, and that is coherent here rather than an oversight: this
       # template ships every federation disabled, so nothing writes to the

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.17.0-rc.1",
+	"version": "0.17.0-rc.2",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {