@o3co/create-auth-provider 0.10.0 → 0.12.0

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IA8DjE,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqBnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AA0DF,eAAO,MAAM,IAAI,QAAO,IAmEvB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IAyEjE,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqBnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AA0DF,eAAO,MAAM,IAAI,QAAO,IAmEvB,CAAC"}

package/dist/index.mjs

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { shouldCopyTemplateEntry } from "./internal/template-filter.mjs";
@@ -53,6 +53,16 @@ export const scaffold = (targetDir, projectName) => {
         recursive: true,
         filter: (source) => shouldCopyTemplateEntry(source, TEMPLATES_DIR),
     });
+    // #407: npm drops a file literally named `.gitignore` from a published
+    // package, so `copy-templates.mjs` stages it dot-less and it is restored
+    // here. Without it the first `git add .` in a scaffolded project commits
+    // the `.env` and the signing key the README's own setup steps say to
+    // create — and it would have shipped that way silently, because the file
+    // is present in the repository and only missing from the tarball.
+    const stagedGitignore = resolve(targetDir, "gitignore");
+    if (existsSync(stagedGitignore)) {
+        renameSync(stagedGitignore, resolve(targetDir, ".gitignore"));
+    }
     // Rewrite package.json
     const pkgPath = resolve(targetDir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/.env.example

@@ -40,10 +40,28 @@ SESSION_SECRET=
 CLIENT_USER_AUTHENTICATE_URL=
 CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
 
-# Redis (code repository + session storage)
+# --- 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
 SESSION_STORAGE_REDIS_URL=redis://redis:6379
+# #407: this one backs the SHARED ioredis socket -- the refresh-token family
+# store, the access-token denylist and the rate limiter all ride on it. It
+# defaults to redis://localhost:6379, which inside the container is the
+# container, so leaving it unset makes the compose boot dial nothing.
+REFRESH_TOKEN_FAMILY_STORE_REDIS_URL=redis://redis:6379
 
 # Development (override for local HTTP).
 # The default cookie name carries the `__Host-` prefix, which browsers only

package/templates/standalone/Dockerfile

@@ -24,7 +24,15 @@ FROM node-base AS deps
 # it at scaffold time and the project commits it. Without it this COPY fails,
 # which is the intended outcome — a build that silently re-resolves every
 # dependency range is the thing this file stopped doing (#289).
-COPY --chown=node:node package.json pnpm-lock.yaml ./
+#
+# pnpm-workspace.yaml is required for the same reason and was missing (#407):
+# the scaffolder generates it to carry bcrypt's `onlyBuiltDependencies`
+# allowlist, and pnpm >= 10.29 reads that setting ONLY from this file, in
+# single-package projects too (#360). Installing without it runs
+# allowlist-less, so pnpm silently skips bcrypt's build hook — which costs
+# nothing while an alpine prebuild exists, and re-creates #360 the day one
+# is missing and the native addon has to compile.
+COPY --chown=node:node package.json pnpm-lock.yaml pnpm-workspace.yaml ./
 
 USER node
 

package/templates/standalone/README.ja.md

@@ -42,7 +42,7 @@ overlay の値は `application.conf` を上書きします。scaffold には
 | 変数 | デフォルト | 説明 |
 |---|---|---|
 | `HTTP_PORT` | `3000` | サーバーがリッスンするポート |
-| `HTTP_TRUST_PROXY` | `false` | リバースプロキシの背後で動作する場合は `true` に設定。**ロードバランサ配下では必須** — 未設定だと `req.ip` が LB のアドレスになり、IP をキーとする全ての rate limit が全ユーザーで 1 バケットを共有する |
+| `HTTP_TRUST_PROXY` | `false` | Express の `trust proxy`。`false` / アドレス・CIDR のリスト (`10.0.0.0/8,loopback`) / ホップ数 (`1`) / `true` のいずれか。**ロードバランサ配下では必須** — 未設定だと `req.ip` が LB のアドレスになり、IP をキーとする全ての rate limit が全ユーザーで 1 バケットを共有する。`true` ではなく**実際のプロキシを名指しする**こと (#292): `true` は「接続してきた相手が誰であれ、その X-Forwarded-For の先頭を信じる」という意味で、プロセスに直接到達できる相手が自分で `req.ip` を選べてしまう。詳細は [Multi-replica deployments](#multi-replica-deployments) |
 
 ### OAuth JWT
 
@@ -114,8 +114,16 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 
 設定上の注意が 2 点:
 
-- TLS 終端プロキシの背後では `HTTP_TRUST_PROXY=true` を設定する。設定しないと `req.protocol` は `http` のままでブラウザは `Origin: https://…` を送るため、origin 側の判定が全リクエストを拒否する。
-- ログイン UI をプロバイダーと**別 origin** で配信している場合は、その origin を HOCON の `session.csrf.trustedOrigins` に列挙する。`cors.allowedOrigins` は CSRF 信頼を与えなくなった。
+- 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 信頼を与えない。
+
+### 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 フェデレーション
 
@@ -271,9 +279,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() });
 ```
 
+### シャットダウンの保証
+
+`src/shutdown.mts` は依存パッケージではなく scaffold 側に置いてある (#290)。全ユーザーセッションを終端するコンポーネントについて「SIGTERM は in-flight リクエストを待つのか、待つなら何秒か」は、デプロイするコード自体から答えられる必要があるため。
+
+1. **`SIGTERM` / `SIGINT`** のどちらでも開始する。2 回目のシグナルは無視する（1 回目の dispose に重ねて 2 回目を走らせない）。
+2. **新規接続は即座に停止**し、idle な keep-alive ソケットは解放する。リクエストを持たないまま server を開いたままにするソケットなので、解放しないと閑散時に deadline を丸ごと待つことになる。
+3. **in-flight リクエストには `drainTimeoutMs`**(既定 **10 秒**)を与える。
+4. **deadline を超えたら残接続を切り、プロセスは非ゼロ終了する。** 常に `0` しか見えない orchestrator では、正常な drain と時間切れの強制切断を区別できない。
+5. **`cleanup` は drain 後・exit 前**に走る(`handle.dispose()` = 逆トポロジカルなコンポーネント cleanup + Redis/タイマーの drain)。失敗はこのサービス自身の logger(他の行と同じ NDJSON)に出し、exit code にも反映する。dispose が throw してもプロセスは終了する。
+
+**`drainTimeoutMs` は orchestrator の kill grace period より短く設定すること** — Kubernetes の `terminationGracePeriodSeconds`、compose の `stop_grace_period` はいずれも既定 30 秒。他人の都合の `SIGKILL` が来る前に、自分の都合で閉じるのが目的。
+
 ## npm スクリプト
 
 | スクリプト | 説明 |

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
@@ -460,9 +601,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 |
@@ -474,6 +627,7 @@ gracefulShutdown(server, () => 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

@@ -149,6 +149,17 @@ session {
   sameSite = ${?SESSION_SAME_SITE}
   domain = null
   domain = ${?SESSION_DOMAIN}
+  # #405: every URL `POST /session/login` may accept as `redirect_to`, matched
+  # EXACTLY -- scheme, host, port, path and query all significant. Empty (the
+  # default) refuses every `redirect_to`, so leave it alone unless your login
+  # page actually posts one.
+  #
+  #   redirectAllowlist = ["https://app.example.com/welcome"]
+  #
+  # `http://` is accepted for loopback hosts only. With `domain` set above, an
+  # entry outside it fails boot rather than being silently ignored. The
+  # federation flow has a separate list per provider (see `federations` below).
+  redirectAllowlist = []
   storage {
     type = "redis"
     type = ${?SESSION_STORAGE_TYPE}
@@ -280,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/config/clients.yaml.example

@@ -7,8 +7,21 @@
 #   - "none":                public client — no clientSecret; PKCE/S256 mandatory at /authorize
 #
 # Secret format (only for confidential clients — basic / post):
-#   - Plain text: "my-secret"
-#   - Bcrypt hash: "$2b$10$..." (generate with: node -e "require('bcrypt').hash('secret',10).then(console.log)")
+#   - Bcrypt hash: "$2b$10$..."  <-- use this
+#   - Plain text: "my-secret"     <-- accepted, for local development only
+#
+# Generate a real one:
+#   SECRET=$(openssl rand -base64 32)
+#   node -e "require('bcrypt').hash(process.argv[1],10).then(console.log)" "$SECRET"
+# Give $SECRET to the client; put the hash in this file.
+#
+# #407: the schema accepts any non-empty string here, unlike `session.secret`
+# and the JWT signing secret, which have carried a 256-bit floor since #282.
+# That is deliberate — this field also holds a bcrypt hash, whose shape those
+# floors would reject — but it means NOTHING stops you from shipping
+# `clientSecret: "changeme"`. A client secret authenticates a confidential
+# client at the token endpoint; treat it as you would any other credential
+# and give it 256 bits of randomness.
 #
 # `firstParty` (#267): REQUIRED to be `true` for a client to use `/authorize`.
 #   `/authorize` mints a code as soon as the session is authenticated, with no

package/templates/standalone/config/production.conf

@@ -2,9 +2,15 @@
 # Loaded when CONFIG_ENV (or NODE_ENV) is "production".
 # Values here override application.conf.
 #
-# Most production-sensitive values (OAUTH_JWT_SECRET, SESSION_SECRET, REDIS URLs,
-# federation client secrets, etc.) should be supplied via environment variables —
-# see the ${?VAR} substitutions in application.conf.
+# Most production-sensitive values (SESSION_SECRET, the JWT signing key, REDIS
+# URLs, federation client secrets, etc.) should be supplied via environment
+# variables — see the ${?VAR} substitutions in application.conf.
+#
+# #407: this used to name OAUTH_JWT_SECRET as the typical example. That is the
+# HMAC secret, and it stopped being the default when EdDSA became one (#282) —
+# the shipped path is now a key pair delivered as files
+# (OAUTH_JWT_PRIVATE_KEY_PATH / OAUTH_JWT_PUBLIC_KEY_PATH), which
+# docker-compose.production.yml mounts as compose secrets.
 #
 # Override entries here only when a value must be fixed per-environment rather
 # than per-deployment (e.g. feature flags turned on only in production).