@o3co/create-auth-provider 0.10.0 → 0.11.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.11.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,15 @@ SESSION_SECRET=
 CLIENT_USER_AUTHENTICATE_URL=
 CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
 
-# Redis (code repository + session storage)
+# 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,7 +114,7 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 
 設定上の注意が 2 点:
 
-- TLS 終端プロキシの背後では `HTTP_TRUST_PROXY=true` を設定する。設定しないと `req.protocol` は `http` のままでブラウザは `Origin: https://…` を送るため、origin 側の判定が全リクエストを拒否する。
+- 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 信頼を与えなくなった。
 
 ### Google フェデレーション
@@ -271,9 +271,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

@@ -460,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 |

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}

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).

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

@@ -38,7 +38,16 @@ services:
       target: runtime
     restart: unless-stopped
     ports:
-      - "3000:3000"
+      # Loopback-bound on purpose (#407). This file assumes TLS is terminated
+      # in front, and the README says to keep `/metrics` off the public
+      # listener — a bare "3000:3000" publishes on every interface and
+      # contradicts both. A reverse proxy on the same host reaches it here.
+      #
+      # If your load balancer is on another host, publish it instead
+      # (`- "3000:3000"`) and put the access control somewhere real: a
+      # security group, a firewall rule, or the proxy's own network. Do not
+      # widen this line and call it done.
+      - "127.0.0.1:3000:3000"
     depends_on:
       redis:
         condition: service_healthy
@@ -88,6 +97,13 @@ services:
       RATE_LIMITER_ADAPTER: redis
 
   redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
     image: redis:7.2-alpine
     restart: unless-stopped
     # No `ports:`, deliberately — the app reaches Redis over the compose

package/templates/standalone/docker-compose.yml

@@ -16,6 +16,13 @@ services:
         required: false
 
   redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
     image: redis:7.2-alpine
     ports:
       - "127.0.0.1:6379:6379"

package/templates/standalone/gitignore

@@ -0,0 +1,21 @@
+# #407: without this file, the first `git add .` in a scaffolded project
+# commits the two things the README's own setup steps tell you to create right
+# here — the `.env` holding SESSION_SECRET, and the signing key pair.
+
+# Secrets and per-machine configuration
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+config/clients.yaml
+config/*.local.conf
+
+# Build output and dependencies
+node_modules/
+dist/
+coverage/
+
+# Editor / OS noise
+.DS_Store
+*.log

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -27,8 +27,7 @@
 		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
 		"@o3co/auth-provider-session": "workspace:*",
-		"@o3co/auth.utils": "^0.0.4",
-		"@o3co/ts.hocon": "^1.12.0",
+		"@o3co/ts.hocon": "^1.13.0",
 		"connect-redis": "^10.0.0",
 		"express": "^5.2.1",
 		"express-session": "^1.19.0",
@@ -36,7 +35,7 @@
 		"ioredis": "^6.0.0",
 		"pino": "^10.3.1",
 		"prom-client": "^15.1.3",
-		"redis": "^6.2.0"
+		"redis": "^6.2.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
@@ -45,7 +44,7 @@
 		"@types/supertest": "^7.2.1",
 		"supertest": "^7.1.0",
 		"tsx": "^4.23.10",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.10"
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.11"
 	}
 }

package/templates/standalone/src/__tests__/documented-env-overrides.test.mts

@@ -88,11 +88,15 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	OAUTH_OIDC_MODE: "dual",
 	OAUTH_CODE_ADAPTER: "redis",
 	OAUTH_REVOCATION_ACCESS_TOKEN: "denylist",
+	OAUTH_REVOCATION_SUBJECT: "unsupported",
 	OAUTH_REQUIRE_EMAIL_VERIFIED: "true",
+	OAUTH_REQUIRE_GRANT_TYPE_ALLOWLIST: "true",
+	OAUTH_GRANTS_JWT_BEARER_ENABLED: "false",
 	OAUTH_NONCE_MAX_LENGTH: "256",
 	OAUTH_TOKEN_EXCHANGE_MAX_ACTOR_CHAIN_DEPTH: "3",
 	OAUTH_RESOURCE_INDICATOR_ENABLED: "true",
 	OAUTH_TOKEN_BINDING_DISPATCH_POLICY: "intent-explicit",
+	OAUTH_TOKEN_BINDING_BIND_CONFIDENTIAL_CLIENT_REFRESH_TOKENS: "true",
 
 	// --- oauth.grants -------------------------------------------------
 	OAUTH_GRANTS_SESSION_ENABLED: "false",

package/templates/standalone/src/__tests__/scaffold-assets.test.mts

@@ -0,0 +1,117 @@
+/*
+ * 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.
+ */
+
+/**
+ * Issue #407 — scaffold hardening from the v0.10.0 release-cut audit.
+ *
+ * These pin the parts of the scaffold that are checkable from inside the
+ * repository. The scaffold is the artifact an operator actually deploys, and
+ * every one of these was invisible until someone read the file: the container
+ * install losing an allowlist, the dev compose dialling a Redis that is not
+ * there, and one `git add .` committing the signing key.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const standaloneDir = fileURLToPath(new URL("../..", import.meta.url));
+const read = (rel: string): string => readFileSync(`${standaloneDir}${rel}`, "utf8");
+
+describe("#407 — the Dockerfile installs with everything pnpm needs", () => {
+	it("copies pnpm-workspace.yaml into the deps stage", () => {
+		// `create-auth-provider` generates it to carry the bcrypt
+		// `onlyBuiltDependencies` allowlist, because pnpm >= 10.29 reads that
+		// setting ONLY from this file — in single-package projects too (#360).
+		// A deps stage that copies `package.json` and the lockfile but not this
+		// runs allowlist-less, which re-creates #360 the day an alpine prebuild
+		// is missing and bcrypt has to compile.
+		const dockerfile = read("/Dockerfile");
+		const depsStage = dockerfile.slice(
+			dockerfile.indexOf("FROM node-base AS deps"),
+			dockerfile.indexOf("FROM", dockerfile.indexOf("FROM node-base AS deps") + 1),
+		);
+		// Matched as a COPY instruction, not as a substring of the stage: the
+		// comment above that COPY names the file too, so a substring check
+		// would keep passing if the instruction regressed and the comment
+		// stayed — which is the failure this test exists to catch.
+		const copyLines = depsStage
+			.split("\n")
+			.filter((line) => /^COPY\b/.test(line.trim()) && !line.trim().startsWith("#"));
+		expect(copyLines.some((line) => /\bpnpm-workspace\.yaml\b/.test(line))).toBe(true);
+	});
+});
+
+describe("#407 — the dev compose can reach every Redis it configures", () => {
+	it("sets every *_REDIS_URL the template config reads", () => {
+		// The template's application.conf substitutes several Redis URLs, each
+		// defaulting to `redis://localhost:6379` — which inside the container is
+		// the container itself. `.env.example` is what the compose file loads,
+		// so a URL missing from it is a boot that dials nothing.
+		const conf = read("/config/application.conf");
+		const declared = [...conf.matchAll(/\$\{\?([A-Z0-9_]*REDIS_URL)\}/g)].map((m) => m[1]);
+		expect(declared.length).toBeGreaterThan(0);
+
+		const env = read("/.env.example");
+		const missing = [...new Set(declared)].filter(
+			(name) => !new RegExp(`^${name}=`, "m").test(env),
+		);
+		expect(missing).toEqual([]);
+	});
+});
+
+describe("#407 — the scaffold does not invite committing its own secrets", () => {
+	it("ships a .gitignore", () => {
+		// Without one, the first `git add .` in a scaffolded project commits
+		// `.env` and `jwt-private.pem` — both of which the README tells the
+		// operator to create right there.
+		expect(existsSync(`${standaloneDir}/.gitignore`)).toBe(true);
+	});
+
+	it("ignores the files the scaffold's own setup steps create", () => {
+		const ignored = read("/.gitignore");
+		for (const pattern of [".env", "*.pem", "node_modules", "dist"]) {
+			expect(ignored).toContain(pattern);
+		}
+	});
+
+	it("keeps .env.example tracked — it is the documentation", () => {
+		// A bare `.env*` would take the example with it, which is the mistake
+		// this pins against.
+		expect(read("/.gitignore")).toMatch(/^!\.env\.example$/m);
+	});
+});
+
+describe("#407 — the production compose matches the topology it documents", () => {
+	it("does not publish the app port on every interface", () => {
+		// The README says to keep `/metrics` off the public listener and the
+		// file assumes TLS is terminated in front, so a bare "3000:3000"
+		// contradicts both — it binds 0.0.0.0 on the host.
+		const compose = read("/docker-compose.production.yml");
+		expect(compose).not.toMatch(/^\s*-\s*"3000:3000"\s*$/m);
+		expect(compose).toMatch(/127\.0\.0\.1:3000:3000/);
+	});
+});
+
+describe("#407 — the two READMEs agree on security advice", () => {
+	it("does not recommend HTTP_TRUST_PROXY=true in the Japanese README", () => {
+		// #292 made `trust proxy` a CIDR/hop policy precisely because `true`
+		// means "believe the leftmost forwarded entry from whoever opened the
+		// connection". The English README warns against it; the Japanese one
+		// still recommended it, so the two disagreed on which is safe.
+		expect(read("/README.ja.md")).not.toMatch(/HTTP_TRUST_PROXY=true/);
+	});
+});

package/templates/standalone/src/__tests__/shutdown.test.mts

@@ -0,0 +1,244 @@
+/*
+ * 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.
+ */
+
+/**
+ * Issue #290 — shutdown was delegated to `@o3co/auth.utils@0.0.4`, whose
+ * guarantees were not pinned by any contract this repository could check.
+ *
+ * Reading the 22 lines answered the question the issue asked, and the answer
+ * was worth knowing: **there was no force-close deadline**. `server.close()`
+ * waits for in-flight requests indefinitely, so one stuck request meant the
+ * process never exited on its own and the orchestrator's SIGKILL took it down
+ * mid-flight — the opposite of a graceful shutdown, and invisible until it
+ * happened. The cleanup-failure path also wrote to `console.error`, a bare
+ * line in a service whose every other line is NDJSON.
+ *
+ * So the behaviour lives here now, with a deadline and the app's own logger,
+ * and these tests are the contract the issue said was missing.
+ */
+
+import type { Server } from "node:http";
+import type { Logger } from "@o3co/auth-provider-core";
+import { describe, expect, it, vi } from "vitest";
+import { installGracefulShutdown } from "../shutdown.mjs";
+
+/** A `Server` double whose `close` callback fires only when we say so. */
+function makeServer() {
+	let closeCallback: ((err?: Error) => void) | undefined;
+	const server = {
+		close: vi.fn((cb?: (err?: Error) => void) => {
+			closeCallback = cb;
+			return server;
+		}),
+		closeIdleConnections: vi.fn(),
+		closeAllConnections: vi.fn(),
+	};
+	return {
+		server: server as unknown as Server,
+		spies: server,
+		/** Simulate the last in-flight request finishing. */
+		finishDraining: () => closeCallback?.(),
+		/** Simulate `close` reporting a failure through its callback. */
+		failClose: (err: Error) => closeCallback?.(err),
+		get drained() {
+			return closeCallback !== undefined;
+		},
+	};
+}
+
+/**
+ * A `Logger`-shaped spy. Typed rather than cast: `as never` would hide a real
+ * mismatch the day the port gains a method, which is the whole reason the
+ * shutdown path logs through the app logger instead of `console`.
+ */
+const makeLogger = () => {
+	const spy = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		// `child` returns a Logger; returning this one keeps a child's calls
+		// visible on the same spies, which is what a test wants.
+		child: vi.fn(() => spy as unknown as Logger),
+	};
+	return spy satisfies Logger;
+};
+
+/** Drive one shutdown without touching the real `process` or exiting. */
+function install(opts: { cleanup?: () => void | Promise<void>; drainTimeoutMs?: number } = {}) {
+	const { server, spies, finishDraining, failClose } = makeServer();
+	const logger = makeLogger();
+	const exit = vi.fn();
+	const signals = new Map<string, () => void>();
+
+	installGracefulShutdown(server, {
+		logger,
+		cleanup: opts.cleanup ?? (() => {}),
+		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
+		exit,
+		onSignal: (name, handler) => signals.set(name, handler),
+		offSignal: (name) => signals.delete(name),
+	});
+
+	return { spies, logger, exit, signals, finishDraining, failClose };
+}
+
+describe("installGracefulShutdown (#290)", () => {
+	it("listens for both SIGTERM and SIGINT", async () => {
+		const { signals } = install();
+		expect([...signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
+	});
+
+	it("stops accepting connections and releases idle keep-alive sockets", async () => {
+		const { spies, signals } = install();
+		signals.get("SIGTERM")?.();
+		expect(spies.close).toHaveBeenCalled();
+		// Idle keep-alive sockets hold the server open with no request behind
+		// them; releasing them is what lets a quiet server exit promptly.
+		expect(spies.closeIdleConnections).toHaveBeenCalled();
+	});
+
+	it("runs cleanup once draining completes, then exits zero", async () => {
+		const cleanup = vi.fn();
+		const { exit, signals, finishDraining } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		expect(cleanup).not.toHaveBeenCalled();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	it("ignores a second signal instead of running cleanup twice", async () => {
+		// An operator pressing ^C twice, or a SIGINT arriving after SIGTERM,
+		// must not start a second dispose over the first one's stores.
+		const cleanup = vi.fn();
+		const { signals, finishDraining, exit } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		signals.get("SIGINT")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	// The gap the audit was pointing at.
+	it("forces the remaining connections closed when draining outruns the deadline", async () => {
+		vi.useFakeTimers();
+		try {
+			const { spies, signals, exit } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(spies.closeAllConnections).toHaveBeenCalled();
+			expect(exit).toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("exits non-zero on a forced close, so the drain outcome is visible", async () => {
+		// An orchestrator that only ever sees exit 0 cannot tell a clean drain
+		// from one that ran out of time and cut requests off.
+		vi.useFakeTimers();
+		try {
+			const { signals, exit, logger } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(exit).toHaveBeenCalledWith(1);
+			expect(logger.error).toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not force-close a drain that finished in time", async () => {
+		vi.useFakeTimers();
+		try {
+			const { spies, signals, finishDraining, exit } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
+			await vi.advanceTimersByTimeAsync(10_000);
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+			expect(exit).toHaveBeenCalledTimes(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("reports a cleanup failure through the app logger, not console", async () => {
+		// Every other line this service emits is NDJSON through pino; a bare
+		// console.error on the shutdown path is the one a log pipeline drops.
+		const { logger, exit, signals, finishDraining } = install({
+			cleanup: () => {
+				throw new Error("redis quit failed");
+			},
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(logger.error).toHaveBeenCalledWith(
+			expect.objectContaining({ err: expect.any(Error) }),
+			expect.stringContaining("cleanup"),
+		);
+	});
+
+	it("still exits when cleanup throws — a failed dispose must not wedge the process", async () => {
+		const { exit, signals, finishDraining } = install({
+			cleanup: async () => {
+				throw new Error("dispose failed");
+			},
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+	});
+
+	it("does not report a failed close as a clean drain", async () => {
+		// `server.close` reports through its callback -- "Server is not running"
+		// is the common one, but any listener teardown failure lands there.
+		// Exiting 0 on it would tell an orchestrator the listener came down
+		// when it did not.
+		const { exit, logger, signals, failClose } = install();
+		signals.get("SIGTERM")?.();
+		failClose(new Error("Server is not running"));
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+		expect(logger.error).toHaveBeenCalledWith(
+			expect.objectContaining({ err: expect.any(Error) }),
+			expect.stringContaining("close"),
+		);
+	});
+
+	it("still runs cleanup when close reports a failure", async () => {
+		// The listener failing to come down is no reason to leak the Redis
+		// connections behind it.
+		const cleanup = vi.fn();
+		const { exit, signals, failClose } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		failClose(new Error("teardown failed"));
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	it("removes its own signal listeners once shutting down", async () => {
+		// Otherwise a repeated signal keeps re-entering a handler that has
+		// already handed the process over to `close`.
+		const { signals } = install();
+		signals.get("SIGTERM")?.();
+		expect(signals.size).toBe(0);
+	});
+});

package/templates/standalone/src/__tests__/smoke.test.mts

@@ -469,6 +469,42 @@ describe("standalone smoke test", () => {
 			expect(names).not.toContain("standalone:stores");
 			expect(names).toContain("standalone:redis-clients");
 		});
+
+		// #321's `redisSessionStoresModule` requires the two subject-level client
+		// slots (`subjectSessionIndexClient`, `subjectRevocationClient`) its
+		// adapters consume, and the scaffold's shared ioredis module did not
+		// provide them — so `userSessionStores.adapter = "redis"`, the
+		// template's own multi-replica path, failed stage-1 boot with
+		// `missing-required-component`. Nothing here booted that branch: the
+		// tests above check which modules are selected, not whether the
+		// selection is satisfiable. This pins the invariant the shared clients
+		// module exists for: every `*Client` slot any selected module requires
+		// is one it provides.
+		it("standalone:redis-clients provides every *Client slot the Redis branches require", () => {
+			const allRedisConfig = {
+				...config,
+				userSessionStores: { adapter: "redis" as const },
+				rateLimiter: { adapter: "redis" as const },
+				accessTokenDenylist: { adapter: "redis" as const },
+				oauth: { ...config.oauth, code: { adapter: "redis" as const } },
+			};
+			// No `refreshTokenFamilyModules` override: the default is the Redis
+			// RT-family store, so `refreshTokenFamilyClient` is part of what the
+			// invariant covers. Still hermetic — buildModules opens no socket.
+			const modules = buildModules(allRedisConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+			});
+			const clients = modules.find((m) => m.name === "standalone:redis-clients");
+			expect(clients).toBeDefined();
+			const provided = new Set(Object.keys(clients?.provides ?? {}));
+			const requiredClientSlots = new Set(
+				modules.flatMap((m) => [...(m.requires ?? [])]).filter((key) => key.endsWith("Client")),
+			);
+			expect(requiredClientSlots.size).toBeGreaterThan(0);
+			const missing = [...requiredClientSlots].filter((key) => !provided.has(key));
+			expect(missing).toEqual([]);
+		});
 	});
 
 	// #277: the scaffold used to wire NO access-token denylist, so the

package/templates/standalone/src/app.mts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import { gracefulShutdown } from "@o3co/auth.utils";
 import {
 	type AppConfig,
 	AppConfigSchema,
@@ -30,6 +29,7 @@ import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
+import { installGracefulShutdown } from "./shutdown.mjs";
 import { createTerminalErrorHandler } from "./terminalError.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
@@ -154,5 +154,14 @@ await (async (): Promise<void> => {
 	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
 	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain
 	// (Redis clients, interval timers).
-	gracefulShutdown(server, () => handle.dispose());
+	//
+	// #290: in the template rather than a dependency, because "does SIGTERM
+	// wait for in-flight requests, and for how long?" has to be answerable
+	// from the code you deploy. See `shutdown.mts` for the stated guarantees
+	// and for the deadline the previous implementation did not have. Size
+	// `drainTimeoutMs` below your orchestrator's kill grace period.
+	installGracefulShutdown(server, {
+		logger,
+		cleanup: () => handle.dispose(),
+	});
 })();

package/templates/standalone/src/modules.mts

@@ -22,6 +22,8 @@ import {
 	createInMemorySessionFamilyIndex,
 	createInMemorySessionFederationIndex,
 	createInMemorySessionRPRegistry,
+	createInMemorySubjectRevocation,
+	createInMemorySubjectSessionIndex,
 	createInMemoryUserSessionStore,
 	createKeyStoreFactory,
 	createRepositoryFactories,
@@ -198,6 +200,20 @@ export const inMemorySessionStoresModule: Module = defineModule({
 		sessionRPRegistry: () => createInMemorySessionRPRegistry(),
 		sessionFamilyIndex: () => createInMemorySessionFamilyIndex(),
 		sessionFederationIndex: () => createInMemorySessionFederationIndex(),
+		// #406: the two subject-level revocation slots. They were missing here
+		// on both branches, so a scaffolded deployment got
+		// `subjectRevocation: undefined` — `verifyJwt` skipped the watermark,
+		// the #376 refresh gate was inert, and `revokeAllForSubject` reported
+		// `unavailable`. Nothing failed and nothing warned, which is what #406
+		// is about; the boot guard now refuses that state, and the scaffold's
+		// answer is to wire them rather than to declare the capability absent.
+		//
+		// Single-process only, like every other store on this branch. The
+		// redis branch swaps in `redisSessionStoresModule`, which has provided
+		// both since #321 — before that there was no distributed adapter to
+		// point at, which is why this gap outlived #296.
+		subjectSessionIndex: () => createInMemorySubjectSessionIndex(),
+		subjectRevocation: () => createInMemorySubjectRevocation(),
 	},
 });
 
@@ -304,10 +320,11 @@ export const storesModule: Module = defineModule({
 
 /**
  * Shared ioredis clients module — opens ONE long-lived ioredis connection
- * per replica, wraps it via `makeIoredisClients()` (returns 11 typed
+ * per replica, wraps it via `makeIoredisClients()` (returns 13 typed
  * per-purpose clients), and exposes the slots consumed by the standalone's
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
- * rate limiter + code repository + access-token denylist).
+ * subject-level revocation index + watermark + rate limiter + code
+ * repository + access-token denylist).
  *
  * Per F4 PR1 (D-2 v2) + Wave 5d unification: the previous design opened a
  * separate ioredis socket per Redis-backed module (3+ sockets per replica).
@@ -407,6 +424,27 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.accessTokenDenylistClient;
 		},
+		// #321: the two subject-level revocation client slots, off the same
+		// shared socket. `redisSessionStoresModule` requires both — the index
+		// enumerates what a credential change cascades over and the watermark
+		// refuses what the cascade missed — so without them the scaffold's
+		// Redis branch had no provider for the slots and stage-1 boot refused
+		// the manifest with `missing-required-component`. Nothing in the
+		// standalone consumes these slots directly; they exist so the module
+		// that does can be selected.
+		subjectSessionIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.subjectSessionIndexClient;
+		},
+		subjectRevocationClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.subjectRevocationClient;
+		},
 	},
 });
 

package/templates/standalone/src/shutdown.mts

@@ -0,0 +1,162 @@
+/*
+ * 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.
+ */
+
+import type { Server } from "node:http";
+import type { Logger } from "@o3co/auth-provider-core";
+
+/**
+ * Graceful shutdown for the scaffolded server (#290).
+ *
+ * ## Why this is in the template rather than a dependency
+ *
+ * It used to be `gracefulShutdown` from `@o3co/auth.utils@0.0.4`. The ops
+ * review's objection was not that the package is bad — it is that for the
+ * component which terminates every user session, "does SIGTERM wait for
+ * in-flight requests, and for how long?" has to be answerable from the code an
+ * operator deploys, and it was answerable only by reading a pre-1.0 package
+ * with no contract pinned here.
+ *
+ * Reading it answered the question, and the answer was the reason to move it:
+ * **there was no deadline**. `server.close()` waits for in-flight requests
+ * indefinitely, so a single stuck request meant the process never exited on
+ * its own and the orchestrator's SIGKILL took it down mid-flight — the
+ * opposite of a graceful shutdown, arriving only under the load that produces
+ * a stuck request. The cleanup-failure path also wrote to `console.error`, one
+ * bare line in a service whose every other line is NDJSON.
+ *
+ * Neither is fixed by documenting or pinning the dependency, which is why this
+ * is ~40 lines here with tests, rather than a version range and a README
+ * paragraph.
+ *
+ * ## The guarantees, stated
+ *
+ * 1. **SIGTERM and SIGINT** both start it; the second signal is ignored rather
+ *    than starting a second dispose over the first one's stores.
+ * 2. **New connections stop immediately** (`server.close`), and idle keep-alive
+ *    sockets are released (`closeIdleConnections`) — 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 are given `drainTimeoutMs`** (default 10s) to finish.
+ * 4. **Past the deadline, remaining connections are cut** (`closeAllConnections`)
+ *    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**, and its failure is logged
+ *    through the app logger and reflected in the exit code. It never wedges the
+ *    process: a dispose that throws still exits.
+ * 6. **A `close` that fails is not reported as a clean drain.** `server.close`
+ *    reports through its callback, and treating that as success would tell an
+ *    orchestrator the listener came down when it did not.
+ *
+ * Size `drainTimeoutMs` **below** the orchestrator's own kill grace period
+ * (Kubernetes `terminationGracePeriodSeconds`, compose `stop_grace_period`,
+ * both 30s by default) — the point is to close on our terms before SIGKILL
+ * arrives on someone else's.
+ */
+export interface GracefulShutdownOptions {
+	readonly logger: Logger;
+	/** Reverse-topological component cleanup — normally `handle.dispose()`. */
+	readonly cleanup?: () => void | Promise<void>;
+	/** How long in-flight requests get before connections are cut. Default 10s. */
+	readonly drainTimeoutMs?: number;
+	/** Injected in tests; defaults to `process.exit`. */
+	readonly exit?: (code: number) => void;
+	/** Injected in tests; defaults to `process.on`. */
+	readonly onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+	/** Injected in tests; defaults to `process.removeListener`. */
+	readonly offSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+}
+
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
+
+export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
+	const {
+		logger,
+		cleanup,
+		drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+		exit = (code: number): void => {
+			process.exit(code);
+		},
+		onSignal = (signal, handler): void => {
+			process.on(signal, handler);
+		},
+		offSignal = (signal, handler): void => {
+			process.removeListener(signal, handler);
+		},
+	} = options;
+
+	let shuttingDown = false;
+	let finished = false;
+
+	/** Run `cleanup` and exit. Called by whichever of drain / deadline wins. */
+	const finish = async (code: number, reason: string): Promise<void> => {
+		if (finished) return;
+		finished = true;
+		let exitCode = code;
+		try {
+			await cleanup?.();
+		} catch (err) {
+			// Through the app logger, not `console.error`: a shutdown that
+			// failed to release its Redis connections is exactly the line an
+			// operator needs to find later, and a bare write is the one their
+			// pipeline drops.
+			logger.error({ err }, "graceful shutdown: cleanup failed");
+			exitCode = 1;
+		}
+		logger.info({ reason, exitCode }, "graceful shutdown: complete");
+		exit(exitCode);
+	};
+
+	const handler = (): void => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		for (const signal of SIGNALS) offSignal(signal, handler);
+		logger.info({ drainTimeoutMs }, "graceful shutdown: draining");
+
+		const deadline = setTimeout(() => {
+			logger.error(
+				{ drainTimeoutMs },
+				"graceful shutdown: drain deadline exceeded, closing remaining connections",
+			);
+			server.closeAllConnections();
+			void finish(1, "drain-timeout");
+		}, drainTimeoutMs);
+		// The deadline must not be what keeps the process alive once the drain
+		// has already finished.
+		deadline.unref?.();
+
+		server.close((err) => {
+			clearTimeout(deadline);
+			if (err) {
+				// `close` reports through its callback — "Server is not running"
+				// is the common one, but any listener teardown failure lands
+				// here. Reporting "drained" and exiting 0 on it would tell an
+				// orchestrator the shutdown went cleanly when the listener did
+				// not actually come down.
+				logger.error({ err }, "graceful shutdown: server close failed");
+				void finish(1, "close-failed");
+				return;
+			}
+			void finish(0, "drained");
+		});
+		// Idle keep-alive sockets have no request behind them, so nothing is
+		// lost by releasing them — and without this a quiet server waits out
+		// the whole deadline for connections that will never send anything.
+		server.closeIdleConnections();
+	};
+
+	for (const signal of SIGNALS) onSignal(signal, handler);
+}

package/templates/versions.json

@@ -1,13 +1,14 @@
 {
-	"@o3co/auth-provider-core": "0.10.0",
-	"@o3co/auth-provider-dpop": "0.10.0",
-	"@o3co/auth-provider-mtls": "0.10.0",
-	"@o3co/auth-provider-federation-google": "0.10.0",
-	"@o3co/auth-provider-federation-github": "0.10.0",
-	"@o3co/auth-provider-oauth": "0.10.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.10.0",
-	"@o3co/auth-provider-session": "0.10.0",
-	"@o3co/auth-provider-foundation": "0.10.0",
-	"@o3co/auth-provider-redis": "0.10.0",
-	"@o3co/auth-provider-webauthn": "0.10.0"
+	"@o3co/auth-provider-core": "0.11.0",
+	"@o3co/auth-provider-device-grant": "0.11.0",
+	"@o3co/auth-provider-dpop": "0.11.0",
+	"@o3co/auth-provider-mtls": "0.11.0",
+	"@o3co/auth-provider-federation-google": "0.11.0",
+	"@o3co/auth-provider-federation-github": "0.11.0",
+	"@o3co/auth-provider-oauth": "0.11.0",
+	"@o3co/auth-provider-oauth-token-exchange": "0.11.0",
+	"@o3co/auth-provider-session": "0.11.0",
+	"@o3co/auth-provider-foundation": "0.11.0",
+	"@o3co/auth-provider-redis": "0.11.0",
+	"@o3co/auth-provider-webauthn": "0.11.0"
 }