@o3co/create-auth-provider 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",

package/templates/standalone/.env.example

@@ -40,6 +40,19 @@ SESSION_SECRET=
 CLIENT_USER_AUTHENTICATE_URL=
 CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
 
+# --- Reverse proxy (required in production) -----------------------------------
+# Express `trust proxy`. Set this to the address or CIDR range of whatever
+# terminates TLS in front of this service — `10.0.0.0/8`, or `loopback` for a
+# sidecar on the same host. Comma-separate several.
+#
+# Prefer naming the hop over `true`: `true` believes a forwarded client address
+# from anyone who can reach this process, and with it any rate-limit identity.
+# Left EMPTY here because it cannot be guessed; `docker-compose.production.yml`
+# refuses to start until it is set, since without it the Secure cookie is never
+# set, the CSRF origin check 403s every browser POST, and every IP-keyed rate
+# limit shares one bucket. A plain-HTTP local run needs nothing here.
+HTTP_TRUST_PROXY=
+
 # Redis (code repository + session storage + the shared client socket)
 # Use redis://redis:6379 when running via docker compose
 CLIENT_CODE_ENDPOINT_URI=redis://redis:6379

package/templates/standalone/README.ja.md

@@ -115,7 +115,15 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 設定上の注意が 2 点:
 
 - TLS 終端プロキシの背後では `HTTP_TRUST_PROXY` にそのプロキシのアドレス／CIDR を設定する (例: `HTTP_TRUST_PROXY=10.0.0.0/8`)。設定しないと `req.protocol` は `http` のままでブラウザは `Origin: https://…` を送るため、origin 側の判定が全リクエストを拒否する。`true` は「プロキシ以外が絶対にプロセスへ到達できない」と言い切れる場合にのみ正しい (#292) — 英語版 README も同じ指針。
-- ログイン UI をプロバイダーと**別 origin** で配信している場合は、その origin を HOCON の `session.csrf.trustedOrigins` に列挙する。`cors.allowedOrigins` は CSRF 信頼を与えなくなった。
+- ログイン UI をプロバイダーと**別 origin** で配信している場合は、その origin を HOCON の `session.csrf.trustedOrigins` に列挙する。`cors.allowedOrigins` は CSRF 信頼を与えない。
+
+### CORS（#500）
+
+ブラウザーアプリをプロバイダーと別 origin で配信している場合、その origin を `cors.allowedOrigins`（環境変数は `CORS_ALLOWED_ORIGINS`、カンマ区切り）に列挙しないと、SPA は token エンドポイントを呼べない。有効になるのは `/oauth/token`、`/oauth/userinfo`、`/oauth/revoke`、discovery、JWKS の 5 つだけで、`/oauth/introspect`（サーバー間通信）と `/oauth/authorize`（トップレベル遷移）は意図的に対象外。
+
+`Origin` ヘッダーとの**完全一致**なので、末尾スラッシュ・明示的な `:443`・パス・大文字ホスト・ワイルドカードはいずれも起動時に失敗する（一致しない許可リストが黙って居座るのを防ぐため）。ループバックホストを除き https が必須。
+
+`Access-Control-Allow-Credentials` は**決して送らない** — ここでのクロスオリジン SPA は PKCE を使う public client であり cookie は不要で、cookie を渡せば `session` grant に届いてしまう。空リスト（既定）なら CORS は無効で、middleware 自体がマウントされない。詳細は英語版 README の [CORS](README.md#cors) を参照。
 
 ### Google フェデレーション
 

package/templates/standalone/README.md

@@ -7,7 +7,7 @@ Deployable server template for auth.provider. This is the composition root — i
 - **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.
+- **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 user-session stores, the federation-token store — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica (`makeIoredisClients`). The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
 
 ## First-party clients
 
@@ -31,6 +31,8 @@ my-app:
 
 ## Multi-replica deployments
 
+The [operator runbook](../../docs/operator-runbook.md) covers the operational side end to end — boot refusals, probes, dependency failures, alerts, Redis sizing, key rotation. This section is the multi-replica checklist.
+
 When running multiple instances of the standalone server behind a load balancer, point `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
 
 **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`.
@@ -50,7 +52,50 @@ An allowlist is a network control, not a cryptographic one. The edge must also *
 
 **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.
+**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 } }`, keyed by the endpoint prefix:
+
+```hocon
+redisRateLimiter {
+  limits {
+    token     { limit = 600, windowSeconds = 60 }
+    introspect { limit = 600, windowSeconds = 60 }
+  }
+}
+```
+
+(`memoryRateLimiter.limits` for the memory adapter, same shape.) Size it from
+your BFF's peak sign-ins and refreshes per minute with headroom, and remember
+that under `rateLimiter.adapter = "redis"` the budget is shared across replicas
+— 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 `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. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too; before #455 they booted under `multi`. Since #474 that includes express-session's own store under `SESSION_STORAGE_TYPE=memory` and the login / WebAuthn-options rate limiters when no shared `rateLimiter` is wired; with the mode unset those three warn instead (see the operator runbook). 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.
 
@@ -58,9 +103,10 @@ Be aware of what this check *cannot* do: if you scale to N replicas without ever
 
 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`).
-- The code repository defaults to Redis when `repositories.code.type = "redis"`; set `CLIENT_CODE_ENDPOINT_URI` to a shared Redis instance.
-- The federation token store can be backed by Redis via `federationTokenStore.type = "redis"` (deferred to operator config; default is in-memory).
+- The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORAGE_TYPE=redis` with `SESSION_STORAGE_REDIS_URL` (`session.storage.redis.url`) pointing at the shared instance.
+- The user-session stores switch on `userSessionStores.adapter = "redis"` (`USER_SESSION_STORES_ADAPTER`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` configures.
+- The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. The older `repositories.code.type = "redis"` (`CLIENT_CODE_TYPE`) switch is still honoured with a deprecation warning at boot. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is still bound by `config/application.conf` but nothing reads it: the Redis code repository has run on the shared connection since the `{ endpointUri }` builder shape was retired, so there is one Redis URL for every adapter and that variable is legacy.
+- The federation token store defaults to memory. Set `FEDERATION_TOKEN_STORE_TYPE=redis` (`federationTokenStore.type = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`. See [Federation Token Store](#federation-token-store).
 
 ## Usage
 
@@ -171,7 +217,7 @@ tokens that have already expired.
 | `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_TYPE` | `redis` | Session store backend: `redis` or `memory`. `memory` is per process and is refused under `DEPLOYMENT_MODE=multi` like the other in-memory stores (#474) |
 | `SESSION_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
 | `SESSION_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
 
@@ -197,7 +243,64 @@ Two configuration notes:
   request.
 - If your login UI is served from a **different origin** than the provider,
   list that origin under `session.csrf.trustedOrigins` in your HOCON config.
-  `cors.allowedOrigins` no longer confers CSRF trust.
+  `cors.allowedOrigins` does not confer CSRF trust — see
+  [CORS](#cors) for what it does confer.
+
+### CORS
+
+| Variable | Default | Description |
+|---|---|---|
+| `CORS_ALLOWED_ORIGINS` | *(empty — CORS off)* | Comma-separated list of browser origins allowed to read the token, userinfo, revocation and discovery/JWKS responses |
+
+A browser app served from a different origin than this provider — an SPA on
+`https://app.example.com` against a provider on `https://auth.example.com` —
+cannot call the token endpoint at all unless that origin is on
+`cors.allowedOrigins`. Set it and the provider answers preflights and stamps
+`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 `oauth.jwt.jwksPath` 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
+cors {
+  allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
+}
+```
+
+or `CORS_ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173`.
+
+**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
 
@@ -238,11 +341,29 @@ or the response cap is unusable, rather than at the first login attempt.
 
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_CODE_TYPE` | `redis` | Authorization code store backend: `redis` |
-| `CLIENT_CODE_ENDPOINT_URI` | — | Redis connection URI for code storage |
+| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); honoured with a boot warning |
+| `CLIENT_CODE_ENDPOINT_URI` | — | Legacy; bound to `repositories.code.redis.endpointUri` but not read — codes use the shared `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` connection |
 | `CLIENT_CODE_PASSWORD` | — | Redis password for code storage |
 | `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | Default authorization code lifetime in seconds |
 
+### Federation Token Store
+
+The upstream IdP tokens (a Google refresh token, say) held on behalf of a
+session. Memory by default, which forks per replica and is refused under
+`DEPLOYMENT_MODE=multi`; the Redis store shares the socket configured by
+`REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` and encrypts records at rest, so it
+needs a key.
+
+| Variable | Default | Description |
+|---|---|---|
+| `FEDERATION_TOKEN_STORE_TYPE` | `memory` | Federation token store backend: `memory` or `redis` |
+| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` | — | AES-256-GCM key for records at rest: 32 bytes, base64-encoded (`openssl rand -base64 32`). **Required** with `redis` unless the mode below is `allow-plaintext` |
+| `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused when the config was selected by a production/staging environment (`CONFIG_ENV` or `NODE_ENV`) and under `DEPLOYMENT_MODE=multi` in any environment, unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` is also set — development only |
+
+`ttl` (seconds; keep it above the upstream refresh-token lifetime) and the #291
+`scanFallback` migration flag live under `redisFederationTokenStore` in a
+config layer rather than behind an environment variable.
+
 ### Redis Namespacing
 
 For multi-tenant Redis clusters, set deployment-specific key prefixes so two
@@ -253,9 +374,10 @@ auth.provider instances cannot collide in the same database:
 | `REDIS_SESSION_STORES_KEY_PREFIX` | `ss:` | Outer prefix for user sessions, RP registry, session-family index, and session-federation index. |
 | `REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
 | `CLIENT_CODE_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
+| `REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX` | `ft:` | Prefix for federation token records, their per-session index and their lock keys. |
 
 Use values that include the deployment name, for example `tenant-a:ss:`,
-`tenant-a:rtfam:`, and `tenant-a:code:`.
+`tenant-a:rtfam:`, `tenant-a:code:`, and `tenant-a:ft:`.
 
 ### Endpoints
 
@@ -270,21 +392,36 @@ per-provider (`FEDERATIONS_GOOGLE_CALLBACK_URL`).
 
 ## Module Composition Order
 
-Modules are registered in the following order. Each module registers its own routes and grant types.
-
-1. **`oauthModule`** — Core OAuth 2.0 endpoints: `POST /oauth/token`, `POST /oauth/introspect`, `GET /oauth/authorize`
-2. **`sessionModule`** — Session-based login/logout and federation: `POST /session/login`, `POST /session/logout`, `GET/POST /session/oauth/federation/*`
-3. **`oauthSessionModule`** — Session grant type (exchanges a valid session for a token)
-4. **`oauthAuthorizationModule`** — Authorization code and refresh token grant types
+`src/buildModules.mts` is the single source of truth for the manifest; this is its order. The boot planner resolves `requires` / `provides` topologically, so list position matters only where a module says so — `sessionStoreModule` must stay first, because it wires the `express-session` middleware every session-consuming route needs. Entries marked *adapter switch* are one of a memory/Redis pair, chosen by config; both provide the same slot, so exactly one is wired.
+
+1. **`sessionStoreModule`** (`@o3co/auth-provider-session`) — `express-session` middleware and its store (`session.storage.type`)
+2. **`oauthModule`** — `POST /oauth/token`, `POST /oauth/introspect`, `POST /oauth/revoke`, `GET /oauth/authorize`, and OIDC discovery when an issuer is configured
+3. **`oauthSessionModule`** — session grant (exchanges an authenticated session for a token)
+4. **`oauthAuthorizationModule`** — authorization-code and refresh-token grants
+5. **`jwksModule`** (`@o3co/auth-provider-core`) — `GET /.well-known/jwks.json` (or `oauth.jwt.jwksPath`); a signing provider publishes its verification keys whether or not an issuer is set
+6. **`sessionModule`** — `POST /session/login`, `POST /session/logout`, `GET/POST /session/oauth/federation/*`. `/session/logout` deletes the `UserSession` record (so `/oauth/introspect` and `/oauth/userinfo` stop honouring tokens minted from that session), the subject index and the federation entries — but it does **not** revoke refresh-token families; `POST /oauth/logout` is the endpoint that runs the full cascade. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
+7. **`googleFederationModule`** + **`googleFederationConfigModule`** — only when `federations.google.enabled = true`
+8. **`keyStoreModule`** — the signing key store from `oauth.jwt.signingKey`
+9. **`repositoriesModule`** — client and user repositories from `repositories.client` / `repositories.user`
+10. **`auditSinkModule`** — always wired; `audit.sink.type` picks `logger` (default) or `console`
+11. **`standaloneRedisClientsModule`** — the one shared ioredis connection; present whenever any switch below is `"redis"`
+12. **`redisFederationTokenStoreModule`** / **`inMemoryFederationTokenStoreModule`** — *adapter switch*: upstream federation tokens per session (`federationTokenStore.type`; see [Multi-replica deployments](#multi-replica-deployments))
+13. **`redisSessionStoresModule`** / **`inMemorySessionStoresModule`** — *adapter switch*: user-session stores (`userSessionStores.adapter`)
+14. **`redisRateLimiterModule`** / **`memoryRateLimiterModule`** — *adapter switch*: the rate limiter behind the OAuth endpoints and `POST /session/login` (`rateLimiter.adapter`)
+15. **`redisCodeRepositoryModule`** / **`inMemoryCodeRepositoryModule`** — *adapter switch*: authorization codes (`oauth.code.adapter`)
+16. **`redisAccessTokenDenylistModule`** / **`memoryAccessTokenDenylistModule`** — *adapter switch*: RFC 7009 access-token denylist (`accessTokenDenylist.adapter`)
+17. **`redisRefreshTokenFamilyStoreModule`** — refresh-token families; Redis unless a test override swaps in the memory store
+18. **`defaultRefreshTokenFamilyRotationModule`**, **`defaultRefreshTokenFamilyRevocationModule`** — rotation and revocation policies over the family store
 
 ## Built-in Routes
 
-The following routes are registered outside of the module system:
+`src/app.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. The JWKS route is not one of them: `jwksModule` contributes it (see above).
 
 | Method | Path | Description |
 |---|---|---|
-| `GET` | `/health` | Health check endpoint |
-| `GET` | `/.well-known/jwks.json` | Public key set (JWKS) for token verification |
+| `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
 
@@ -310,7 +447,11 @@ 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`.
+[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target, no source mounts, restart policies, a network-internal persistent Redis, and a **required** `.env` (a boot without a real `SESSION_SECRET` must fail loudly). Its header comments state what it deliberately leaves to you: TLS termination in front, and the [multi-replica](#multi-replica-deployments) steps before any `--scale`.
+
+`HTTP_TRUST_PROXY` is an explicit `${HTTP_TRUST_PROXY:?…}` entry there, so `docker compose up` **refuses to start** until you name the hop in `.env`. That is deliberate: there is no address the file could default to that would not silently trust a hop you never chose, and without the variable the Secure cookie the file pins is never set, the CSRF origin check 403s every browser POST, and every IP-keyed rate limit shares one bucket.
+
+Every store whose records must outlive one process is named in that file's `environment:` block rather than inherited — including `USER_SESSION_STORES_ADAPTER=redis`, which has to travel with `SESSION_STORAGE_TYPE=redis`. `DEPLOYMENT_MODE=single` will not tell you when it does not: the replica guard answers "can these stores be shared", not "do these two stores have the same lifetime". Split them and a restart leaves every browser holding a surviving express-session that still reads `isAuthenticated` with no `UserSession` behind it — `/authorize` bounces to login, the cookie bounces it back, and the loop clears only when the user deletes the cookie.
 
 ```bash
 # The signing keys are a required input: EdDSA is the default and there is no
@@ -486,6 +627,7 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 
 ## 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

package/templates/standalone/config/application.conf

@@ -291,8 +291,25 @@ endpoints {
   # production consumer reads them.
 }
 
+# #500: browser origins allowed to read the token, userinfo, revocation and
+# discovery/JWKS responses. Empty (the default) means CORS is off -- leave it
+# alone unless a browser app is served from a different origin than this
+# provider. See the library reference.conf for the full rules; the short
+# version is that matching is EXACT, so each entry is a bare origin with no
+# trailing slash, no path and no wildcard, and https is required off loopback.
+#
+#   allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
+#
+# The env-override line is repeated at this layer for the HOCON precedence
+# reason the oauth.grants block above explains: application.conf wins over
+# reference.conf, so without it CORS_ALLOWED_ORIGINS could not take effect.
+# It takes a comma-separated list.
+#
+# Not to be confused with `session.csrf.trustedOrigins`, which answers the
+# other question (#272).
 cors {
   allowedOrigins = []
+  allowedOrigins = ${?CORS_ALLOWED_ORIGINS}
 }
 
 # D-2 v2 + Wave 5d: ioredis connection-config consumed by the shared

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

@@ -19,10 +19,11 @@
 #
 # What this file deliberately does NOT do:
 #
-# - **TLS.** Terminate it in front (reverse proxy / load balancer), and set
-#   HTTP_TRUST_PROXY to that hop's address so `req.ip` — and every IP-keyed
-#   rate limit — means the client, not the proxy. See README
-#   "Multi-replica deployments".
+# - **TLS.** Terminate it in front (reverse proxy / load balancer). The
+#   HTTP_TRUST_PROXY entry below then needs that hop's address so `req.ip` —
+#   and every IP-keyed rate limit — means the client, not the proxy; compose
+#   refuses to start until you supply it. See README "Multi-replica
+#   deployments".
 # - **Scale out.** This is one replica (DEPLOYMENT_MODE=single). Before
 #   `--scale app=N`, set DEPLOYMENT_MODE=multi and read that same README
 #   section — boot will then refuse any in-memory store that must be shared.
@@ -74,7 +75,31 @@ services:
       - jwt_public_key
     environment:
       NODE_ENV: production
+      # One replica. Under `single` the replica-safety guard is SILENT by
+      # design — you have told it there are no peers — so it will not tell you
+      # that a store below is on memory while its sibling is on Redis. That is
+      # why the adapter block further down states every one of them explicitly
+      # instead of leaving them to inherit. Before `--scale app=N`, set `multi`
+      # and read the README's "Multi-replica deployments".
       DEPLOYMENT_MODE: single
+      # Behind the TLS terminator this file assumes, `req.ip` is the proxy's
+      # address and `req.protocol` reads `http` until this names the hop. The
+      # README calls it required for exactly that reason, and the cost of
+      # leaving it unset is three failures at once: the Secure cookie pinned
+      # below is never set, the CSRF origin check 403s every browser POST
+      # (the browser sends `Origin: https://…`, the process believes it is
+      # serving http), and every IP-keyed rate limit — the OAuth endpoint
+      # limiters and the /session/login brute-force guard — shares ONE bucket
+      # across all users.
+      #
+      # It cannot be guessed and it is not defaulted: only you know what sits
+      # in front, and a default here would silently trust a hop you never
+      # chose. Put your edge's address or CIDR range in `.env` — `10.0.0.0/8`,
+      # or `loopback` for a sidecar on this host. Prefer that over `true`,
+      # which believes a forwarded client address from anyone able to reach
+      # this process. The `:?` form makes compose refuse to start until it is
+      # set, rather than starting wrong.
+      HTTP_TRUST_PROXY: ${HTTP_TRUST_PROXY:?set to your TLS terminator's address or CIDR range (e.g. 10.0.0.0/8, or `loopback` for a same-host sidecar) — never `true` behind an open network}
       # Point the process at the mounted secrets rather than the working-copy
       # paths `.env` carries for local runs.
       OAUTH_JWT_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
@@ -89,12 +114,46 @@ services:
       SESSION_SECURE: "true"
       SESSION_NAME: __Host-auth.session
       # Every Redis-backed store shares the compose-network Redis below.
+      #
+      # These are stated in full rather than inherited from
+      # `config/application.conf`, so that the deployable file names its own
+      # topology: an operator reading only this one can see which stores
+      # survive a restart. `OAUTH_CODE_ADAPTER` and
+      # `ACCESS_TOKEN_DENYLIST_ADAPTER` already ship as `redis` in that config
+      # layer and are left there on purpose — restating a value that agrees is
+      # a second place to forget to change.
       REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: redis://redis:6379
       SESSION_STORAGE_TYPE: redis
       SESSION_STORAGE_REDIS_URL: redis://redis:6379
+      # The UserSession stores: the provider's own record of who is signed in,
+      # which RPs a session has touched, and the family / federation indexes
+      # hanging off it. They MUST be on Redis whenever the express-session
+      # store above is, and this line is the fix for what happens when they
+      # are not.
+      #
+      # express-session on Redis survives a restart; a memory UserSession store
+      # does not. So every browser comes back holding a session cookie whose
+      # express-session record still says `isAuthenticated: true`, while the
+      # `UserSession` that record points at is gone — /authorize sees an
+      # authenticated session, finds no user session behind it, and sends the
+      # browser to log in again, where the still-valid cookie puts it straight
+      # back. A login loop that clears only when the user deletes the cookie.
+      # `DEPLOYMENT_MODE: single` says nothing about it: the replica guard
+      # answers "can these stores be shared", not "do these two stores have the
+      # same lifetime".
+      USER_SESSION_STORES_ADAPTER: redis
       # The memory rate limiter is per-process and evadable under bucket
       # exhaustion (see README) — production points it at Redis.
       RATE_LIMITER_ADAPTER: redis
+      # The federation token store is deliberately left at its `memory`
+      # default, and that is coherent here rather than an oversight: this
+      # template ships every federation disabled, so nothing writes to the
+      # store, and switching it on would need a 32-byte AES key
+      # (REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY) that this file must not
+      # invent — the records are long-lived upstream refresh tokens. Enabling
+      # a federation means setting BOTH, together:
+      #   FEDERATION_TOKEN_STORE_TYPE: redis
+      #   REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: <openssl rand -base64 32, from .env>
 
   redis:
     # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)

package/templates/standalone/docker-compose.yml

@@ -14,6 +14,23 @@ services:
     env_file:
       - path: .env
         required: false
+    environment:
+      # The same coherence the production file states, for the same reason,
+      # and it matters MORE here. `config/application.conf` already puts
+      # express-session, the authorization codes and the access-token denylist
+      # on the Redis this compose runs; only the UserSession stores were left
+      # on their `memory` default. That combination survives a restart on one
+      # side and not the other, so every browser comes back holding an
+      # express-session that still says `isAuthenticated` with no `UserSession`
+      # behind it and /authorize loops.
+      #
+      # A dev container restarts on every save (`target: develop` is hot
+      # reload), so the developer meets that loop constantly — and meets it
+      # while changing something else, which is the worst possible time to
+      # debug it. Redis is already running and already required by three other
+      # stores, so this costs nothing: the shared ioredis socket is open
+      # either way.
+      USER_SESSION_STORES_ADAPTER: redis
 
   redis:
     # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {

package/templates/standalone/src/__tests__/device-code-store-client-module.test.mts

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * `standaloneRedisClientsModule` provides `deviceCodeStoreClient` (#433).
+ *
+ * The template does not mount the device grant, so nothing in `buildModules`
+ * selects `redisDeviceCodeStoreModule` today and the smoke test's client-slot
+ * invariant cannot see it. This pins the slot directly: a deployment that adds
+ * `deviceGrantModule` to this manifest and picks the Redis store must not hit
+ * the `missing-required-component` boot failure that #439 already paid for
+ * once with the subject-level slots — a Redis-branch module whose required
+ * client slot the shared clients module did not provide, caught only by the
+ * umbrella e2e.
+ */
+
+import type { LifecycleRegistrar } from "@o3co/auth-provider-core";
+import { redisDeviceCodeStoreModule } from "@o3co/auth-provider-redis";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const redisCtorCalls: Array<{ url: string }> = [];
+
+vi.mock("ioredis", () => {
+	class MockRedis {
+		on = vi.fn();
+		quit = vi.fn(async () => "OK" as const);
+		ping = vi.fn(async () => "PONG" as const);
+		eval = vi.fn();
+		evalsha = vi.fn();
+		duplicate(): MockRedis {
+			return new MockRedis("redis://duplicate.local");
+		}
+		constructor(url: string) {
+			redisCtorCalls.push({ url });
+		}
+	}
+	return { Redis: MockRedis, default: MockRedis };
+});
+
+const importModule = async () => await import("../modules.mjs");
+
+const baseConfig = {
+	refreshTokenFamilyStore: {
+		redis: { url: "redis://example.com:6379" },
+	},
+};
+
+describe("#433 / standaloneRedisClientsModule.deviceCodeStoreClient", () => {
+	beforeEach(() => {
+		redisCtorCalls.length = 0;
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("provides every *Client slot redisDeviceCodeStoreModule requires", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provided = new Set(Object.keys(standaloneRedisClientsModule.provides ?? {}));
+		const required = [...(redisDeviceCodeStoreModule.requires ?? [])].filter((key) =>
+			key.endsWith("Client"),
+		);
+		expect(required).toEqual(["deviceCodeStoreClient"]);
+		expect(required.filter((key) => !provided.has(key))).toEqual([]);
+	});
+
+	it("resolves the client off the one shared socket, not a second connection", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		const lifecycleRegistrar: LifecycleRegistrar = { register: () => {} };
+
+		const client = (await provides.deviceCodeStoreClient?.({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+		})) as Record<string, unknown>;
+		await provides.rateLimiterClient?.({ config: { ...baseConfig }, lifecycleRegistrar });
+
+		expect(redisCtorCalls).toHaveLength(1);
+		for (const method of ["create", "findPending", "decide", "poll", "remove"]) {
+			expect(typeof client[method], `deviceCodeStoreClient.${method}`).toBe("function");
+		}
+	});
+});