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

package/templates/standalone/README.md

@@ -1,1537 +0,0 @@
-# @o3co/auth-provider-standalone
-
-Last updated: 2026-10-07
-
-Deployable server template for auth.provider. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-provider`.
-
-## Responsibility
-
-**Role.** The composition root and the starting point for a deployment. It is
-not a library: nothing imports it. `@o3co/create-auth-provider` copies it into
-a new project, and from then on the operator owns and edits the copy. It sits
-on top of the packages: it composes `@o3co/auth-provider-oauth`, `-session`,
-the Google and generic OpenID Connect federation adapters, `-federation-grants`,
-`-mfa`, `-redis`, `-foundation` and `-standard`'s mail senders over
-`@o3co/auth-provider-core`.
-
-**Owns** the choices that are specific to one deployment:
-
-- which modules are composed, in what order, and which adapter fills each
-  store slot — [`src/buildModules.mts`](src/buildModules.mts) (see
-  [Module Composition Order](#module-composition-order)), the choice read from
-  its own keys, the `adapters` section ([`src/adapters.mts`](src/adapters.mts))
-  and the MFA switch `mfaMode` ([`src/mfaSwitch.mts`](src/mfaSwitch.mts));
-- the modules only this scaffold has — `logging` and `http` (the host
-  process's own settings, with its CORS list, and core's `httpSettings`
-  slot), the signing key store, the client and user repositories, the audit
-  sink, the one shared
-  Redis connection, the in-memory user-session stores, code repository and
-  federation token store —
-  [`src/modules.mts`](src/modules.mts), with the defaults of the sections they
-  own in [`config/reference.conf`](config/reference.conf). They are the
-  scaffold's rather than a package's because each builds its component from
-  this template's configuration sections; a deployment that wants another
-  source wires its own module of the same shape;
-- where configuration comes from and how its layers stack —
-  [`src/configPath.mts`](src/configPath.mts) and [`config/`](config/);
-- the host process: the Express app, its security headers and startup —
-  [`src/app.mts`](src/app.mts); the health, readiness and metrics routes, the
-  composed router and core's terminal error handler after them, in the order
-  they are mounted — [`src/routes.mts`](src/routes.mts); the listener, which logs `server_listening`
-  (info, `port`) once its socket is bound, fails boot with the bind error
-  when it cannot be, and logs any later server error as `server_error`
-  (error) — [`src/listen.mts`](src/listen.mts). Every error this code logs — an unhandled
-  request error, the shared Redis connection's `error` event, a failed
-  shutdown — is logged as core's
-  [`loggableError`](../../packages/core/README.md#logger) projection, never the
-  error, which can carry what an upstream or Redis said (the connection's
-  error carries the `AUTH` handshake, password included, when the server
-  refuses it);
-- the concrete logger and audit stream (pino) —
-  [`src/logger.mts`](src/logger.mts) — and the metrics
-  ([`src/metrics.mts`](src/metrics.mts));
-- process lifecycle: signal handling with a drain deadline —
-  [`src/shutdown.mts`](src/shutdown.mts);
-- packaging: the `Dockerfile`, the compose files, the `Makefile`;
-- its tests: `src/__tests__/`, which `pnpm run test` and `make test` run against
-  this composition, and `tests/`, a separate black-box API suite with its own
-  `package.json`, run against a server that is already up (`API_BASE_URL`).
-  Among what `src/__tests__/` holds: every module this template can turn on
-  boots together and keeps the contracts that exist only when they meet — one
-  discovery document, each module's body rules in either mount order, a store
-  or repository outage answered 503 and logged once — pinned by
-  `all-modules-composition.test.mts`.
-
-**Does not own** the HTTP API, the grants, the token format, how each store
-behaves, or the config schema — the packages do. Change those upstream, not
-here.
-
-**Why separate.** Everything above is a per-deployment decision, so it is kept
-out of the published libraries and put in a tree the operator is expected to
-modify. It is `"private": true` and never published itself; it reaches users
-only through the scaffolder. A scaffolded copy carries this README too; its
-relative links into `../../docs` and `../../packages` resolve only inside this
-repository.
-
-## Requirements
-
-- **Node.js** `>=22.0.0`
-- **`bcrypt` native binary**: this template depends transitively on `bcrypt@6.x`, which ships **prebuilt N-API binaries** for `darwin-arm64`, `darwin-x64`, `linux-x64` (glibc and musl), `linux-arm64` (glibc and musl), `linux-arm`, `win32-x64`, and `win32-arm64`. On these platforms `pnpm install` succeeds without compiling from source, and no extra toolchain is required (the `darwin-*`, `node:*-alpine`, and `node:*-bookworm` images all match a shipped prebuild). On platforms or libc/arch combinations that have no matching prebuild, `pnpm install` falls back to compiling, which then requires a C++ compiler and Python (the standard Node.js native-addon toolchain): Debian/Ubuntu `apt-get install build-essential python3`, Alpine `apk add make g++ python3`, macOS `xcode-select --install`. The pnpm 10 `onlyBuiltDependencies` allowlist for `bcrypt` lives in `pnpm-workspace.yaml` — pnpm ≥10.29 reads it only from there, in single-package projects too. `create-auth-provider` writes that file into the project it scaffolds (inside this monorepo, the allowlist sits in the workspace root's `pnpm-workspace.yaml`); without it a fresh `pnpm install` silently skips the install hook on those platforms.
-- **Redis 7.2 LTS or later** for any Redis-backed adapter (refresh token family store, code repository, federation token store, session store). The `pExpireGT` flag pair on which several adapters depend was introduced in Redis 7.0+; 7.2 LTS is the tested floor. Tested against AWS ElastiCache for Redis 7.2, Upstash Redis, Redis Cloud 7.2, and self-managed `redis:7.2-alpine`.
-- **ioredis** `^6.0.0` (direct runtime dependency). Every `@o3co/auth-provider-redis` adapter this template wires — refresh-token families, authorization codes, rate-limit counters, the access-token denylist, the replay seen-set, the user-session stores, the federation-token store, the consent stores and the federation-grant stores — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica. The same module provides the client of every other store the Redis package ships — the device-code store and the WebAuthn challenge store — so a deployment that adds the device grant or WebAuthn to `buildModules.mts` with a Redis store finds its client there. The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORE_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
-
-## First-party clients
-
-For a client marked `firstParty: true`, `GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
-
-That is a coherent model for a **first-party** OP — one where every registered client is operated by you — and it is coherent nowhere else. A page you do not control can force a top-level navigation to `/authorize?client_id=X&redirect_uri=...&code_challenge=<theirs>`, a logged-in user's browser mints a code bound to *their* session, it is delivered to X's registered `redirect_uri`, and whoever chose the `code_challenge` redeems it for tokens carrying that user's identity.
-
-So the assumption is enforced rather than assumed. Every other client — one with no `firstParty` field and one carrying `false` alike — goes through the consent step: the user is asked on your consent page before a code is minted. That step needs a consent store, and the template ships none (`ADAPTERS_CONSENT_STORE=none`), so on the defaults such a client is refused at `/authorize` with `unauthorized_client`; see [Consent Store](#consent-store) to serve it. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
-
-```yaml
-# config/clients.yaml
-my-app:
-  tokenEndpointAuthMethod: "client_secret_basic"
-  firstParty: true
-  allowedRedirectUris: ["https://app.example/callback"]
-```
-
-A machine client can authenticate with a key instead of a shared secret (#484):
-`tokenEndpointAuthMethod: "private_key_jwt"` plus `jwks` (inline public keys) or
-`jwksUri`, and it presents a signed assertion at `/oauth/token` — see the
-[oauth package README](../../packages/oauth/README.md#client-authentication-private_key_jwt-rfc-7523-22).
-Nothing secret lives in `clients.yaml` for such a client.
-
-**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident.
-
-**Unmarked registrations.** A registration without the field is not first-party: on the defaults it is refused at `/authorize` until you mark it, with no admit-with-warning window. Mark every client you operate before pointing it at `/authorize`. `oauth.authorize.allowUnmarkedClients` is not a setting: a config or environment that sets it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot rather than being silently ignored: the oauth module refuses the key as removed (`config-path-relocated`), and the variable as one bound to a removed key (`environment-variable-renamed`). Mark your clients, then delete the key and unset the variable.
-
-## Multi-replica deployments
-
-The [operator runbook](../../docs/operator-runbook.md) covers the operational side end to end — boot refusals, probes, dependency failures, alerts, Redis sizing, key rotation. This section is the multi-replica checklist.
-
-When running multiple instances of the standalone server behind a load balancer, point `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:
-
-| Value | Meaning |
-|---|---|
-| `false` (default) | Trust nothing; `req.ip` is the socket peer |
-| `10.0.0.0/8,192.168.0.0/16` | Trust exactly these hops. IP literals, CIDR ranges, or the named ranges `loopback` / `linklocal` / `uniquelocal`. Comma-separate for the env var |
-| `1` | Trust that many hops back from the socket peer |
-| `true` | Trust every hop — the leftmost `X-Forwarded-For` entry, from whoever opened the connection |
-
-**Prefer the address list.** `true` believes a forwarded client address from anyone who can reach this process; a client that routes to it directly, or through one hop more than you accounted for, then chooses its own `req.ip` and with it any rate-limit identity keyed on it. Entries are validated at boot, so a hostname or a typo'd range fails loudly instead of becoming a rule that never matches.
-
-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. `/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
-bucket key as `<endpoint>:ip:<req.ip>`), which is the right identity when the
-client is the browser or a native app talking to this provider directly. It is
-the wrong one in a backend-for-frontend topology, where a server-side app holds
-the session and exchanges codes and refreshes on its users' behalf: every
-`/oauth/token` and `/oauth/introspect` call then arrives from the BFF's single
-address and the whole deployment shares one bucket. At the default 60 requests
-per 60 s that caps you at roughly **60 session-grant exchanges a minute across
-all users** — and it does not surface as a rate limit. The BFF gets a `429` it
-was not written to expect, turns it into a `502` for its own caller, and the
-symptom your users report is "sign-in is broken sometimes", at the traffic
-level where it starts happening and not before.
-
-`HTTP_TRUST_PROXY` does not fix this and is not meant to. It teaches `req.ip`
-to see through a *proxy* — a hop that forwards someone else's request and says
-so in `X-Forwarded-For`. A BFF is not forwarding anyone; it is the client, and
-its address is the honest answer to "who called". There is no per-user identity
-in these requests to key on.
-
-The knob is the per-endpoint budget. Both limiter adapters take
-`limits { <prefix> { limit, windowSeconds } }` in their own sections, keyed by
-the endpoint prefix:
-
-```hocon
-redis-rate-limiter {
-  limits {
-    token     { limit = 600, windowSeconds = 60 }
-    introspect { limit = 600, windowSeconds = 60 }
-  }
-}
-```
-
-(`core-rate-limiter-memory.limits` for the memory adapter, same shape.) Size it from
-your BFF's peak sign-ins and refreshes per minute with headroom, and remember
-that under `adapters.rateLimiter = "redis"` the budget is shared across replicas
-— which is what you want here, and what makes the number mean something.
-
-The defaults are deliberately left alone: 60/60 s per source IP is a sensible
-brute-force bound for a deployment whose clients really are distinct IPs, and
-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 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 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.
-
-**Access-token revocation needs a denylist, and the template ships one.** `POST /oauth/revoke` revokes an access token by writing its `jti` to the `accessTokenDenylist`, which token verification and introspection consult. Boot *fails* if the endpoint is mounted with no denylist behind it: RFC 7009 obliges the endpoint to answer `200`, so an unwired denylist would tell you a token is revoked while it keeps working until it expires. `adapters.accessTokenDenylist` defaults to `"redis"` here (`ADAPTERS_ACCESS_TOKEN_DENYLIST=memory` for single-instance local work) and shares the ioredis socket configured by `REDIS_CLIENTS_URL`, so it costs no extra connection. A deployment that genuinely does not revoke access tokens sets `OAUTH_REVOCATION_ACCESS_TOKEN=unsupported` instead; the endpoint then answers `unsupported_token_type` for `token_type_hint=access_token`. **Refresh-token revocation works in either case and never needed a denylist.**
-
-Other multi-replica considerations covered by the default modules:
-
-- The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORE_STORAGE_TYPE=redis` with `SESSION_STORE_STORAGE_REDIS_URL` (`session-store.storage.redis.url`) pointing at the shared instance.
-- The user-session stores switch on `adapters.userSessionStores = "redis"` (`ADAPTERS_USER_SESSION_STORES`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REDIS_CLIENTS_URL` configures.
-- The authorization-code repository switches on `adapters.codeRepository` (`ADAPTERS_CODE_REPOSITORY`); the template ships `"redis"`, on that same connection, so there is one Redis URL for every adapter. The Redis repository's own settings are its section, `redis-code-repository`; the in-process one's, `standalone-in-memory-code-repository` (see [Code Repository](#code-repository)).
-- The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `adapters.replaySeenSet` (`ADAPTERS_REPLAY_SEEN_SET`); the template ships `"redis"` on the shared connection, and `memory` is refused under `CORE_DEPLOYMENT_MODE=multi` because a captured client assertion would replay once per replica.
-- The consent step for clients that are not first-party (#527) switches on `adapters.consentStore` (`ADAPTERS_CONSENT_STORE`). It is off (`none`) by default; `memory` is refused under `CORE_DEPLOYMENT_MODE=multi`, because a consent granted on one replica would be asked for again on every other and a consent page's parked request would be unknown to the replica that receives the answer. `redis` (#561) keeps both on the shared connection. See [Consent Store](#consent-store).
-- The federation token store defaults to memory. Set `ADAPTERS_FEDERATION_TOKEN_STORE=redis` (`adapters.federationTokenStore = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REDIS_CLIENTS_URL`. See [Federation Token Store](#federation-token-store).
-- Federation grants (#593), when enabled, keep two more stores: the grants themselves (`ADAPTERS_FEDERATION_GRANT_STORE`) and acquisition's records (`ADAPTERS_FEDERATION_GRANT_INTENT_STORE`). Both ship `none`, which an enabled feature refuses at boot naming the store: select `redis` (the shared socket) or `memory` for each; `memory` for either is refused under `CORE_DEPLOYMENT_MODE=multi`, and Redis grants beside memory user-session stores are refused on any replica count, because the grants would outlive the boundary that ends them. See [Federation Grants](#federation-grants).
-
-## Usage
-
-`pnpm run debug` runs `src/app.mts` under `tsx watch` on this machine. It reads
-no `.env` file — its configuration is `config/` plus the environment of the
-shell that starts it — and it does not boot until that environment supplies:
-
-- `OAUTH_JWT_ISSUER` — this server's origin (`http` is accepted for a loopback
-  host);
-- a signing key pair, `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` / `KEY_STORE_LOCAL_PUBLIC_KEY_PATH`
-  (see [OAuth JWT](#oauth-jwt));
-- `SESSION_STORE_SECRET`, at least 32 bytes;
-- `REPOSITORIES_USER_HTTP_AUTHENTICATE_URL` and `REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL` —
-  your user service ("the Store"), `https`, or `http` on a loopback host. Boot
-  checks their form, not that anything answers; logins fail until something
-  does (see [User Repository](#user-repository));
-- a Redis it can reach at `redis://localhost:6379`. The shipped configuration
-  keeps the browser session store there (`SESSION_STORE_STORAGE_REDIS_URL`), and
-  opens one shared connection (`REDIS_CLIENTS_URL`) for the
-  refresh-token families, the authorization codes, the access-token denylist
-  and the replay seen-set — and for the user-session stores, with the setting
-  below.
-
-Plain HTTP also needs `SESSION_STORE_SECURE=false` and a session cookie name without
-the `__Host-` prefix (see [Session](#session)). And set
-`ADAPTERS_USER_SESSION_STORES=redis`: the browser session store is in Redis, the
-user-session stores default to memory, and `tsx watch` restarts the process on
-every save — split, a restart leaves the browser's session pointing at a
-`UserSession` that is gone, and `/authorize` loops (see [Docker](#docker)).
-MFA is on by default, and its two stores default to memory too: set
-`ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`
-for the same reason, or every save empties them while the sessions survive —
-or `MFA_MODE=off` to run without MFA (see
-[Multi-factor authentication](#multi-factor-authentication)).
-
-It also reads the client registry, `config/clients.yaml` (`REPOSITORIES_CLIENT_YAML_PATH`). That
-file is per-deployment: the scaffold creates an empty one, and `.gitignore`
-keeps it out of the project's repository, so a fresh clone has none and boot
-fails naming the path until you create it — from `config/clients.yaml.example`,
-or empty for a registry with no clients.
-
-The key pair below is generated with Node, which every machine running this
-already has. `openssl genpkey -algorithm ed25519` works too, with OpenSSL 1.1.1
-or later — not with the LibreSSL that macOS ships as `/usr/bin/openssl`.
-
-```bash
-pnpm install
-
-# A signing key pair (Ed25519) and a local Redis
-node -e '
-const { generateKeyPairSync } = require("node:crypto");
-const fs = require("node:fs");
-const { privateKey, publicKey } = generateKeyPairSync("ed25519");
-fs.writeFileSync("jwt-private.pem", privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
-fs.writeFileSync("jwt-public.pem", publicKey.export({ type: "spki", format: "pem" }));
-'
-docker run -d --name auth-redis -p 127.0.0.1:6379:6379 redis:7.2-alpine
-
-# What boot requires (replace the user-service URLs with your Store's)
-export OAUTH_JWT_ISSUER=http://localhost:3000 \
-  KEY_STORE_LOCAL_PRIVATE_KEY_PATH=./jwt-private.pem \
-  KEY_STORE_LOCAL_PUBLIC_KEY_PATH=./jwt-public.pem \
-  SESSION_STORE_SECRET="$(openssl rand -hex 32)" \
-  SESSION_STORE_SECURE=false SESSION_STORE_NAME=auth.sid \
-  ADAPTERS_USER_SESSION_STORES=redis \
-  ADAPTERS_MFA_FACTOR_STORE=redis ADAPTERS_MFA_TRANSACTION_STORE=redis \
-  REPOSITORIES_USER_HTTP_AUTHENTICATE_URL=http://localhost:8080/authenticate \
-  REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL=http://localhost:8080/authenticate-by-token
-
-# Start in development mode (hot reload)
-pnpm run debug
-
-# Build, then run the compiled server (CONFIG_ENV or NODE_ENV selects config/<env>.conf)
-pnpm run build
-pnpm run start
-```
-
-`.env` is read only by the compose files (`env_file`). `make dev`
-(`docker compose up --build`) runs the same debug server in a container beside
-a Redis service, with its environment from `.env` — copied from
-`.env.example`, whose Redis URLs name that service. Values there are resolved
-inside the container, which holds no key files: only `src/`, `config/`, the
-package manifests and what installing and building them produced. A key path or
-a `localhost` URL that works on the host does not work there. The deployable
-image and its compose file are under [Docker](#docker).
-
-## Configuration
-
-Configuration is loaded from `config/application.conf` (HOCON format), over the defaults in the packages' `reference.conf` files and the template's own `config/reference.conf`. Each value can be overridden with the corresponding environment variable.
-
-### Environment-specific config overlay
-
-`src/app.mts` loads configuration in layers, highest precedence first:
-
-1. **`config/{ENV}.conf`** — overlay for the current environment, where
-   `ENV = CONFIG_ENV || NODE_ENV || "development"`.
-2. **`config/application.conf`** — this deployment's settings.
-3. **the `reference.conf` of each package the loaded modules come from**, then
-   **`@o3co/auth-provider-core`'s** — the defaults, resolved from the
-   installed packages: each module declares its package's file, and core's
-   `moduleReferences(modules)` lists them, core's last. The template's own
-   modules declare `config/reference.conf`, which holds the defaults of the
-   sections they own — `logging`, `http` (with its CORS list,
-   `http.cors`), `key-store`, the shared Redis connection's `redis-clients`,
-   `repositories`, the in-process code repository's
-   `standalone-in-memory-code-repository` and `audit-sink` — and of the
-   composition root's own `adapters` and `mfaMode` (below), and the MFA
-   routes' budget in both rate limiters' sections
-   (`core-rate-limiter-memory.limits.mfa`, `redis-rate-limiter.limits.mfa`;
-   see [Multi-replica deployments](#multi-replica-deployments)). Set a deployment's own value in
-   the two files above, not there. `config/reference.conf` binds each of these
-   keys' variables beside its default, so a value either file above sets wins
-   over the variable, except for `HTTP_PORT`, `HTTP_TRUST_PROXY`,
-   `HTTP_CORS_ALLOWED_ORIGINS` and `REDIS_CLIENTS_URL` /
-   `REDIS_CLIENTS_PASSWORD`, which `application.conf` binds again in its last
-   lines, so each of those wins over a value that file sets above them. A key
-   neither file above sets takes its value from here.
-
-It reads the two files above once, under one snapshot of the environment
-(`readOwnLayers`), and builds two phases from that one read
-([#728](https://github.com/o3co/auth.provider/issues/728);
-[`src/configPath.mts`](src/configPath.mts)) — so a file replaced, or a
-variable changed, while the process starts cannot make boot parse something
-other than what the modules were chosen by. First, before it knows its
-modules, it reads what `buildModules` chooses them by — never a federation
-entry — from the two files above over the template's `config/reference.conf`
-alone (`readSwitches`). It reads `adapters` — which adapter fills each slot,
-the composition root's own section — with the template's own schema
-(`readAdapters`): a selection still written at the path it moved from, or a
-variable renamed with it, is refused there, before any module is chosen,
-naming the new path and variable. It reads the MFA switch `mfaMode`
-(`MFA_MODE`), the composition root's own key, the same way, with the
-template's own schema (`readMfaSwitch`), and beside them the user
-repository's HTTP settings, unparsed, which the Store-backed MFA factor store
-is built over. It reads whether federation grants are installed from
-`federation-grants.enabled` (`FEDERATION_GRANTS_ENABLED`, which
-`application.conf` binds for this), with core's `coerceBooleanFromEnv`: a
-value that does not read as `false` installs the federation-grants modules,
-so that boot refuses a bad value at `federation-grants.enabled` rather than
-the feature reading as off, and a setting at the section's old path,
-`federationGrants`, installs them too, for boot to refuse naming the new
-path. Boot is not handed `adapters` or `mfaMode`. Phase one reads no other
-key, and sees nothing a package's `reference.conf` alone sets — none is
-layered yet. A module you add to `buildModules` reads its own section at
-boot (`deps.section`), never when it is built. The log level is read before boot too, as
-the `logging` module's section, with that module's schema, over the template's
-`reference.conf` (`readLogging`): the logger exists before boot, since the
-template logs while it reads its configuration and chooses its modules.
-What the template refuses of the configuration before boot — `adapters`,
-`mfaMode` and `logging` in phase one, and what it builds for boot below
-(`resolveForBoot`) — is a `BootError` under the reason boot raises for the
-same case (`config-path-relocated`, `environment-variable-renamed`,
-`config-validation-failed`, `module-section-path-invalid`;
-[`src/bootRefusal.mts`](src/bootRefusal.mts)), so an alert on a boot error's
-reason sees it too. Not every failure to start carries a reason: a
-`CONFIG_ENV` naming a file outside `config/` is a plain `Error`, a missing
-`{ENV}.conf` or a file HOCON cannot parse is the HOCON library's error, and
-a failure after boot, such as a port the listener cannot bind, is its own. Then it hands `createApp` the configuration as resolved over every
-loaded module's `reference.conf` (`resolveForBoot`), unparsed, with
-`core.sessionRequirements` as the MFA switch expects it written in — the
-configuration's list with `mfa` added when the switch installs MFA; a value
-that is not a list of names is handed on as written, for boot to refuse — and
-the `mfa` section as the MFA switch decides it (see [Multi-factor authentication](#multi-factor-authentication)):
-boot parses it once, with every loaded module's schema. What
-the template reads after boot — the trusted hops, the port, the readiness
-deadline — it reads from the `http` module: core's `httpSettings` slot and the
-template's `httpHostSettings`. Beside it, the template hands boot the
-configuration's defaults (`configDefaultsFor`): the same `reference.conf`
-files with neither of the two files above and no environment. Boot names a
-top-level section no loaded module owns by them, once, at warn, and keeps it:
-a section a loaded package's `reference.conf` sets for a module the
-composition does not load (`redis-clients` with no store on Redis, say) is
-silent while it is as that file sets it, and `config_sections_not_loaded`
-once your files or a variable change it — the setting reaches nothing; a
-section no loaded package sets is `config_sections_ignored`, which is where a
-misspelt section name shows. A renamed variable a loaded package's
-`reference.conf` captures and no loaded module declares is named
-`environment_variables_not_applied`. The [operator
-runbook](../../docs/operator-runbook.md) has a row for each.
-
-Values in the overlay take precedence over `application.conf`. The scaffold
-ships with `development.conf`, `production.conf` and `mailpit.conf` (the
-development overlay under the name the
-[Mailpit overlay](#mailpit-for-the-smtp-sender-development-only) selects). To add another
-environment (e.g. `staging`), create `config/staging.conf` and set
-`CONFIG_ENV=staging`. A missing `{ENV}.conf` is a boot-time error — typos
-fail fast rather than silently falling back to defaults.
-
-### Adapters
-
-Which adapter fills each slot is the composition root's own choice, its own
-section `adapters`, read before any module is chosen (above). Each key has its
-variable; a value the template does not know, or a key it does not declare,
-fails before boot, naming it.
-
-| Variable | Default | Description |
-|---|---|---|
-| `ADAPTERS_RATE_LIMITER` | `memory` | `adapters.rateLimiter`: `memory` or `redis`. See [Multi-replica deployments](#multi-replica-deployments) |
-| `ADAPTERS_ATTEMPT_COUNTER` | `memory` | `adapters.attemptCounter`: the counter behind the login's attempt limit (and device verification's, when the device grant is added), `memory` (none: per process) or `redis`. See [Multi-replica deployments](#multi-replica-deployments) |
-| `ADAPTERS_USER_SESSION_STORES` | `memory` | `adapters.userSessionStores`: the user-session stores, `memory` or `redis`. Keep it with `SESSION_STORE_STORAGE_TYPE` (see [Docker](#docker)) |
-| `ADAPTERS_ACCESS_TOKEN_DENYLIST` | `redis` | `adapters.accessTokenDenylist`: `memory` or `redis` |
-| `ADAPTERS_REPLAY_SEEN_SET` | `redis` | `adapters.replaySeenSet`: the replay seen-set behind `private_key_jwt`, `memory` or `redis` |
-| `ADAPTERS_CONSENT_STORE` | `none` | `adapters.consentStore`: `none`, `memory` or `redis`. See [Consent Store](#consent-store) |
-| `ADAPTERS_FEDERATION_TOKEN_STORE` | `memory` | `adapters.federationTokenStore`: `memory` or `redis`. See [Federation Token Store](#federation-token-store) |
-| `ADAPTERS_FEDERATION_GRANT_STORE` | `none` | `adapters.federationGrantStore`: `none`, `memory` or `redis`. See [Federation Grants](#federation-grants) |
-| `ADAPTERS_FEDERATION_GRANT_INTENT_STORE` | `none` | `adapters.federationGrantIntentStore`: `none`, `memory` or `redis`. See [Federation Grants](#federation-grants) |
-| `ADAPTERS_MFA_FACTOR_STORE` | `memory` | `adapters.mfaFactorStore`: `memory` (development and test only), `redis` or `store` (the Store's endpoints), read while `MFA_MODE` installs MFA. See [Multi-factor authentication](#multi-factor-authentication) |
-| `ADAPTERS_MFA_TRANSACTION_STORE` | `memory` | `adapters.mfaTransactionStore`: `memory` (development and test only) or `redis`, read while `MFA_MODE` installs MFA |
-| `ADAPTERS_CODE_REPOSITORY` | `redis` | `adapters.codeRepository`: the authorization-code repository, `memory` or `redis`. See [Code Repository](#code-repository) |
-| `ADAPTERS_CLIENT_REPOSITORY` | `yaml` | `adapters.clientRepository`: `yaml`, or `static` (core's alias of `yaml`). See [Client Repository](#client-repository) |
-| `ADAPTERS_USER_REPOSITORY` | `http` | `adapters.userRepository`: `http`, `yaml` or `static` (core's alias of `yaml`). See [User Repository](#user-repository) |
-| `ADAPTERS_AUDIT_SINK` | `logger` | `adapters.auditSink`: where security events go, `logger` (pino-enveloped NDJSON on stdout) or `console` (bare event JSON). There is no `none`. See [Audit trail](#audit-trail) |
-
-A selection still written where it was — `rateLimiter.adapter`,
-`oauth.code.adapter`, `audit.sink.type`, `repositories.user.type` and the
-like — or a variable renamed with it (`RATE_LIMITER_ADAPTER`, `CLIENT_TYPE`,
-…) set, alone or beside the new one at any value, fails before boot, naming
-the new path and variable: unset the old variable.
-
-### HTTP
-
-| Variable | Default | Description |
-|---|---|---|
-| `HTTP_PORT` | `3000` | Port the server listens on, `0` to `65535` in decimal digits; `0` lets the OS choose a free one. Set but empty, it fails boot |
-| `HTTP_TRUST_PROXY` | `false` | Express `trust proxy`: `false`, an address/CIDR list (`10.0.0.0/8,loopback`), a hop count (`1`), or `true`. **Required behind a load balancer** — otherwise every IP-keyed rate limit shares one bucket across all users. Prefer naming the proxy over `true`. See [Multi-replica deployments](#multi-replica-deployments) |
-| `HTTP_READINESS_TIMEOUT_MS` | `1000` | Per-probe deadline for `/readyz` (see [Health endpoints](#health-endpoints)) |
-| `LOGGING_LEVEL` | `info` | Minimum level emitted: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`. Does **not** gate the audit trail — see [Audit trail](#audit-trail) |
-
-### OAuth JWT
-
-The signing key is the `key-store` module's section: `key-store.provider`
-(`KEY_STORE_PROVIDER`, `local`) and the local key store's `key-store.local`
-(`KEY_STORE_LOCAL_*`). The issuer and the token format stay under `oauth.jwt`.
-
-| Variable | Default | Description |
-|---|---|---|
-| `KEY_STORE_LOCAL_ALGORITHM` | `EdDSA` | JWT signing algorithm: `EdDSA`, `ES256`, `RS256` or `HS256`. The default is asymmetric so `/.well-known/jwks.json` publishes a real verification key. |
-| `KEY_STORE_LOCAL_SECRET` | — | Signing secret, **HMAC (`HS256`) only**. At least 32 bytes (256 bits) of random material — `openssl rand -hex 32`. Hex/base64 values are measured **decoded**, so a 32-character hex string counts as 16 bytes and is refused. |
-| `OAUTH_JWT_ISSUER` | **(required)** | Canonical issuer URL stamped as `iss` on every token. Must be absolute `https` (`http` only for a loopback host), with no query or fragment. Boot fails when unset — it is never derived from the `Host` header. |
-| `OAUTH_REQUIRE_EMAIL_VERIFIED` | `false` | Refuse to issue tokens for a user until the Store publishes `emailVerified: true`. Enforced at `/authorize` and on the `session` grant. Verification itself is the Store's job — this only reads the result. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ENABLED` | `false` | Accept Client ID Metadata Documents (#529): a client whose `client_id` is the `https` URL of its own registration, the model MCP hosts use. Such a client is public, never first-party — it goes through the consent step, so wire `ADAPTERS_CONSENT_STORE`. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_SCOPES` | — | Comma-separated: what any such client may obtain (its document's `scope` is intersected with this). Empty admits none. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_AUDIENCES` | — | Comma-separated: the resource servers it may mint for (RFC 8707 `resource`). Empty admits only its own `client_id`. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ALLOWED_HOSTS` | — | Comma-separated hosts a document may live on: exact, or `.suffix` for a domain and its subdomains. Empty admits any public host. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_DENIED_HOSTS` | — | Comma-separated hosts refused even when allowed above. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_BYTES` | `5120` | Byte cap on a document (the draft recommends 5 KB). |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_TIMEOUT_MS` | `5000` | Fetch timeout. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_CACHE_MAX_AGE_MS` | `600000` | Upper bound on how long a valid document is served from cache; `Cache-Control: max-age` may shorten it. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_CACHE_ENTRIES` | `256` | How many documents are remembered at once. The keys are chosen by an unauthenticated caller, so the map is bounded. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_STALE_IF_ERROR_MS` | `300000` | How long a registration already validated is still served after a revalidation that failed for a reason that is not the document's (a DNS blip, a 5xx, a timeout) — an outage should not break a working client. A document that was *rejected* is dropped immediately. `0` disables it. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_NEGATIVE_CACHE_MS` | `60000` | How long a refusal is remembered, so the same `client_id` is not resolved and fetched again on every request. Short, so a client that fixes its document is not locked out. |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_CONCURRENT_FETCHES` | `8` | How many documents may be in flight at once, across every `client_id`. Bounds what an unauthenticated caller can make this server dial. |
-| `KEY_STORE_LOCAL_KID` | `v0` | Key ID included in the JWT header. 1 to 256 characters with no control character; anything else fails boot, including a variable exported but empty (which used to sign under the kid `""`; tokens issued that way are refused once it is corrected, so their users sign in again) |
-| `KEY_STORE_LOCAL_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
-| `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
-| `KEY_STORE_LOCAL_PUBLIC_KEY` | — | PEM-encoded public key |
-| `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` | — | Path to PEM public key file |
-| `OAUTH_JWT_LEGACY_TYP_ACCEPT` | `false` | Accept tokens whose `typ` header is absent. `false` rejects them, treating a typ-less token as the misconfiguration or downgrade attempt it usually is. Set `true` only for a bounded migration window while v0.4.x tokens are still in circulation. |
-| `JWKS_PATH` | `/.well-known/jwks.json` | Where the verification keys are published under the issuer, and what discovery advertises as `jwks_uri` (`jwks.path`). An absolute path with no `//`, dot-segment, query, fragment, backslash, percent-encoding or control character. |
-| `JWKS_CACHE_MAX_AGE` | `300` | The JWKS response's `Cache-Control: public, max-age`, in seconds (`jwks.cacheMaxAge`). Keep it well below the key-overlap window, so a rotated key reaches caching verifiers in time. |
-
-**Signing keys are required.** The default algorithm is `EdDSA` and there is no
-key-material default: a deployment that sets none fails at boot naming the keys
-to set, rather than quietly signing with something guessable. Generate an
-Ed25519 pair:
-
-```bash
-openssl genpkey -algorithm ed25519 -out jwt-private.pem
-openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
-```
-
-then point `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` / `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` at them
-(or inline the PEMs via `KEY_STORE_LOCAL_PRIVATE_KEY` / `KEY_STORE_LOCAL_PUBLIC_KEY`).
-
-`HS256` is still selectable (`KEY_STORE_LOCAL_ALGORITHM=HS256` plus a ≥32-byte
-`KEY_STORE_LOCAL_SECRET`), but understand what it costs: a symmetric key has no
-public half, so `/.well-known/jwks.json` answers `404 jwks_not_published` and
-every relying party must be handed the shared secret — which also lets it
-**mint** tokens, not merely verify them.
-
-### Token Expiry
-
-| Variable | Default | Description |
-|---|---|---|
-| `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_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
-boot failure, not a fallback (HOCON resolves `FOO=` to `""`), and so is a hex
-(`0x10`), exponent (`1e3`), sign (`+5`) or fraction (`5.0`).
-
-Only token exchange (RFC 8693) reads an `expires_in` request parameter; every
-other grant ignores it and mints the default.
-
-The default's old name, `OAUTH_ACCESS_TOKEN_EXPIRES_IN` (config key
-`oauth.accessToken.expiresIn`), refuses boot 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 |
-|---|---|---|
-| `OAUTH_SESSION_ENABLED` | `true` | Enable the session grant type |
-| `OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED` | `true` | Enable the authorization code grant type |
-| `OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED` | `true` | Enable the refresh token grant type |
-| `OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED` | `false` | Enable the client credentials grant type |
-| `OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED` | `false` | Enable the jwt-bearer grant type (RFC 7523) |
-
-Each switch is its module's key — `oauth-session.enabled`, and
-`oauth-authorization.grants.<grant>.enabled` for the others. Both modules are
-always loaded and read their switches at boot, from the configuration boot
-parses; the template reads none of them before boot. `OAUTH_GRANTS_<GRANT>_ENABLED`,
-the old names, refuse boot while they are set, alone or beside the new name at
-any value.
-
-### Session
-
-| Variable | Default | Description |
-|---|---|---|
-| `SESSION_STORE_SECRET` | — | **Required.** Signs the cookie that *is* the authenticated session, so guessing it forges logins. At least 32 bytes (256 bits) — `openssl rand -hex 32`. Measured **decoded**, same rule as `KEY_STORE_LOCAL_SECRET`. |
-| `SESSION_STORE_NAME` | `__Host-auth.session` | Session cookie name. The default uses the `__Host-` prefix and therefore requires `SESSION_STORE_SECURE=true` and no `SESSION_STORE_DOMAIN`. |
-| `SESSION_STORE_MAX_AGE` | `3600000` | Session cookie max age in milliseconds. Whole positive number, at most one year (`31536000000`). |
-| `SESSION_STORE_SECURE` | `true` | Set `Secure` flag on session cookie |
-| `SESSION_STORE_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`). `none` **requires** `SESSION_STORE_SECURE=true` — browsers drop a `SameSite=None` cookie that is not `Secure`, so boot refuses the combination rather than letting every login fail silently in the client. |
-| `SESSION_STORE_DOMAIN` | — | Cookie domain (unset by default) |
-| `SESSION_CSRF_TTL_SECONDS` | `7200` | Lifetime of an issued CSRF token, in seconds. Whole number in decimal digits, 1–86400; boot fails otherwise, an *empty* or blank value included. |
-| `SESSION_STORE_STORAGE_TYPE` | `redis` | Session store backend: `redis` or `memory`. `memory` is per process and is refused under `CORE_DEPLOYMENT_MODE=multi` like the other in-memory stores (#474) |
-| `SESSION_STORE_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
-| `SESSION_STORE_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
-
-The cookie and its store are the session store's section, `session-store`; the
-CSRF token's lifetime, the login page and the login's budget are the session
-module's, `session`. `SESSION_<KEY>`, the old names of the `SESSION_STORE_*`
-variables, refuse boot 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
-`auth.sid` — with `SESSION_STORE_SECURE=false`, one with no prefix: a `__Secure-` name
-needs `SESSION_STORE_SECURE=true` too. The server fails fast when a `__Host-` or
-`__Secure-` cookie name is combined with attributes that browsers reject for that
-prefix (in any case), on a `SESSION_STORE_NAME` that is not a cookie name (an RFC 6265
-token: no space, `;` or other separator), and on a `SESSION_STORE_DOMAIN` that is not a
-host name (a scheme, a port or a path).
-
-#### CSRF on `/session/login` and `/session/logout`
-
-Both routes accept a request carrying **either** a same-origin (or trusted)
-`Origin` / `Referer`, **or** a valid double-submit CSRF token, and reject one
-carrying neither (#272). Browsers satisfy this automatically; a scripted client
-calls `GET /session/csrf` first and sends the returned `csrf_token` back as
-both the `<SESSION_STORE_NAME>.csrf` cookie and an `x-csrf-token` header (or a
-`csrf_token` form field).
-
-Two configuration notes:
-
-- Behind a TLS-terminating proxy, set `HTTP_TRUST_PROXY` (to the proxy's
-  address or CIDR range, not `true`). Without it `req.protocol` reads `http`
-  while the browser sends `Origin: https://…`, and the origin arm rejects every
-  request.
-- If your login UI is served from a **different origin** than the provider,
-  list that origin under `session.csrf.trustedOrigins` in your HOCON config.
-  A listed origin can also answer federation-grant consents and device
-  verification, so a client's origin is never listed (the federation-grants
-  ADR's D7). `http.cors.allowedOrigins` does not confer CSRF trust — see
-  [CORS](#cors) for what it does confer.
-
-### CORS
-
-| Variable | Default | Description |
-|---|---|---|
-| `HTTP_CORS_ALLOWED_ORIGINS` | *(empty — CORS off)* | Comma-separated list of browser origins allowed to read the token, userinfo, revocation and discovery/JWKS responses |
-
-A browser app served from a different origin than this provider — an SPA on
-`https://app.example.com` against a provider on `https://auth.example.com` —
-cannot call the token endpoint at all unless that origin is on
-`http.cors.allowedOrigins`. Set it and the provider answers preflights and stamps
-`Access-Control-Allow-Origin` on the five endpoints a browser has a legitimate
-reason to call cross-origin:
-
-| Endpoint | Methods | Why |
-|---|---|---|
-| `/oauth/token` | `POST` | The PKCE code exchange and refresh — the call an SPA cannot avoid |
-| `/oauth/userinfo` | `GET`, `POST` | OIDC Core §5.3 defines both |
-| `/oauth/revoke` | `POST` | RFC 7009 §2.1 — a public client revoking its own tokens on sign-out |
-| `/.well-known/openid-configuration` | `GET` | Discovery, fetched by browser client libraries |
-| `/.well-known/jwks.json` | `GET` | Same; follows `jwks.path` when you override it |
-
-`/oauth/introspect` and `/oauth/authorize` are deliberately **not** included.
-Introspection is server-to-server and already refuses public clients, so no
-browser could use it; `/authorize` is a top-level navigation rather than a
-`fetch`, and CORS has no say over where a browser may navigate.
-
-```hocon
-http.cors {
-  allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
-}
-```
-
-or `HTTP_CORS_ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173`.
-Those are the two spellings; a value that is neither — a number, an
-object, a boolean, which only a configuration file can write — fails boot
-naming `http.cors.allowedOrigins` rather than reading as no origins.
-
-The list is part of the `http` module's section, with its default in
-`config/reference.conf`. The `http` module hands it to core's CORS middleware
-in the `httpSettings` slot, beside the trusted hops, and core reads the slot,
-not the configuration: a composition with no `httpSettings` provider mounts
-no CORS.
-
-**Matching is exact string equality against the `Origin` header**, and every
-shape that could not match fails at boot naming its index rather than sitting
-in the config admitting nobody. So: no trailing slash
-(`https://app.example.com/`), no explicit default port (`:443`), no path, no
-uppercase host, and **no wildcard** — there is no subdomain matching and there
-is not going to be. `https` is required except for a loopback host
-(`localhost`, `127.0.0.0/8`, `[::1]`), which is the carve-out that lets a
-front-end dev server work without a certificate.
-
-**Credentials are never allowed.** The provider sends no
-`Access-Control-Allow-Credentials`, so an allowlisted origin can read these
-responses and cannot use the browser's session cookie. That is deliberate: a
-cross-origin SPA here is a public client using PKCE and needs no cookie, while
-the cookie it would otherwise gain reaches the `session` grant — which
-exchanges an authenticated browser session for tokens. If your app needs that
-grant, serve it same-origin or put a BFF in front.
-
-Every response from these five routes carries `Vary: Origin`, including the
-ones with no CORS headers, so a shared cache cannot hand one origin's response
-to another. An empty list (the default) means the middleware is not mounted at
-all — no headers, no `Vary`, nothing changed.
-
-### Google Federation
-
-The federations are core's: `core.federations`, one map keyed by the name
-each is reached at (`/session/oauth/federation/<name>`). A key of one is bound
-to the variable named after its path, `CORE_FEDERATIONS_<NAME>_<KEY>`. The map
-written at the top level (`federations { ... }`) refuses boot, naming each
-key's path under `core.federations`; a `FEDERATIONS_GOOGLE_*` or
-`FEDERATIONS_OIDC_*` variable set, alone or beside its new name at 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 |
-|---|---|---|
-| `CORE_FEDERATIONS_GOOGLE_ENABLED` | `false` | Enable Google OAuth federation |
-| `CORE_FEDERATIONS_GOOGLE_CLIENT_ID` | — | Google OAuth client ID |
-| `CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
-| `CORE_FEDERATIONS_GOOGLE_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/google/callback` | Google OAuth callback URL |
-| `CORE_FEDERATIONS_GOOGLE_ACCESS_TYPE` | unset (`offline`) | `offline`: every sign-in shows Google's consent screen and every session gets a refresh token. `online`: consent on the first sign-in only, and no refresh token at all. See [federation-google](../../packages/federation-google/README.md#refresh-tokens-and-the-consent-screen) |
-
-### OIDC Federation (any OpenID Connect provider)
-
-One instance ships in `config/application.conf` under `core.federations.oidc`
-(`@o3co/auth-provider-federation-oidc`, #524): Okta, Entra ID, Auth0, Keycloak
-or your own tenant, selected by issuer. Discovery runs at boot and a failure
-refuses boot. The identity handed to the Store is `oidc:<sub>`; an identity
-the Store does not know is refused with 401 — nothing is provisioned.
-
-| Variable | Default | Description |
-|---|---|---|
-| `CORE_FEDERATIONS_OIDC_ENABLED` | `false` | Enable the OIDC federation |
-| `CORE_FEDERATIONS_OIDC_ISSUER` | — | Issuer identifier (https), exactly as the IdP writes `iss` |
-| `CORE_FEDERATIONS_OIDC_CLIENT_ID` | — | Client ID registered at the IdP |
-| `CORE_FEDERATIONS_OIDC_CLIENT_SECRET` | — | Client secret (`client_secret_basic`); set `privateKey` in the config file for `private_key_jwt` instead |
-| `CORE_FEDERATIONS_OIDC_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/oidc/callback` | Where the IdP sends the browser back |
-
-A second IdP is another section with `type = "oidc"` and its own callback:
-
-```hocon
-core.federations {
-  okta {
-    enabled = true
-    type = "oidc"
-    issuer = "https://dev-123.okta.com"
-    clientId = ${OKTA_CLIENT_ID}
-    clientSecret = ${OKTA_CLIENT_SECRET}
-    callbackURL = "https://auth.example.com/session/oauth/federation/okta/callback"
-    redirectAllowlist = ["https://app.example.com/welcome"]
-  }
-}
-```
-
-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` —
-is documented in [its README](../../packages/federation-oidc/README.md).
-
-### Client Repository
-
-| Variable | Default | Description |
-|---|---|---|
-| `ADAPTERS_CLIENT_REPOSITORY` | `yaml` | Client store backend: `yaml`, or `static`, core's alias of `yaml`, which reads `repositories.client.static.path` (no default) |
-| `REPOSITORIES_CLIENT_YAML_PATH` | `./config/clients.yaml` | Path to the YAML client registry |
-
-The registry is per-deployment configuration: `.gitignore` keeps
-`config/clients.yaml` out of git and `.dockerignore` keeps it out of the image,
-and the production compose file mounts it (see [Docker](#docker)).
-
-### User Repository
-
-| Variable | Default | Description |
-|---|---|---|
-| `ADAPTERS_USER_REPOSITORY` | `http` | User repository backend: `http`, or `yaml` for local work (`static`, core's alias of `yaml`, reads `repositories.user.static.path`, with no default) |
-| `REPOSITORIES_USER_YAML_PATH` | `./config/users.yaml` | The YAML user file the `yaml` backend reads |
-| `REPOSITORIES_USER_HTTP_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
-| `REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
-| `REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store links a federated identity at (#482); enables `?link=1` on the federation start route. **https required** |
-| `REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store answers who holds an upstream identity at (#613, federation grants' check 5). With it, declare what the Store covers in `repositories.user.http.federatedIdentityLookupCoverage` (HOCON). **https required** |
-| `REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` | — | Optional. URL the Store keeps the MFA enrollment witness at (the MFA ADR's D12): with it, a lost factor store cannot open a first binding. The Store must then answer `mfaEnrolled` on both authenticate URLs. Unset, a boot with MFA on warns (`mfa_enrollment_witness_unwritable`). **https required** |
-| `REPOSITORIES_USER_HTTP_BEARER_TOKEN` | — | Optional. The credential this server presents to the Store: every Store request carries `Authorization: Bearer <token>`. A bare token (no `Bearer ` prefix) of at least 32 bytes — `openssl rand -hex 32`. Unset, no `Authorization` header is sent (see below) |
-| `REPOSITORIES_USER_HTTP_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
-| `REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
-
-**The `yaml` users file** is keyed by username; each entry holds `password`,
-and optionally `id` (the username when absent) and claims. A password is plain
-text, or a bcrypt hash: anything starting with `$2` is read as one, and must be
-a well-formed `$2a$`, `$2b$` or `$2y$` hash (the last compared as `$2b$`) at a
-cost from 04 to 15 (a compare at 15 takes about 2 s, at 10 about 60 ms, on a
-thread of Node's libuv pool). `$2b$` and `$2y$` compare only the first 72
-bytes of a password (about 24 Japanese characters in UTF-8). `$2a$` reads the
-same 72 bytes of a password up to 254 bytes long, but counts a longer one's
-length modulo 256, so a password of 255 bytes or more can compare as a
-different one; use `$2b$` for new entries. A plain-text entry is compared over
-its full length.
-Every bcrypt entry uses one cost. Boot refuses a password that breaks these
-rules, bcrypt entries at more than one cost (naming the costs), an empty `id`
-or username, two users with the same id, and a `username` key inside an entry,
-naming the field and the user or the costs, never a value. Each start with the `yaml` backend logs
-`user_repository_in_memory` at warn on the template's logger (`LOGGING_LEVEL`
-applies), whatever the environment: the users file is meant for development
-and tests. See
-[the core package's README](../../packages/core/README.md#loading-clients-and-users-from-yaml).
-
-Both user-authentication URLs carry **plaintext user credentials** to the
-upstream store, so both must be absolute `https://` URLs. `http://` is accepted
-only for a loopback host — `localhost`, an address in `127.0.0.0/8`, or `[::1]`
-— so that local development needs no certificate. A private-range address
-(`http://10.0.0.5/…`) or a container-network service name
-(`http://user-service/…`) still requires `https://`: those cross a network the
-deployment does not control end to end. Boot fails if either URL, the timeout,
-or the response cap is unusable, rather than at the first login attempt.
-
-Each URL must be the endpoint that answers, not one that redirects: no request
-follows a `3xx`, so a URL that redirects fails every call — see
-[What the Store must enforce itself](../../packages/foundation/README.md#what-the-store-must-enforce-itself).
-
-**Who may call the Store.** What the token-based login and account linking
-send is an identifier, not a secret, so a Store that answers any caller
-resolves a known identity to its user — or links one to any account — for
-anyone who can reach it. Set `REPOSITORIES_USER_HTTP_BEARER_TOKEN` and have the Store
-answer every request whose `Authorization` is not exactly `Bearer <that token>`
-with `401` and `WWW-Authenticate: Bearer error="invalid_token"` (or `403` and
-`error="insufficient_scope"`). The one token goes to every Store URL above, so
-those endpoints must be one trust domain. With `ADAPTERS_USER_REPOSITORY=http` — this
-template's default — boot fails if the token is weaker than 32 bytes
-(measured like `SESSION_STORE_SECRET`), malformed, or exported but empty; it appears
-in no error this server throws. With that challenge, a token the Store does not
-accept is an outage on every Store call: logins answer
-`503 temporarily_unavailable` and log an error naming the refused credential,
-not the token, and so do federation-grants connects
-(`federation_grant_callback_unavailable`). A `401` or `403` without the
-challenge keeps its old meaning — at login "no such user", at a `?link=1`
-link a refusal, and at the federation-grants identity lookup an outage like
-any other non-`2xx` — so a mismatch then shows only as every login failing
-and every link refused; and a Store must not put a `Bearer` challenge on a
-user's wrong password or a link it refuses. A Store that cannot be reached,
-closes the connection before a complete response, or answers with a malformed
-HTTP response is logged as such, with at most a transport code
-(`ECONNREFUSED`, `UND_ERR_SOCKET`, `ERR_SSL_WRONG_VERSION_NUMBER`, …), and
-never with what the transport quoted. Without the token, admit only this server to the Store
-by network policy or platform mutual TLS. Rotation, what each caller logs, and
-what the Store checks are in the same foundation README section.
-
-### Code Repository
-
-`adapters.codeRepository` (`ADAPTERS_CODE_REPOSITORY`) chooses the
-repository; each reads its own section. The Redis one runs on the shared
-connection `REDIS_CLIENTS_URL` configures, so it takes no URL or password of
-its own.
-
-| Variable | Default | Description |
-|---|---|---|
-| `REDIS_CODE_REPOSITORY_DEFAULT_EXPIRES_IN` | `600` | `redis-code-repository.defaultExpiresIn`: the Redis repository's default authorization-code lifetime, in seconds |
-| `REDIS_CODE_REPOSITORY_KEY_PREFIX` | `oauth:code:` | `redis-code-repository.keyPrefix`: the Redis repository's key namespace (see [Redis Namespacing](#redis-namespacing)) |
-| `STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN` | `600` | `standalone-in-memory-code-repository.defaultExpiresIn`: the in-process repository's, a positive whole number of seconds |
-
-`CLIENT_CODE_DEFAULT_EXPIRES_IN` and `CLIENT_CODE_KEY_PREFIX` were renamed
-with them, and `CLIENT_CODE_ENDPOINT_URI` and `CLIENT_CODE_PASSWORD` removed. A
-renamed one set, alone or beside its new name at any value, and a removed one
-set at all, fails boot naming what to set instead.
-
-### Federation Token Store
-
-The upstream IdP tokens (a Google refresh token, say) held on behalf of a
-session. Memory by default, which forks per replica and is refused under
-`CORE_DEPLOYMENT_MODE=multi`; the Redis store shares the socket configured by
-`REDIS_CLIENTS_URL` and encrypts records at rest, so it
-needs a key.
-
-| Variable | Default | Description |
-|---|---|---|
-| `ADAPTERS_FEDERATION_TOKEN_STORE` | `memory` | Federation token store backend: `memory` or `redis` |
-| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` | — | AES-256-GCM key for records at rest: 32 bytes, base64-encoded (`openssl rand -base64 32`). **Required** with `redis` unless the mode below is `allow-plaintext` |
-| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused when the config was selected by a production/staging environment (`CONFIG_ENV` or `NODE_ENV`) and under `CORE_DEPLOYMENT_MODE=multi` in any environment, unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` is also set — development only |
-
-`ttl` (seconds; keep it above the upstream refresh-token lifetime) and the #291
-`scanFallback` migration flag live under `redis-federation-token-store` in a
-config layer rather than behind an environment variable.
-
-### Consent Store
-
-Where an end-user's consent to a client that is not first-party is recorded,
-together with the `/authorize` request parked while the consent page asks
-(#527, #552). One switch wires both. `none` by default: such clients are
-refused and only first-party clients are served. `memory` forks per replica and
-is refused under `CORE_DEPLOYMENT_MODE=multi`; `redis` (#561) shares both over the
-socket configured by `REDIS_CLIENTS_URL`.
-
-| Variable | Default | Description |
-|---|---|---|
-| `ADAPTERS_CONSENT_STORE` | `none` | Consent store for clients that are not first-party (#527): `none` (such clients are refused), `memory` (single replica) or `redis` (shared, #561) |
-
-### Multi-factor authentication
-
-A second factor after a password login, and a step-up when a relying party
-asks for one at `/authorize` — the [MFA package](../../packages/mfa/README.md).
-`MFA_MODE` is the template's own switch, `mfaMode`
-([`config/reference.conf`](config/reference.conf)): `required`, the default
-(every password login has a second factor), and `optional` (a user with a
-factor is challenged, nobody is forced) install the MFA module, the TOTP, recovery-code and email factors (email off
-unless `MFA_EMAIL_FACTOR_ENABLED`), the operator reset
-(`handle.components.mfaReset`), the session package's login completion and
-the two MFA stores `adapters` selects. The template then adds `mfa` to
-`core.sessionRequirements.expected`, names it
-`core.sessionRequirements.secondFactorAuthority` and writes `mfa.mode` from
-the switch, so
-a composition that asks for a second factor and cannot enforce one is refused
-at boot rather than let a password alone sign in; `off` installs nothing of
-MFA. A value that is none of the three is refused before boot, naming
-`mfaMode` and `MFA_MODE`.
-
-**On by default.** In development (`make dev`) MFA needs nothing more: the
-sample key in `config/development.conf`, the sender that logs each code, and
-`docker-compose.yml`'s Redis for the two stores. Outside development a
-deployment either sets what MFA needs — the two stores on `redis` (or the
-factors in the `store`), `MFA_ENCRYPTION_KEY` and the SMTP relay
-(`STANDARD_SMTP_MAIL_SENDER_HOST` and `_FROM`, or a sender of its own through
-`buildModules`' `mailSenderModules`) — or sets `MFA_MODE=off`. Until it
-decides, the boot is refused before the app is created: the stores' refusal
-comes first, naming each of those and `MFA_MODE=off`. The MFA page is never
-refused: `MFA_PAGE_URL` defaults to `/mfa`, which the deployment must serve,
-in development too, or every password login stops there.
-
-| Variable | Default | Description |
-|---|---|---|
-| `MFA_MODE` | `required` | `mfaMode`: `required`, `optional` or `off` |
-| `MFA_ENCRYPTION_KEY` | — | The MFA key ring's first key, which seals every factor's data: canonical base64 of 32 bytes (`openssl rand -base64 32`). Required with MFA on. Under `CONFIG_ENV=development`, `config/development.conf` puts the MFA package's published sample key in its place: write your own key there instead, since this variable set beside that ring refuses the boot. The sample key is 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` |
-| `STANDARD_SMTP_MAIL_SENDER_FROM` | — | The one sender address of that mail |
-| `STANDARD_SMTP_MAIL_SENDER_PORT` | `587` | The relay's port |
-| `STANDARD_SMTP_MAIL_SENDER_SECURE` | `starttls` | `starttls`, `tls`, or `none` to a loopback relay only |
-| `STANDARD_SMTP_MAIL_SENDER_USER` | — | The relay account, with `STANDARD_SMTP_MAIL_SENDER_PASSWORD` |
-| `STANDARD_SMTP_MAIL_SENDER_PASSWORD` | — | That account's password |
-
-The rest of the MFA settings — each factor's, the lock, a transaction's life
-— are the MFA package's, with their variables, in its
-[README](../../packages/mfa/README.md#configuration). A few things to know:
-
-- **The stores.** `memory`, the shipped selection, is for development and
-  test alone: a restart loses every factor, lock and recorded email proof,
-  after which whoever holds a password can bind a factor of their own. With
-  MFA on it is refused before boot unless the configuration's name, and
-  `CONFIG_ENV` and `NODE_ENV` wherever set, each say `development` or
-  `test`, and core refuses it under `CORE_DEPLOYMENT_MODE=multi`. Production
-  needs `redis` for both, or `store` for the factors: `redis` shares the
-  socket `REDIS_CLIENTS_URL` opens; `store` (factors only) keeps them behind the Store's four endpoints
-  (`FOUNDATION_MFA_FACTOR_STORE_*`,
-  [foundation's README](../../packages/foundation/README.md)), sent the same
-  bearer token as the user repository.
-- **The enrollment witness.** With `ADAPTERS_USER_REPOSITORY=http`, set
-  `REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` ([User Repository](#user-repository));
-  without it, boot warns once (`mfa_enrollment_witness_unwritable`).
-- **`acr`.** With MFA on, the template adds `"urn:o3co:acr:mfa" = ["mfa"]`
-  to `oauth.authorize.acrValues`, unless your configuration writes that
-  entry, and discovery advertises it. With MFA off it adds nothing: the acr
-  table and discovery are what they are without MFA.
-- **The mail in development.** Under `CONFIG_ENV=development` the template's
-  sender logs each code (`mail_code_issued`) and sends nothing. To run the
-  SMTP sender and read what it sends, use the
-  [Mailpit overlay](#mailpit-for-the-smtp-sender-development-only).
-- **One switch.** A file that writes `mfaMode` while `MFA_MODE` is set to
-  something else, and a configuration that writes `mfa.mode` other than
-  what the switch says, are refused before boot, naming the keys. While MFA
-  is off, nothing the configuration writes under `mfa` is handed to boot.
-
-### Federation Grants
-
-Offline delegation of an upstream IdP's tokens (#593): a user consents once
-that a client — a backend, an agent — may obtain access tokens for one
-upstream connection on their behalf, and the client obtains them over HTTP
-later, with the user not present. A grant **survives logout**; a credential
-change ends it through the subject-revocation service. Off by default, and
-off installs nothing. The routes and what each answer means are in the
-[package README](../../packages/federation-grants/README.md); what each IdP
-needs before it issues a refresh token is in
-[`docs/offline-access.md`](../../packages/federation-grants/docs/offline-access.md).
-
-| Variable | Default | Description |
-|---|---|---|
-| `FEDERATION_GRANTS_ENABLED` | `false` | Installs the routes, the two stores selected below (none until selected) and the subject-revocation service |
-| `FEDERATION_GRANTS_CONSENT_URL` | — | The deployment's consent page for grants: a path, or an absolute URL on the provider's origin. No default — enabling grants is a statement that the page exists, and boot refuses without it |
-| `FEDERATION_GRANTS_IDENTITY_LOOKUP` | `required` | Whether the connect callback refuses an upstream account already linked to another local user. `required` needs a user repository that covers every connection's registration (below); `unsupported` records that the check is not made |
-| `ADAPTERS_FEDERATION_GRANT_STORE` | `none` | Where grants live: `none` (no store; an enabled feature refuses boot naming it), `memory` (one replica; lost on restart, every user reconnects) or `redis` (the shared socket) |
-| `ADAPTERS_FEDERATION_GRANT_INTENT_STORE` | `none` | Where acquisition's records live — the intent a backend lodged, the consent challenge, the connect transaction: `none` (no store; an enabled feature refuses boot naming it), `memory` (one replica; a restart loses flows in progress and nothing else) or `redis` |
-| `REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused in production/staging and under `CORE_DEPLOYMENT_MODE=multi` unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` |
-| `FEDERATION_GRANTS_ALLOW_KEEP_ON_SUBJECT_REVOCATION` | `false` | Whether a subject-wide revocation may be *asked* to leave established grants standing. An allowance, not an instruction |
-| `REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX` | `fg:` | Key namespace of the Redis grant store |
-| `REDIS_FEDERATION_GRANT_INTENT_STORE_KEY_PREFIX` | `fg:` | Key namespace of the Redis intent store; set it with the grant store's — the template refuses to boot with the grant store's set and this one left at its default |
-
-The feature's own settings are the `federation-grants {}` section; the Redis
-grant store's — its key ring, its encryption mode, its prefix — are
-`redis-federation-grant-store {}`. **Two things have no environment form**,
-because a list is HOCON's: the connections, and the encryption key ring.
-Write them in a deployment-owned layer — `config/production.conf`, say:
-
-```hocon
-redis-federation-grant-store {
-  encryptionKeys = [
-    # The first key seals; every listed key opens. GRANT_KEY_2026_09 is a name
-    # you choose (openssl rand -base64 32), not a template override.
-    { id = "2026-09", key = ${GRANT_KEY_2026_09} }
-  ]
-}
-
-federation-grants {
-  connections {
-    files {
-      federation = "entra-files"   # an enabled core.federations.<name> of type "oidc", with an app registration of its own
-      scopes = ["openid", "profile", "offline_access", "Files.Read"]
-      boundary = "production"
-      maxAccessTokenLifetime = 3600
-      # The grant flow's own callback on this provider's origin — not the
-      # federation's login callback.
-      callbackURL = "https://auth.example/session/federation-grants/callback/files"
-      allowScopeSubsets = false
-      identityClaims = ["oid", "tid"]
-    }
-  }
-}
-```
-
-**What boot refuses**, each named, rather than met by a user mid-flow: no
-consent page; a connection without `callbackURL`, on a federation that is not
-enabled, or on one whose adapter lacks the delegated capability — only the
-generic OIDC adapter has it, so a Google connection is a `type = "oidc"`
-federation; `required` with a user repository that does not cover a
-connection's registration; Redis grants beside memory user-session stores
-(`ADAPTERS_USER_SESSION_STORES=memory` — the grants would outlive the boundary
-that ends them; both compose files set `redis`); the Redis grant store under
-`encryptionMode = "required"` with no key in the ring (the memory store seals
-nothing and needs none); `memory` for either store under `CORE_DEPLOYMENT_MODE=multi`.
-
-**The user repository.** Under `required`, boot asks the repository whether it
-covers each connection's registration, and the connect callback asks it who
-holds the upstream account. The template's `http` repository asks your Store
-(#613): set `REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` to the
-endpoint, and declare what that endpoint covers — one entry per registration,
-with the claims the Store's strategy needs — in a HOCON layer:
-
-```hocon
-repositories.user.http.federatedIdentityLookupCoverage = [
-  { provider = "entra-files", issuer = "https://login.microsoftonline.com/<tenant>/v2.0",
-    clientId = "<the grants app registration>", requiredClaims = ["tid", "oid"] }
-]
-```
-
-Boot then holds every connection to it: one whose registration is not
-declared, or whose `identityClaims` misses a required claim, is refused by
-name. The wire contract the Store implements — and what "unlinked" obliges it
-to have checked — is in the
-[foundation README](../../packages/foundation/README.md#the-identity-lookup-613);
-the Store is not asked at boot. The bundled in-memory repository covers no
-registration. Without a covering Store, set
-`FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported` — the recorded decision not to
-refuse an upstream account another local user already holds. With no
-connection configured nothing is required.
-
-**Registering a client.** In `config/clients.yaml`, a confidential client that
-may hold grants names the connections it may ask for and where the browser
-may be returned. Neither its `allowedRedirectUris` nor `firstParty` grants
-either:
-
-```yaml
-worker:
-  tokenEndpointAuthMethod: "client_secret_basic"
-  clientSecret: "$2b$10$…"
-  allowedFederationGrantConnections: ["files"]
-  federationGrantRedirectUris: ["https://worker.example/connected"]
-```
-
-**The flow, from the client's side.** `POST /oauth/federation-grants`
-(client-authenticated) lodges an intent for a `sub` and answers a `grant_id`
-and a `connect_uri`; the client sends the user's browser there. The provider
-signs the user in if needed, shows your consent page, sends them to the
-upstream, and returns the browser to the client's `redirect_uri` with
-`grant_id` and `state` — never a token. The client then calls
-`/oauth/federation-grants/:grantId/token`, `/status` and `/revoke` with its
-own credentials and the user's `sub`, with no user present.
-
-**The consent page** is yours, same-origin with the provider, and its contract
-is `/oauth/consent`'s, so one page can serve both. `GET
-/session/federation-grants/consent?challenge=…` answers JSON: `client_id`,
-`client_name`, `connection`, `scopes`, `resource`, `grant_expires_in` (a
-duration after approval, not a date), `continues_after_logout` (which the page
-must show), and `expires_in` (what is left of the flow). `POST` with
-`challenge` and `decision` (`accept` | `deny`) answers `303` — to the upstream,
-or back to the client. Every acquisition and renewal goes through it. The
-answer is held to the session module's CSRF policy: post it as a form from the
-page, and serve the page with `Referrer-Policy: same-origin` — not
-`no-referrer`, whether by the header, `<meta name="referrer">` or
-`rel="noreferrer"` on the form, under which the browser sends `Origin: null`
-and the answer is refused. This app's `helmet()` sends `no-referrer` on every
-response, so a page it serves sets `Referrer-Policy: same-origin` on its own
-route. Behind a proxy, `HTTP_TRUST_PROXY` names it, and it forwards
-`X-Forwarded-Proto` and `X-Forwarded-Host` (or keeps the browser's `Host`). A
-user agent that sends neither `Origin` nor `Referer` echoes the token
-`GET /session/csrf` hands out, as for `POST /session/login`; a page may always
-include it, since it counts only when neither is sent. The package README has
-the rule.
-
-**The login page** is the one `SESSION_LOGIN_PAGE_URL` names, reached with
-`redirect_to=<the connect link>`; it signs the user in and navigates back to
-that link unchanged, as it does for `/oauth/authorize`. Do not submit the link
-to `POST /session/login` as its `redirect_to`: that route's exact-match
-allowlist is for landing pages and refuses a per-flow handle.
-
-**Operating it.** Rotate the key ring by the procedure in the
-[operator runbook](../../docs/operator-runbook.md) — new key last, then first,
-old key kept 365 days. A shutdown gives cleanup 45 seconds while the feature
-is on — more if you raise `upstreamHardTimeoutMs`, `persistRetryBudgetMs` or
-`lockWaitMs`, since the allowance is their sum plus a margin — and both
-compose files give the process 60; see
-[Shutdown guarantees](#shutdown-guarantees). Disabling the feature is not
-revoking: grants stay in Redis until revoked, so end them first, and keep the
-keys and the revocation boundaries through any temporary shutdown.
-
-### Redis Namespacing
-
-For multi-tenant Redis clusters, set deployment-specific key prefixes so two
-auth.provider instances cannot collide in the same database:
-
-| Variable | Default | Description |
-|---|---|---|
-| `REDIS_SESSION_STORES_KEY_PREFIX` | `ss:` | Outer prefix for user sessions, the subject session index, the subject-revocation boundaries and the session lifecycle records. |
-| `REDIS_REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
-| `REDIS_CODE_REPOSITORY_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
-| `REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX` | `ft:` | Prefix for federation token records, their per-session index and their lock keys. |
-| `REDIS_CONSENT_STORE_KEY_PREFIX` | `consent:` | Prefix for consent records and for parked consent requests with their per-session index (`ADAPTERS_CONSENT_STORE=redis`, #561). |
-
-Use values that include the deployment name, for example `tenant-a:ss:`,
-`tenant-a:rtfam:`, `tenant-a:code:`, `tenant-a:ft:`, and `tenant-a:consent:`.
-
-### Endpoints
-
-| Variable | Default | Description |
-|---|---|---|
-| `SESSION_LOGIN_PAGE_URL` | `/login` | URL of the login page (for redirects) |
-| `OAUTH_CONSENT_PAGE_URL` | `/consent` | URL of the consent page a client that is not first-party is routed through, with `?challenge=<id>` (#527) |
-
-There is no deployment-wide client or callback URL: federation callback URLs
-are configured per federation (`CORE_FEDERATIONS_GOOGLE_CALLBACK_URL`,
-`CORE_FEDERATIONS_OIDC_CALLBACK_URL`).
-
-## Module Composition Order
-
-[`src/buildModules.mts`](src/buildModules.mts) is the single source of truth for which modules are composed and in what order — read it rather than a copy of it. The boot planner resolves `requires` / `provides` topologically, but it mounts routes and middleware in list order unless a module declares `before` / `after` — so position matters for anything that mounts. These are the rules to keep when you edit the list:
-
-1. **`sessionStoreModule` stays first.** It mounts the `express-session` middleware and declares no `before` / `after`, so its position in the list is what puts it ahead of every route that reads `req.session`. It declares its replica safety from its own section, so `session-store.storage.type = "memory"` is replica-unsafe and refused under `core.deployment.mode = "multi"`.
-2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthEndpointsModule` and any module of your own may all mount routes under `/oauth`. `oauthEndpointsModule`'s router parses the bodies of its own routes only, so each module's requests reach its own parsers whatever the list order — provided every module under `/oauth` parses its own body and scopes its parsers to exactly its own paths, as the shipped ones do — a route (`router.all(path, parser)` or the route's own handler list), not `router.use(path, parser)`, which matches every path beneath `path` as well. The federation grants browser half orders itself after the session middleware with its own `after`.
-3. **One module per store slot.** Each adapter switch — `adapters.federationTokenStore`, `adapters.userSessionStores`, `adapters.rateLimiter`, `adapters.codeRepository`, `adapters.accessTokenDenylist`, `adapters.replaySeenSet`, `adapters.consentStore`, the two federation-grant store switches and the two MFA store switches — picks one of a memory / Redis pair (or, for the MFA factors, the Store). Both provide the same slot, so wiring both is a boot-time slot collision. `adapters.consentStore = "none"` wires neither, the federation-grant stores are wired only while the feature is enabled, and the MFA stores only while `MFA_MODE` installs MFA.
-4. **The shared Redis connection comes with the first Redis-backed module.** `standaloneRedisClientsModule` opens the one ioredis connection every Redis adapter here uses, from its own section (`redis-clients`), and is added whenever a composed module needs one. The refresh-token family store is on Redis in the shipped composition, so a deployment always has it; the in-memory family store is a test override (`overrides.refreshTokenFamilyModules`).
-5. **The template's own settings modules are always composed.** `loggingModule` and `httpModule` own `logging {}` and `http {}`, the CORS list among `http`'s keys (`http.cors.allowedOrigins`). `httpModule` provides core's `httpSettings`, which is authoritative, so no `overrideComponents` entry replaces it while the module is loaded; it also provides the template's `httpHostSettings`, which `app.mts` reads after boot for the port and the readiness deadline. The logger is built before boot from the `logging` section (`readLogging`), not by a module, and handed to boot as the `logger` component.
-6. **The federation types are always composed.** `googleFederationTypeModule()` and `oidcFederationTypeModule()` are listed whatever `core.federations` says: each contributes its type, and boot builds one federation per enabled entry of it, under the entry's name, so a federation is added or removed in configuration alone. Nothing in the list reads an entry. A module that contributes a federation under an entry's name directly beside an entry dispatched by its type is a boot-time `duplicate-contribute`: add a federation of another kind as a type module, and give its entries that type.
-7. **The mail sender follows the environment.** `@o3co/auth-provider-standard`'s development sender, which logs each code, where the configuration was selected as `development`; its module installs only where that name, and `CONFIG_ENV` and `NODE_ENV` wherever they are set, each read `development` or `test`, and refuses the boot otherwise, or where `core.deployment.mode` is `multi`. Under any other name, the SMTP sender's module, whose section is `standard-smtp-mail-sender` ([the package's README](../../packages/standard/README.md)); its sender is built only where something reads the `mailSender` slot, and there the boot needs `STANDARD_SMTP_MAIL_SENDER_HOST` and `STANDARD_SMTP_MAIL_SENDER_FROM`. While `MFA_MODE` is `off` nothing reads the slot, so the template boots without them; with MFA on, the MFA module and the operator reset read it. A sender of your own replaces this choice: pass its module where [`src/app.mts`](src/app.mts) calls `buildModules`, as `buildModules(switches, { environment: env, mailSenderModules: [mySenderModule] })`. Given, `mailSenderModules` is installed under every environment name and the bundled sender is not, so the two never both provide the slot; an empty list installs no sender, and a module that needs one (the MFA email factor, or the MFA module with `requireEmailProof = "always"`) then refuses the boot.
-
-`jwksModule` (from core) is always composed: a provider that signs tokens publishes its verification keys whether or not an issuer is configured. What each route module mounts is in its package's README. 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
-
-`src/routes.mts` mounts these on the host app ahead of the composed auth router, so they keep answering while the auth pipeline is degraded — which is when an operator needs them — and core's terminal error handler after all of them, so an error one of them lets through is answered as the auth routes' are (`500 server_error`, logged once as `unhandled_request_error`). The JWKS route is not one of them: `jwksModule` contributes it (see above).
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/_healthcheck` | Liveness — `200 {"status":"ok"}` whenever the process is up, whatever Redis is doing. See [Health endpoints](#health-endpoints) |
-| `GET` | `/readyz` | Readiness — runs every registered dependency probe (`redis`, `session-store`, …) under `HTTP_READINESS_TIMEOUT_MS`; `200 {"status":"ready"}` or `503 {"status":"unready"}`, never cached |
-| `GET` | `/metrics` | Prometheus text exposition; dependency gauges are re-probed on every scrape. Keep it off the public listener — see [Metrics](#metrics) |
-
-## Docker
-
-The Dockerfile uses multi-stage builds with the following targets:
-
-| Target | Purpose |
-|---|---|
-| `runtime` | Production image (compiled JS only) |
-| `develop` | Development image with hot reload (`pnpm run debug`) |
-| `test` | Test runner image |
-
-```bash
-# Build the production image
-make build IMAGE=my-auth-provider
-
-# Start with docker compose (development)
-make dev
-
-# Run tests in Docker
-make test
-```
-
-The `docker-compose.yml` starts the auth server together with a Redis container. Configure environment variables in `.env`.
-
-`docker-compose.yml` is a **development** file: it builds the `develop` target and bind-mounts `./src` and `./config`, so deploying it ships a hot-reload server running your working tree. The deployable shape is
-[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target, no source mounts, restart policies, a network-internal persistent Redis, and a **required** `.env` (a boot without a real `SESSION_STORE_SECRET` must fail loudly). Its header comments state what it deliberately leaves to you: TLS termination in front, and the [multi-replica](#multi-replica-deployments) steps before any `--scale`.
-
-`HTTP_TRUST_PROXY` is an explicit `${HTTP_TRUST_PROXY:?…}` entry there, so `docker compose up` **refuses to start** until you name the hop in `.env`. That is deliberate: there is no address the file could default to that would not silently trust a hop you never chose, and without the variable the Secure cookie the file pins is never set, the CSRF origin check 403s every browser POST, and every IP-keyed rate limit shares one bucket.
-
-Every store whose records must outlive one process is named in that file's `environment:` block rather than inherited — including `ADAPTERS_USER_SESSION_STORES=redis`, which has to travel with `SESSION_STORE_STORAGE_TYPE=redis`. `CORE_DEPLOYMENT_MODE=single` will not tell you when it does not: the replica guard answers "can these stores be shared", not "do these two stores have the same lifetime". Split them and a restart leaves every browser holding a surviving express-session that still reads `isAuthenticated` with no `UserSession` behind it — `/authorize` bounces to login, the cookie bounces it back, and the loop clears only when the user deletes the cookie.
-
-The two MFA stores are the exception, since MFA is on by default and whether to keep it is the deployment's decision: the production file leaves them at `memory`, which the template refuses in production before boot, naming the stores, `MFA_ENCRYPTION_KEY`, the SMTP relay, `MFA_PAGE_URL` and `MFA_MODE=off`. Set them in `.env` — `ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`, on the file's persistent Redis, with the rest of [Multi-factor authentication](#multi-factor-authentication) — or set `MFA_MODE=off`. `docker-compose.yml` keeps both on its Redis, so that a hot reload does not empty them while the sessions survive.
-
-```bash
-# The signing keys are a required input: EdDSA is the default and there is no
-# key-material default, so a deployment that generates none fails at boot.
-openssl genpkey -algorithm ed25519 -out jwt-private.pem
-openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
-chmod 600 jwt-private.pem
-
-# The client registry is a required input too: the scaffold's
-# config/clients.yaml, or one made from config/clients.yaml.example.
-
-docker compose -f docker-compose.production.yml up -d --build
-```
-
-**Keys in containers.** The pem pair reaches the container as a compose
-**secret**, mounted read-only at `/run/secrets/`, and the compose file points
-`KEY_STORE_LOCAL_*_KEY_PATH` there. Do not park them in `config/`: the `Dockerfile`
-`COPY`s that directory. `.dockerignore` keeps every `*.pem` and `*.key` out of
-the build context, as `.gitignore` keeps them out of git, but a key under any
-other name placed there is baked into an image layer and travels with every
-push — a key you then have to rotate rather than one you merely stored badly.
-The same applies to `.env`; keep both out of git.
-
-**The client registry in containers.** `config/clients.yaml` arrives the same
-way, as the compose secret `client_registry`, with `REPOSITORIES_CLIENT_YAML_PATH` pointed at it.
-It is per-deployment and may hold client secrets, so `.dockerignore` keeps it
-out of the build context: no image carries a registry, and an image built from
-a working copy is the same as one built from a clean checkout. Compose refuses
-to start until the file exists. Run the image some other way and you mount it
-and set `REPOSITORIES_CLIENT_YAML_PATH` yourself.
-
-The production file also pins `SESSION_STORE_SECURE=true` and the `__Host-` cookie
-name in its `environment:` block, which wins over `env_file`. `.env.example`
-ships `SESSION_STORE_SECURE=false` so that a plain-HTTP compose run (`make dev`) does
-not trip the `__Host-` cookie check, and this file requires that same `.env` — behind the TLS it assumes, a non-Secure session
-cookie is the session handed to anyone who can read one plaintext hop.
-
-The image installs with `pnpm install --frozen-lockfile`, so a committed
-`pnpm-lock.yaml` is a required build input — `create-auth-provider` generates
-one at scaffold time; if yours is missing, run `pnpm install` once and commit
-the result. Rebuilding the same source then produces the same dependency tree.
-
-The production image sets `ENV HTTP_PORT=3000` and uses it for both `EXPOSE`
-and the Docker-native healthcheck against `/_healthcheck`. The HOCON config
-also reads `${?HTTP_PORT}` for `http.port`, so the listener and the
-healthcheck cannot drift apart. To run on a different port:
-
-```bash
-docker run -e HTTP_PORT=8080 -p 8080:8080 my-auth-provider
-```
-
-`EXPOSE` is image metadata and does not publish ports by itself, so the
-explicit `-p` mapping is still required.
-
-### Mailpit for the SMTP sender (development only)
-
-[`docker-compose.mailpit.yml`](docker-compose.mailpit.yml) is an overlay on
-`docker-compose.yml` that adds [Mailpit](https://mailpit.axllent.org/), a mail
-catcher, so a development run with MFA on sends its mail — the account-email
-proof, the email factor's codes — through the SMTP sender instead of the
-development sender, which only logs each code:
-
-```bash
-docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
-```
-
-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
-names a real relay with the `STANDARD_SMTP_MAIL_SENDER_*` variables
-([Multi-factor authentication](#multi-factor-authentication)).
-
-What the overlay sets on the app service:
-
-- `CONFIG_ENV=mailpit`. Under `development` the template installs the sender
-  that logs each code ([Module Composition Order](#module-composition-order),
-  rule 7). [`config/mailpit.conf`](config/mailpit.conf) 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`,
-  on the compose Redis, as `docker-compose.yml` sets them: under a name other
-  than `development` or `test` the MFA stores may not be kept in memory.
-- `STANDARD_SMTP_MAIL_SENDER_HOST=localhost`,
-  `STANDARD_SMTP_MAIL_SENDER_PORT=1025`, `STANDARD_SMTP_MAIL_SENDER_SECURE=none`
-  and `STANDARD_SMTP_MAIL_SENDER_FROM=auth@example.com`. The SMTP sender sends
-  in plaintext only to a loopback host, so Mailpit runs in the app container's
-  network namespace (`network_mode: service:app`) and listens on its
-  `localhost`; the app service therefore publishes Mailpit's web UI, on
-  loopback.
-
-It is an overlay rather than a compose profile because a profile only adds
-services: it cannot change the app service's environment or ports.
-
-### Health endpoints
-
-Two routes, answering two different questions. Both are mounted on the host
-app ahead of the auth router, so they keep answering while the auth pipeline
-is degraded.
-
-| Route | Question | Answer |
-|---|---|---|
-| `GET /_healthcheck` | Is the process up? | Always `200 {"status":"ok"}` |
-| `GET /readyz` | Can this replica serve right now? | `200 {"status":"ready", …}` or `503 {"status":"unready", …}` |
-
-Use them for different probes:
-
-```yaml
-livenessProbe:
-  httpGet: { path: /_healthcheck, port: 3000 }
-readinessProbe:
-  httpGet: { path: /readyz, port: 3000 }
-```
-
-Pointing liveness at `/readyz` is the mistake worth avoiding: a Redis
-partition would then look like a broken container and Kubernetes would
-restart every replica in a loop, which reconnects nothing and adds cold
-starts to an incident. Losing Redis is a reason to stop *routing* to a
-replica, not to kill it.
-
-The image's `HEALTHCHECK` probes `/_healthcheck` for the same reason. Docker
-has exactly one health signal, and on Swarm and ECS an unhealthy container is
-stopped and replaced — so wiring it to `/readyz` would reintroduce the restart
-loop for every non-Kubernetes orchestrator. If you want
-`depends_on: condition: service_healthy` to mean "ready" rather than "alive",
-override `healthcheck:` for that one service in your compose file instead of
-changing the image.
-
-`/readyz` runs one probe per backing connection and reports each by name:
-
-```json
-{
-  "status": "unready",
-  "checks": [
-    { "name": "redis", "ok": true, "durationMs": 2 },
-    { "name": "session-store", "ok": false, "durationMs": 1001 }
-  ]
-}
-```
-
-The failure's *reason* is deliberately absent from the body and goes to the log
-instead (`readiness_probe_failed`, with each failing check's error as core's
-`loggableError` projection). A driver
-error reads `connect ECONNREFUSED 10.0.3.14:6379` — an internal host and port —
-and this endpoint is unauthenticated because an orchestrator has no credentials
-to present. Set `includeErrorDetail: true` on `createReadinessRouter` only when
-the endpoint is reachable solely from inside the deployment.
-
-For the same reason, keep `/readyz` off the public listener. It sits ahead of
-the auth router, so it is outside that router's rate limiter, and each request
-issues one command per probe against the very dependency it reports on —
-enough for an anonymous request loop to add load during an incident. Bind it to
-the internal network, an admin listener, or your ingress' internal-only path
-rules.
-
-Probes are registered by whichever builder opened the connection, so the list
-reflects what this deployment actually wired: the shared ioredis client
-(`redis`) and the connect-redis session client (`session-store`) when the
-Redis adapters are selected, and **nothing at all** for a composition with no
-Redis-backed module — which would therefore always be ready, having no
-dependency to be unready for. The shipped composition is never that: its
-refresh-token families are always in Redis, so `redis` is always probed.
-
-`http.readinessTimeoutMs` (env `HTTP_READINESS_TIMEOUT_MS`, default `1000`)
-is the per-probe deadline. Keep it below the orchestrator's own probe timeout;
-otherwise an unreachable dependency reads as a slow replica rather than an
-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: `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 [
- 		sessionStoreModule,
- 		…
- 		...(federationGrantsEnabled || mfaInstalled ? [subjectRevocationServiceModule] : []),
-+		myCustomModule,
- 	];
-```
-
-Keep the other rules there too: the session store module stays first, and a module that fills a store slot replaces that slot's adapter switch rather than being added beside it. [`src/app.mts`](src/app.mts) needs no change: it passes `buildModules(config, …)` to `createApp`, mounts the router `createApp` returns, and wires the server's lifetime — `installGracefulShutdown` (below) drains it and calls `handle.dispose()`. The exception is a mail sender of your own: it goes in through the `mailSenderModules` override in that call (rule 7), not into the list, where it would collide with the bundled sender on the `mailSender` slot.
-
-A module that contributes a session requirement changes what "logged in" means, so its name goes in `core.sessionRequirements.expected`, which `config/application.conf` ships as `[]`. Boot compares the list with what the modules register. A name listed that nothing registers refuses the boot (`session-requirement-missing`), and so does a registered requirement the list leaves out (`session-requirements-undeclared`). When `MFA_MODE` installs MFA, the template adds `mfa` to the list (`expectedSessionRequirements`, [`src/configPath.mts`](src/configPath.mts)), keeping the names you wrote, and writes `core.sessionRequirements.secondFactorAuthority = "mfa"` beside it; a value of your own there other than `mfa` is refused before boot. The MFA module it installs registers `mfa` and declares the second-factor authority. Core refuses a declared authority whose requirement does not declare it (`second-factor-authority-not-declared`), a second requirement named `mfa`, and a second requirement declaring the authority (`duplicate-second-factor-authority`), so a module you add cannot stand in for it. Install MFA through `MFA_MODE`, not by adding its modules to the list: the template would install them a second time.
-
-### Shutdown guarantees
-
-`src/shutdown.mts` is deliberately part of the scaffold rather than a dependency (#290): for the component that terminates every user session, *"does SIGTERM wait for in-flight requests, and for how long?"* has to be answerable from the code you deploy.
-
-1. **`SIGTERM` and `SIGINT`** both start it. A second signal is ignored rather than starting a second dispose over the first one's stores.
-2. **New connections stop immediately**, and idle keep-alive sockets are released — they hold the server open with no request behind them, so a quiet server would otherwise wait out the whole deadline for nothing.
-3. **In-flight requests get `drainTimeoutMs`** (default **10s**) to finish.
-4. **Past the deadline the remaining connections are cut and the process exits non-zero.** An orchestrator that only ever sees `0` cannot tell a clean drain from one that ran out of time.
-5. **`cleanup` runs after draining, before exit** — `handle.dispose()`, i.e. reverse-topological component cleanup plus the Redis/timer drain. A failure there is logged through this service's own logger (NDJSON, like every other line) as `shutdown_cleanup_failed` (or `shutdown_cleanup_timed_out`) and reflected in the exit code; every stage is its own event (see the table below). A dispose that throws still exits; it never wedges the process. The line carries core's [`loggableError`](../../packages/core/README.md#logger) projection of the failure, never the error itself: `dispose()` rejects with an AggregateError of every cleanup's own error, and the line names each of them with its code (`aggregateErrors`, the first five) and nothing of what it holds — a store write that failed, with what it was writing, can be one of them.
-
-6. **`cleanup` gets at least the allowance the modules registered**: `handle.cleanupAllowanceMs`, the longest tail a module registered its cleanup with, which `src/app.mts` hands `installGracefulShutdown` as `cleanupAllowanceMs: () => handle.cleanupAllowanceMs`, read when the signal arrives; cleanup's budget is the longer of it and the drain's ten, and `shutdown_draining` logs it as `cleanupTimeoutMs`. An allowance that is not a whole number of milliseconds from 1 to 2147483647 is ignored. The template reads no module's settings to size it. With federation grants on, the package registers its drain's tail as `federation-grants.upstreamHardTimeoutMs` + `persistRetryBudgetMs` + `lockWaitMs` + 12 s, never below 45 s — exactly 45 s under the shipped budgets (25 + 3 + 5 + 12) — because the dispose waits for a rotated upstream credential's write. Raise a budget and the allowance grows with it; raise your orchestrator's grace to match. Off, nothing registers an allowance and the cleanup budget stays the drain's.
-
-Each stage logs one line:
-
-| Event | Level | Fields |
-|---|---|---|
-| `shutdown_draining` | info | `drainTimeoutMs`, `cleanupTimeoutMs` |
-| `shutdown_drain_deadline_exceeded` | error | `drainTimeoutMs` |
-| `shutdown_server_close_failed` | error | `err` |
-| `shutdown_cleanup_timed_out` | error | `cleanupTimeoutMs` |
-| `shutdown_cleanup_failed` | error | `err` |
-| `shutdown_complete` | info | `reason`, `drain`, `exitCode` |
-
-`err` is the `loggableError` projection. `drain` is how the drain ended: `drained`, `drain-timeout` or `close-failed` (a listener that did not come down is not a clean drain, and exits non-zero). `reason` is what decided `exitCode`: the drain's outcome, or `cleanup-timeout` / `cleanup-failed` when the cleanup then timed out or threw, so `reason: "drained"` never sits beside a non-zero code.
-
-**Size `drainTimeoutMs` and `cleanupTimeoutMs` together below your orchestrator's kill grace period.** Kubernetes `terminationGracePeriodSeconds` is 30s by default and compose's `stop_grace_period` is 10s; with federation grants on, the worst case is drain (10s) + cleanup (45s) = 55s, so **set the grace to 60s or more** — the shipped compose files do, and a Kubernetes deployment must set `terminationGracePeriodSeconds: 60` itself, or a rolling restart SIGKILLs the process in the middle of the write the cleanup exists to finish. The point is to close on your terms before `SIGKILL` arrives on someone else's.
-
-## npm Scripts
-
-| Script | Description |
-|---|---|
-| `pnpm run build` | Compile TypeScript to `dist/` |
-| `pnpm run start` | Start the compiled server |
-| `pnpm run debug` | Start with hot reload via `tsx watch` (development mode) |
-| `pnpm run test` | Typecheck (`tsc --noEmit`), then run the tests with Vitest |
-
-## See Also
-
-- [Operator runbook](../../docs/operator-runbook.md) — deployment shapes and boot refusals, probes, what each dependency failure looks like, events to alert on, Redis key families and failure timing, key rotation, upgrading and rollback
-- [`@o3co/auth-provider-core`](../../packages/core) — Application factory and config schema
-- [`@o3co/auth-provider-oauth`](../../packages/oauth) — OAuth module
-- [`@o3co/auth-provider-session`](../../packages/session) — Session module
-- [`@o3co/auth-provider-foundation`](../../packages/foundation) — Built-in adapter registration
-- [`@o3co/create-auth-provider`](../../create-app) — CLI scaffolder that generates this template
-
-## Observability
-
-### Logging
-
-The provider logs newline-delimited JSON on stdout via [pino](https://getpino.io),
-which is what a log aggregator ingests without a parser. `LOGGING_LEVEL` (HOCON
-`logging.level`, the `logging` module's section, read before boot with that
-module's schema) sets the threshold; `trace` and `debug` carry request-shaped
-detail and are off by default, and pino drops sub-threshold calls before
-formatting, so they cost nothing in production rather than being emitted and
-filtered downstream.
-
-The logger is wired into the boot planner's `logger` component slot, so every
-module that declares `optional: ["logger"]` — oauth, session, dpop, mtls,
-token-exchange — logs through this one instance. Filling that slot is what makes
-`LOGGING_LEVEL` reach them; a composition root that leaves it empty gets each
-module's own `consoleLogger` default instead, and configuring a level changes
-nothing.
-
-Events are structured and named: `logger.error({ err }, "session_store_redis_error")`.
-Alert on the name, not on the message text.
-
-To swap the backend, replace `createAppLogger` in `src/logger.mts`. Anything
-satisfying core's `Logger` works — the interface has pino's two-overload call
-shape, so a pino-compatible logger needs no adapter.
-
-### Audit trail
-
-Security-relevant events — who authenticated, what was issued, what was refused,
-and when the rate limiter could not answer — go to the sink named by
-`adapters.auditSink` (env `ADAPTERS_AUDIT_SINK`). The template ships `"logger"`, which
-writes one event per line through the same pino stream as everything else:
-
-```json
-{"level":30,"time":1787841564013,"name":"audit","audit":{"timestamp":"2026-08-27T14:39:24.013Z","type":"token.issued.failure","ip":"203.0.113.7","details":{"reason":"unsupported_grant_type"}},"msg":"token.issued.failure"}
-```
-
-One output style, so an aggregator ingests application logs and audit events
-through one parser and separates them on `name` (`"provider"` vs `"audit"`).
-The event type is also the message, so alert on the name — `authorize.rejected`,
-`token.issued.failure`, `rate_limit.unavailable` — the same way you would on
-`session_store_redis_error`.
-
-`ADAPTERS_AUDIT_SINK=console` selects core's built-in sink instead: the bare event
-as one JSON object per line, with no log envelope, for a pipeline that wants the
-event and nothing else.
-
-**`LOGGING_LEVEL` does not gate the audit trail.** The audit stream's level is fixed
-at `info`. `warn` is an ordinary production setting and `silent` a legitimate
-one, and either silencing this would delete the record of every authentication
-and issuance while looking like a logging preference. Where audit events go is
-chosen by `adapters.auditSink` — and that selector has **no `"none"`**. An unknown
-sink fails boot naming the sinks that are registered, rather than producing a
-deployment with no audit trail. A composition that installs no sink on purpose
-says so in core's own section, `core.declaredAbsent = ["auditSink"]`; this
-template always installs one.
-
-To point it at a real sink — SIEM, log pipeline, message bus — register a
-builder in `auditSinkModuleFor` (`src/modules.mts`) and select it; its options
-are the `audit-sink` module's section, under the sink's name:
-
-```ts
-factory.register("splunk-hec", (cfg) => createSplunkSink(cfg));
-```
-
-```hocon
-adapters.auditSink = "splunk-hec"
-audit-sink {
-  splunk-hec { endpoint = ${?SPLUNK_HEC_URL}, token = ${?SPLUNK_HEC_TOKEN} }
-}
-```
-
-To add an audit destination beside the configured one, contribute
-`auditHooks` from your own module; core fans out `auditSink` and `auditHooks`
-together.
-
-Sinks are fire-and-forget by contract: core dispatches without awaiting and
-swallows rejections, so a slow or failing sink cannot add latency to — or
-fail — an auth flow. The flip side is that a sink which cannot deliver drops
-the event. On its own a sink's failure is swallowed silently; once a module
-contributes `auditHooks`, the fan-out logs each failing call at error as
-`audit_sink_failed`, with the sink's position and the event's `type`. The
-drops are not counted yet — see **Not published yet** under Metrics below.
-
-### Metrics
-
-`GET /metrics` serves the Prometheus text exposition format.
-
-| Metric | Type | What it answers |
-|---|---|---|
-| `http_request_duration_seconds` | histogram | Request rate, error rate and latency, by `method` / `route` / `status` |
-| `auth_dependency_up` | gauge | Whether each backing dependency answered its readiness probe (`dependency="redis"`, `"session-store"`) |
-| `auth_provider_*` | various | Node process defaults — event-loop lag, heap, GC, handles |
-
-`auth_dependency_up` is the series that separates "Redis is gone" from "the app
-is slow", which is otherwise only distinguishable by grepping container logs. It
-reuses the probes the adapter builders already registered, so it reflects what
-this deployment actually wired rather than a second, drifting list. Dependencies
-are re-sampled on every scrape — a cached verdict would report healthy for
-exactly as long as an incident lasts — and in-flight probes are joined rather
-than re-issued, so a scrape loop does not stack commands on a dependency that is
-already in trouble.
-
-Route labels use the Express route **pattern** (`/oauth/token`,
-`/api/widgets/:id`), never the URL, and unmatched requests collapse to
-`route="unmatched"`. Labelling by path would mint a series per distinct URL, and
-this server's paths carry opaque values — that is how a metrics endpoint takes
-down the monitoring that was supposed to watch it.
-
-A scrape example:
-
-```yaml
-scrape_configs:
-  - job_name: auth-provider
-    static_configs:
-      - targets: ["auth-provider:3000"]
-```
-
-Keep `/metrics` off the public listener, for the same reason as `/readyz`: it is
-unauthenticated, it sits ahead of the auth router and so outside its rate
-limiter, and each scrape samples the readiness probes.
-
-**Not published yet:** rate-limiter fail-closed counts and audit-sink drops.
-Both happen inside `@o3co/auth-provider-core` and are not observable from the
-composition root; counting them needs a metrics hook in core rather than
-something this template can reach. Until then, alert on the
-`rate_limiter_failed_closed` and `rate_limit.unavailable` log events.