@o3co/create-auth-provider 0.9.0 → 0.11.0

package/templates/standalone/README.md

@@ -4,15 +4,58 @@ Deployable server template for auth.provider. This is the composition root — i
 
 ## Requirements
 
-- **Node.js** `>=18.19.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` is set in this template's `package.json` so a fresh `pnpm install` does not silently skip the install hook on those platforms.
+- **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** `^5.4.1` (direct runtime dependency, used by the refresh-token-family client). Other Redis-backed adapters in this template still use the `redis` npm package; ioredis is added for the RT family store specifically.
 
+## First-party clients
+
+`GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
+
+That is a coherent model for a **first-party** OP — one where every registered client is operated by you — and it is coherent nowhere else. A page you do not control can force a top-level navigation to `/authorize?client_id=X&redirect_uri=...&code_challenge=<theirs>`, a logged-in user's browser mints a code bound to *their* session, it is delivered to X's registered `redirect_uri`, and whoever chose the `code_challenge` redeems it for tokens carrying that user's identity.
+
+So the assumption is enforced rather than assumed. A client must carry `firstParty: true` in its registration to use `/authorize`; anything else is refused with `unauthorized_client`. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
+
+```yaml
+# config/clients.yaml
+my-app:
+  tokenEndpointAuthMethod: "client_secret_basic"
+  firstParty: true
+  allowedRedirectUris: ["https://app.example/callback"]
+```
+
+**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident. The step that changes the former is a consent screen, tracked separately.
+
+**Migrating.** Registrations that predate the field are refused at `/authorize` until you mark them — a client with no `firstParty` field and one carrying an explicit `false` are treated alike. Mark every client you operate before pointing it at `/authorize`; there is no admit-with-warning window. The one-time `oauth.authorize.allowUnmarkedClients` migration flag was removed before it ever shipped in a release, and a config or environment still setting it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
+
 ## Multi-replica deployments
 
 When running multiple instances of the standalone server behind a load balancer, point `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
 
+**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`.
+
+Since #292 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 `rateLimiter.adapter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. Since #270 the login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `rateLimit.login`; both adapters seed their own `limits.login` from it, so there is nothing to restate.
+
+**Set `DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, DPoP proof-replay detection forking. With the mode unset you get one `replica_unsafe_adapters` warning at boot instead; with `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica.
+
+Be aware of what this check *cannot* do: if you scale to N replicas without ever setting `DEPLOYMENT_MODE`, nothing fails. A process holding all its state in its own memory has no shared medium through which to notice peers — the condition is undetectable from inside exactly when it is true. Set the variable as part of scaling, not after something breaks.
+
+**Access-token revocation needs a denylist, and the template ships one.** `POST /oauth/revoke` revokes an access token by writing its `jti` to the `accessTokenDenylist`, which token verification and introspection consult. Boot *fails* if the endpoint is mounted with no denylist behind it: RFC 7009 obliges the endpoint to answer `200`, so an unwired denylist would tell you a token is revoked while it keeps working until it expires. `accessTokenDenylist.adapter` defaults to `"redis"` here (`ACCESS_TOKEN_DENYLIST_ADAPTER=memory` for single-instance local work) and shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`, so it costs no extra connection. A deployment that genuinely does not revoke access tokens sets `OAUTH_REVOCATION_ACCESS_TOKEN=unsupported` instead; the endpoint then answers `unsupported_token_type` for `token_type_hint=access_token`. **Refresh-token revocation works in either case and never needed a denylist.**
+
 Other multi-replica considerations covered by the default modules:
 
 - The session store is wired via `redisSessionStoresModule`; set the corresponding session-store Redis URL (per `session.storage.redis.url`).
@@ -59,27 +102,55 @@ fail fast rather than silently falling back to defaults.
 | Variable | Default | Description |
 |---|---|---|
 | `HTTP_PORT` | `3000` | Port the server listens on |
-| `HTTP_TRUST_PROXY` | `false` | Set to `true` when running behind a reverse proxy |
+| `HTTP_TRUST_PROXY` | `false` | Express `trust proxy`: `false`, an address/CIDR list (`10.0.0.0/8,loopback`), a hop count (`1`), or `true`. **Required behind a load balancer** — otherwise every IP-keyed rate limit shares one bucket across all users. Prefer naming the proxy over `true`. See [Multi-replica deployments](#multi-replica-deployments) |
+| `HTTP_READINESS_TIMEOUT_MS` | `1000` | Per-probe deadline for `/readyz` (see [Health endpoints](#health-endpoints)) |
+| `LOG_LEVEL` | `info` | Minimum level emitted: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`. Does **not** gate the audit trail — see [Audit trail](#audit-trail) |
+| `AUDIT_SINK_TYPE` | `logger` | Where security events go: `logger` (pino-enveloped NDJSON on stdout) or `console` (bare event JSON). There is no `none`. See [Audit trail](#audit-trail) |
 
 ### OAuth JWT
 
 | Variable | Default | Description |
 |---|---|---|
-| `OAUTH_JWT_ALGORITHM` | `HS256` | JWT signing algorithm (e.g. `RS256`, `ES256`) |
-| `OAUTH_JWT_SECRET` | — | Signing secret (HMAC algorithms) |
-| `OAUTH_JWT_ISSUER` | — | JWT `iss` claim value |
+| `OAUTH_JWT_ALGORITHM` | `EdDSA` | JWT signing algorithm: `EdDSA`, `ES256`, `RS256` or `HS256`. The default is asymmetric so `/.well-known/jwks.json` publishes a real verification key. |
+| `OAUTH_JWT_SECRET` | — | Signing secret, **HMAC (`HS256`) only**. At least 32 bytes (256 bits) of random material — `openssl rand -hex 32`. Hex/base64 values are measured **decoded**, so a 32-character hex string counts as 16 bytes and is refused. |
+| `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_JWT_KID` | `v0` | Key ID included in the JWT header |
 | `OAUTH_JWT_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
 | `OAUTH_JWT_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
 | `OAUTH_JWT_PUBLIC_KEY` | — | PEM-encoded public key |
 | `OAUTH_JWT_PUBLIC_KEY_PATH` | — | Path to PEM public key file |
+| `OAUTH_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. |
+
+**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 `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH` at them
+(or inline the PEMs via `OAUTH_JWT_PRIVATE_KEY` / `OAUTH_JWT_PUBLIC_KEY`).
+
+`HS256` is still selectable (`OAUTH_JWT_ALGORITHM=HS256` plus a ≥32-byte
+`OAUTH_JWT_SECRET`), but understand what it costs: a symmetric key has no
+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_EXPIRES_IN` | `3600` | Access token lifetime in seconds |
-| `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | Refresh token lifetime in seconds |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | `3600` | Access token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
+| `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | Refresh token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
+
+Exporting one of these as an empty string is a boot failure, not a fallback:
+HOCON resolves `FOO=` to `""`, which coerces to `0`, and a zero lifetime mints
+tokens that have already expired.
 
 ### Grant Types
 
@@ -93,12 +164,13 @@ fail fast rather than silently falling back to defaults.
 
 | Variable | Default | Description |
 |---|---|---|
-| `SESSION_SECRET` | — | **Required.** Session signing secret |
+| `SESSION_SECRET` | — | **Required.** Signs the cookie that *is* the authenticated session, so guessing it forges logins. At least 32 bytes (256 bits) — `openssl rand -hex 32`. Measured **decoded**, same rule as `OAUTH_JWT_SECRET`. |
 | `SESSION_NAME` | `__Host-auth.session` | Session cookie name. The default uses the `__Host-` prefix and therefore requires `SESSION_SECURE=true` and no `SESSION_DOMAIN`. |
-| `SESSION_MAX_AGE` | `3600000` | Session cookie max age in milliseconds |
+| `SESSION_MAX_AGE` | `3600000` | Session cookie max age in milliseconds. Whole positive number, at most one year (`31536000000`). |
 | `SESSION_SECURE` | `true` | Set `Secure` flag on session cookie |
-| `SESSION_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`) |
+| `SESSION_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`). `none` **requires** `SESSION_SECURE=true` — browsers drop a `SameSite=None` cookie that is not `Secure`, so boot refuses the combination rather than letting every login fail silently in the client. |
 | `SESSION_DOMAIN` | — | Cookie domain (unset by default) |
+| `SESSION_CSRF_TTL_SECONDS` | `7200` | Lifetime of an issued CSRF token, in seconds. Integer, 1–86400; boot fails otherwise (an *empty* value coerces to `0` and would silently disable the token arm). |
 | `SESSION_STORAGE_TYPE` | `redis` | Session store backend: `redis` or `memory` |
 | `SESSION_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
 | `SESSION_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
@@ -108,6 +180,25 @@ for shared-domain cookies, also set `SESSION_NAME` to a non-`__Host-` value such
 `auth.sid`. The server fails fast when a `__Host-` cookie name is combined with
 attributes that browsers reject for that prefix.
 
+#### 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_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.
+  `cors.allowedOrigins` no longer confers CSRF trust.
+
 ### Google Federation
 
 | Variable | Default | Description |
@@ -129,9 +220,19 @@ attributes that browsers reject for that prefix.
 | Variable | Default | Description |
 |---|---|---|
 | `CLIENT_USER_TYPE` | `http` | User repository backend: `http` |
-| `CLIENT_USER_AUTHENTICATE_URL` | — | URL for password-based user authentication |
-| `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication |
-| `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds |
+| `CLIENT_USER_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
+| `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
+| `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
+| `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
+
+Both user-authentication URLs carry **plaintext user credentials** to the
+upstream store, so both must be absolute `https://` URLs. `http://` is accepted
+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.
 
 ### Code Repository
 
@@ -160,9 +261,12 @@ Use values that include the deployment name, for example `tenant-a:ss:`,
 
 | Variable | Default | Description |
 |---|---|---|
-| `ENDPOINTS_LOGIN_URL` | — | URL of the login page (for redirects) |
-| `ENDPOINTS_CLIENT_URL` | — | URL of the client application |
-| `ENDPOINTS_AUTH_CALLBACK_URL` | — | URL of the authorization callback |
+| `ENDPOINTS_LOGIN_URL` | `/login` | URL of the login page (for redirects) |
+
+`ENDPOINTS_CLIENT_URL` and `ENDPOINTS_AUTH_CALLBACK_URL` were removed (IH-10) —
+no production consumer read them, and the config lines leaked values into
+`AppConfig` that nothing consumed. Federation callback URLs are configured
+per-provider (`FEDERATIONS_GOOGLE_CALLBACK_URL`).
 
 ## Module Composition Order
 
@@ -205,6 +309,37 @@ make test
 
 The `docker-compose.yml` starts the auth server together with a Redis container. Configure environment variables in `.env`.
 
+`docker-compose.yml` is a **development** file: it builds the `develop` target and bind-mounts `./src` and `./config`, so deploying it ships a hot-reload server running your working tree. The deployable shape is
+[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target, no source mounts, restart policies, a network-internal persistent Redis, and a **required** `.env` (a boot without a real `SESSION_SECRET` must fail loudly). Its header comments state what it deliberately leaves to you: TLS termination in front plus `HTTP_TRUST_PROXY`, and the [multi-replica](#multi-replica-deployments) steps before any `--scale`.
+
+```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
+
+docker compose -f docker-compose.production.yml up -d --build
+```
+
+**Keys in containers.** The pem pair reaches the container as a compose
+**secret**, mounted read-only at `/run/secrets/`, and the compose file points
+`OAUTH_JWT_*_KEY_PATH` there. Do not park them in `config/`: the `Dockerfile`
+`COPY`s that directory, so a key placed there is baked into an image layer and
+travels with every push — a key you then have to rotate rather than one you
+merely stored badly. The same applies to `.env`; keep both out of git.
+
+The production file also pins `SESSION_SECURE=true` and the `__Host-` cookie
+name in its `environment:` block, which wins over `env_file`. `.env.example`
+ships `SESSION_SECURE=false` so a plain-HTTP local run works, and this file
+requires that same `.env` — behind the TLS it assumes, a non-Secure session
+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 `app.listen()` and the
@@ -217,6 +352,78 @@ 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.
 
+### 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 the full per-check detail). 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 memory-only
+deployment — which is therefore always ready, because it has no dependency to
+be unready for.
+
+`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 include it in the `modules` array passed to `createApp`:
@@ -253,9 +460,21 @@ const handle = await createApp({
 
 app.use(handle.router);
 const server = app.listen(config.http.port);
-gracefulShutdown(server, () => handle.dispose());
+installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 ```
 
+### 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) and reflected in the exit code. A dispose that throws still exits; it never wedges the process.
+
+**Size `drainTimeoutMs` below your orchestrator's kill grace period** — Kubernetes `terminationGracePeriodSeconds` and compose `stop_grace_period` are both 30s by default. The point is to close on your terms before `SIGKILL` arrives on someone else's.
+
 ## npm Scripts
 
 | Script | Description |
@@ -272,3 +491,124 @@ gracefulShutdown(server, () => handle.dispose());
 - [`@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. `LOG_LEVEL` (HOCON
+`logging.level`) 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
+`LOG_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
+`audit.sink.type` (env `AUDIT_SINK_TYPE`). 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`.
+
+`AUDIT_SINK_TYPE=console` selects core's built-in sink instead: the bare event
+as one JSON object per line, with no log envelope, for a pipeline that wants the
+event and nothing else.
+
+**`LOG_LEVEL` does not gate the audit trail.** The audit stream's level is fixed
+at `info`. `warn` is an ordinary production setting and `silent` a legitimate
+one, and either silencing this would delete the record of every authentication
+and issuance while looking like a logging preference. Where audit events go is
+chosen by `audit.sink.type` — and that selector has **no `"none"`**. An unknown
+type fails boot naming the sinks that are registered, rather than producing a
+deployment with no audit trail.
+
+To point it at a real sink — SIEM, log pipeline, message bus — register a
+builder in `auditSinkModule` (`src/modules.mts`) and name it in config; its
+options ride along in the same block:
+
+```ts
+factory.register("splunk-hec", (cfg) => createSplunkSink(cfg));
+```
+
+```hocon
+audit {
+  sink {
+    type = "splunk-hec"
+    splunk-hec { endpoint = ${?SPLUNK_HEC_URL}, token = ${?SPLUNK_HEC_TOKEN} }
+  }
+}
+```
+
+Sinks are fire-and-forget by contract: core dispatches without awaiting and
+swallows rejections, so a slow or failing sink cannot add latency to — or
+fail — an auth flow. The flip side is that a sink which cannot deliver drops
+events silently, and those drops are not counted yet — see **Not published
+yet** under Metrics below.
+
+### 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.