@o3co/create-auth-provider 0.9.0 → 0.11.0

package/templates/standalone/src/modules.mts

@@ -16,16 +16,23 @@
 import path from "node:path";
 import {
 	type AppConfig,
+	consoleLogger,
+	createAuditSinkFactory,
 	createFederationTokenStoreFactory,
 	createInMemorySessionFamilyIndex,
 	createInMemorySessionFederationIndex,
 	createInMemorySessionRPRegistry,
+	createInMemorySubjectRevocation,
+	createInMemorySubjectSessionIndex,
 	createInMemoryUserSessionStore,
 	createKeyStoreFactory,
 	createRepositoryFactories,
 	defineModule,
 	type LifecycleRegistrar,
+	type Logger,
 	type Module,
+	type ReadinessRegistrar,
+	registerBuiltinAuditSinks,
 	registerBuiltinFederationTokenStores,
 	registerBuiltinKeyStores,
 } from "@o3co/auth-provider-core";
@@ -34,16 +41,20 @@ import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
 import { redisFederationTokenStoreBuilder } from "@o3co/auth-provider-redis";
 import { makeIoredisClients } from "@o3co/auth-provider-redis/ioredis";
 import { extractFederationSection } from "@o3co/auth-provider-session";
-// Named import is required here, not default. Under `module: "nodenext"`
-// with esModuleInterop, the default import resolves to the entire ioredis
-// CJS module-exports namespace object (because ioredis 5.x ships
-// `export = Redis`), so `new Redis(...)` raises TS2351 "not constructable".
+// Named import is required here, not default. ioredis is CJS and its entry
+// does `module.exports = Redis` with the class re-exported as both `default`
+// and `Redis`; under `module: "nodenext"` with esModuleInterop the default
+// import therefore resolves to the module-exports namespace object rather
+// than the class, and `new Redis(...)` raises TS2351 "not constructable".
+// Still true on ioredis 6 — verified against 6.0.0, not inherited from the
+// ioredis 5 era this note was first written in.
 // The 11 default-import sites elsewhere in the repo all live under
 // `packages/redis/__tests__/` which `packages/redis/tsconfig.json`
 // explicitly excludes from strict tsc build (vitest's vue-tsc is more
 // permissive about CJS interop). Standalone production source is built
 // with strict nodenext, so the named import is the right shape here.
 import { Redis } from "ioredis";
+import { createAuditLogger, createLoggerAuditSink } from "./logger.mjs";
 
 /**
  * Helper: turn a v0.4.x { type, [type]: {...} } adapter-config slice into the
@@ -189,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(),
 	},
 });
 
@@ -218,6 +243,66 @@ export const federationTokenStoreModule: Module = defineModule({
 	},
 });
 
+/**
+ * Audit-sink module — fills the `auditSink` slot every route that emits a
+ * security event reads (#287).
+ *
+ * The slot is `optional` on `oauthModule`, `sessionModule` and `webauthnModule`,
+ * and `emitAuditEvent` is a no-op when it is empty. That combination is why the
+ * gap was invisible: the scaffold wired no sink, so `token.issued.failure`,
+ * `authorize.rejected` / `authorize.granted`, `logout.cascade_failed` and the
+ * shared rate-limit guard's `rate_limit.unavailable` were all discarded by the
+ * deployable artifact, with nothing failing and nothing warning. This module is
+ * always in the manifest for that reason — there is no "no audit sink" branch,
+ * the way there is a memory/redis branch for the state stores.
+ *
+ * Two sink kinds are registered:
+ *
+ * - `"logger"` (the template's default) — one NDJSON line per event on stdout,
+ *   in the same pino envelope as every other line this template emits, on a
+ *   stream named `audit` whose level is fixed. See `createAuditLogger`.
+ * - `"console"` — core's built-in, from `registerBuiltinAuditSinks`: the bare
+ *   event as one JSON object per line on stdout, with no log envelope. For a
+ *   pipeline that wants the event and nothing else.
+ *
+ * A deployment with a real sink (SIEM, log pipeline, message bus) registers its
+ * builder here and names it in `audit.sink.type`; its options ride along in the
+ * same config block (`flattenAdapterConfig` unwraps `sink { type = "x", x { … } }`).
+ *
+ * One thing to know before writing such a builder: `createAuditSinkFactory()`
+ * takes no `BuilderContext`, so a sink builder receives `{}` and the
+ * `ctx.lifecycle?.register(…)` / `ctx.readiness?.register(…)` calls that
+ * CONTRIBUTING.md requires of a builder opening a connection are silent no-ops
+ * here. A sink holding a socket must own its cleanup another way until that
+ * factory takes a context.
+ *
+ * There is deliberately no `"none"`. An unknown type — including the `"none"`
+ * an operator might reasonably guess at — fails boot naming the sinks that
+ * exist, rather than producing a deployment with no audit trail (#304).
+ */
+export const auditSinkModule: Module = defineModule({
+	name: "standalone:audit-sink",
+	requires: ["config"] as const,
+	provides: {
+		auditSink: async ({ config }) => {
+			const factory = createAuditSinkFactory();
+			registerBuiltinAuditSinks(factory);
+			factory.register("logger", () => createLoggerAuditSink(createAuditLogger()));
+			const slice = (config as AppConfig).audit?.sink;
+			// Absence lands on the default sink rather than on `undefined`: a
+			// config that says nothing about auditing is not a config asking for
+			// the events to be dropped. The literal default lives in HOCON
+			// (`reference.conf` / `application.conf`); this is the floor under a
+			// hand-built config that never met either.
+			return factory.create(
+				slice
+					? flattenAdapterConfig(slice as { type: string } & Record<string, unknown>)
+					: { type: "logger" },
+			);
+		},
+	},
+});
+
 /**
  * @deprecated since Wave 5d (F4 PR2): split into `inMemorySessionStoresModule`
  * + `federationTokenStoreModule`. Re-exported for backward compatibility
@@ -235,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 9 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).
+ * 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).
@@ -273,26 +359,46 @@ export const storesModule: Module = defineModule({
 export const standaloneRedisClientsModule: Module = defineModule({
 	name: "standalone:redis-clients",
 	requires: ["config"] as const,
-	optional: ["lifecycleRegistrar"] as const,
+	optional: ["lifecycleRegistrar", "readinessRegistrar", "logger"] as const,
 	provides: {
-		refreshTokenFamilyClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).refreshTokenFamilyClient;
+		refreshTokenFamilyClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.refreshTokenFamilyClient;
 		},
-		userSessionStoreClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).userSessionStoreClient;
+		userSessionStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.userSessionStoreClient;
 		},
-		sessionRPRegistryClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).sessionRPRegistryClient;
+		sessionRPRegistryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.sessionRPRegistryClient;
 		},
-		sessionFamilyIndexClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).sessionFamilyIndexClient;
+		sessionFamilyIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.sessionFamilyIndexClient;
 		},
-		sessionFederationIndexClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar)
+		sessionFederationIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
-		rateLimiterClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).rateLimiterClient;
+		rateLimiterClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.rateLimiterClient;
 		},
 		// OR-9: code-repository client wired off the same shared ioredis
 		// socket. `redisCodeRepositoryModule` consumes this slot when
@@ -300,12 +406,126 @@ export const standaloneRedisClientsModule: Module = defineModule({
 		// high-volume — sharing the connection avoids opening a separate
 		// socket while the per-purpose typed wrapper keeps the Redis
 		// command surface consumed by RedisCodeRepository explicit.
-		codeRepositoryClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).codeRepositoryClient;
+		codeRepositoryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.codeRepositoryClient;
+		},
+		// #277: access-token denylist client, off the same shared socket. A
+		// denylist is only worth having if every replica reads the same one —
+		// that is the entire reason `redisAccessTokenDenylistModule` exists — so
+		// it belongs on the connection the rest of the shared state already uses
+		// rather than opening a second one.
+		accessTokenDenylistClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			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;
 		},
 	},
 });
 
+/**
+ * Failure-timing options for the one shared ioredis socket (#286).
+ *
+ * On the driver's defaults this connection had no `commandTimeout` at all, so
+ * a partition did not produce errors — it produced *waiting*. Every `/token`
+ * request that touched Redis parked in the offline queue while the socket
+ * reconnected, and because nothing threw, the `rateLimit.failMode = "closed"`
+ * policy (`createRateLimitGuard`, OR-5) never engaged: it only fires when
+ * `limiter.check()` rejects. The load the policy exists to shed kept arriving
+ * and kept accumulating, and memory and sockets grew until ioredis's 20th
+ * reconnect attempt finally flushed the queue — tens of seconds later.
+ *
+ * The values below are chosen against the actual command surface of this
+ * socket, which is entirely O(1) primitives and small paged scans
+ * (`SET`/`GET`/`DEL`/`EXISTS`/`PTTL`/`INCR`/`EVAL`/`HSCAN`/`SSCAN`/`ZADD`/…).
+ * There is no blocking command here, so no legitimate command has any reason
+ * to take a meaningful fraction of a second.
+ *
+ * - `commandTimeout: 1000` — the hard ceiling on any single command. ioredis
+ *   arms this timer in `sendCommand`, *before* the writability check, so it
+ *   bounds a command that went into the offline queue exactly as it bounds one
+ *   already on the wire. That is what makes the queued case fail rather than
+ *   hang, and it is also the only guard that survives the nastiest partition
+ *   shape: a zombie TCP connection where no `close` event ever fires, so the
+ *   reconnect path described next is never entered at all.
+ * - `maxRetriesPerRequest: 3` — on the fourth reconnect attempt (roughly
+ *   0.4–1 s in on ioredis 6's jittered exponential backoff) the whole queue is
+ *   failed in one go with `MaxRetriesPerRequestError`, rather than on the
+ *   twentieth as the default has it. `commandTimeout` alone bounds each command's
+ *   *latency*, but the queue would still grow to (request rate × 1 s) entries
+ *   for as long as the outage lasted; this bounds its *depth*. Three rather
+ *   than one so an ordinary sub-second reconnect blip is ridden out silently.
+ * - `connectTimeout: 5000` — halves the driver's 10 s default. A dropped SYN
+ *   (a partition that black-holes packets rather than refusing them) is the
+ *   only case that reaches this ceiling; a real connect on any deployment
+ *   topology this template targets completes in well under a second.
+ * - `enableOfflineQueue: true` — the driver default, declared explicitly
+ *   because it is a decision, not an inherited value. See below.
+ * - `lazyConnect: false` — also the driver default (still, on ioredis 6),
+ *   declared so the boot-time-connect contract survives a future flip.
+ *
+ * **Why the offline queue stays on.** Turning it off is the sharper answer for
+ * the rate limiter specifically: a command issued while the socket is down
+ * rejects immediately instead of after `commandTimeout`, so the fail-closed
+ * policy sheds load at the first request rather than one second per request
+ * later. But `enableOfflineQueue` is a per-**connection** option, and this
+ * template runs every purpose off one socket — refresh-token families, the
+ * four user-session stores, the authorization-code repository, the
+ * access-token denylist and the rate limiter all come out of a single
+ * `makeIoredisClients(io)` call (pinned by "one connection in, one connection
+ * used" in `packages/redis/__tests__/ioredis.test.mts`). There is no way to
+ * express "off here, on there" without opening a second socket, which is the
+ * connection-pool pressure the shared-socket design was built to avoid.
+ *
+ * So the choice is one setting for all eleven purposes, and `false` is the
+ * wrong one to pick for all eleven: it converts every reconnect — including
+ * the sub-second blip of a routine managed-Redis failover, during which
+ * ioredis would have recovered transparently — into hard errors on session
+ * lookup, code redemption and refresh rotation. A failed refresh rotation is
+ * not a retryable blip to the end user; it is a re-login.
+ *
+ * `true` costs the rate limiter up to `commandTimeout` of delay before it
+ * starts shedding, and that is the honest trade. It is affordable precisely
+ * because `commandTimeout` exists: the pile-up is now bounded by
+ * (request rate × 1 s) and self-draining, rather than unbounded and growing.
+ * A deployment that wants the sharper behavior gives the rate limiter its own
+ * connection in its own composition root — the per-purpose client interfaces
+ * exist for exactly that, and it is a deliberate second socket rather than a
+ * silent global.
+ */
+const SHARED_REDIS_TIMEOUTS = {
+	commandTimeout: 1_000,
+	connectTimeout: 5_000,
+	maxRetriesPerRequest: 3,
+	enableOfflineQueue: true,
+	lazyConnect: false,
+} as const;
+
 // Module-scoped cache so each `provides.*` factory invocation reuses the
 // same `Redis` instance (and its `makeIoredisClients()` derivation) within
 // a single createApp() invocation. The boot planner calls each `provides`
@@ -324,7 +544,10 @@ const clientsCache = new WeakMap<LifecycleRegistrar, ReturnType<typeof makeIored
 function getOrCreateClients(
 	config: AppConfig,
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
+	readinessRegistrar?: ReadinessRegistrar,
+	injectedLogger?: Logger,
 ): ReturnType<typeof makeIoredisClients> {
+	const logger = injectedLogger ?? consoleLogger;
 	const cached = lifecycleRegistrar ? clientsCache.get(lifecycleRegistrar) : undefined;
 	if (cached) return cached;
 
@@ -339,29 +562,57 @@ function getOrCreateClients(
 	}
 	const password = typeof cfg.password === "string" ? cfg.password : undefined;
 
-	// `lazyConnect: false` is the ioredis 5.x default; the explicit option
-	// documents the boot-time-connect contract so a future ioredis version
-	// flip does not silently change the failure mode.
-	const io = new Redis(cfg.url, { password, lazyConnect: false });
+	const io = new Redis(cfg.url, { password, ...SHARED_REDIS_TIMEOUTS });
 
-	// Attach error handler so unhandled "error" events from ioredis 5.x do
-	// not crash the Node.js process. Initial connection failures surface
-	// here; downstream adapter operations then fail visibly. TODO(D-4):
-	// swap `console.error` for the Logger interface once a v0.5.2 polish
-	// PR lands.
+	// Attach an error handler so unhandled "error" events do not crash the
+	// process. Initial connection failures surface here; downstream adapter
+	// operations then fail visibly.
 	io.on("error", (err: unknown) => {
-		console.error("[standalone:redis-clients] ioredis error", err);
+		logger.error({ err }, "standalone_redis_clients_error");
 	});
 
 	lifecycleRegistrar?.register(async () => {
 		await io.quit();
 	});
 
-	const clients = makeIoredisClients(io);
+	// One probe for the one socket. Registering per consumed slot would report
+	// the same connection six times; the cache above means this runs once per
+	// boot, on the call that actually constructs the client.
+	readinessRegistrar?.register({
+		name: "redis",
+		check: () => io.ping(),
+	});
+
+	// The wrapper opens its own connections for refresh rotation
+	// (`refreshTokenFamilyClient.duplicate()`), which inherit no listeners from
+	// `io`; passing the logger lets those report through the same channel.
+	const clients = makeIoredisClients(io, { logger });
 	if (lifecycleRegistrar) clientsCache.set(lifecycleRegistrar, clients);
 	return clients;
 }
 
+/**
+ * Reads an optional string field off a federation slice.
+ *
+ * A field the operator did not set stays absent rather than becoming
+ * `undefined`, so `"sessionDomain" in config` still distinguishes the two. A
+ * field that is present but not a string throws: HOCON hands through whatever
+ * shape the file holds, and silently ignoring `sessionDomain = 42` would leave
+ * the redirect policy running with one fewer constraint than the operator
+ * wrote down.
+ */
+function optionalString(
+	slice: Record<string, unknown>,
+	field: string,
+): Record<string, string> | Record<string, never> {
+	const value = slice[field];
+	if (value === undefined || value === null) return {};
+	if (typeof value !== "string") {
+		throw new Error(`federations.google.${field} must be a string when present`);
+	}
+	return { [field]: value };
+}
+
 /**
  * Google federation config bridge — supplies the typed `googleFederationConfig`
  * ComponentMap slot from the `config.federations.google` slice.
@@ -369,6 +620,15 @@ function getOrCreateClients(
  * Per `@o3co/auth-provider-federation-google` README. Per-federation modules
  * (Phase 7 A5) consume this slot; the bridge is the standalone composition
  * root's responsibility because the slot's content is consumer-specific.
+ *
+ * #278: this used to return `{ clientId, clientSecret, callbackURL }` and stop
+ * there, dropping `redirectAllowlist` / `sessionDomain` / `authCallbackUrl` /
+ * `clientUrl` on the floor. Nothing complained — `googleFederationModule` hands
+ * this same object to `createFederationRedirectPolicy`, so the redirect policy
+ * was built from a config with none of the fields it reads, and a deployment
+ * that had configured them ran as though it had not. The generated app is the
+ * shape most operators start from, so the safe path has to be the one that
+ * works by filling in the config file.
  */
 export const googleFederationConfigModule: Module = defineModule({
 	name: "standalone:google-federation-config",
@@ -393,7 +653,33 @@ export const googleFederationConfigModule: Module = defineModule({
 					"federations.google requires clientId, clientSecret, callbackURL when enabled",
 				);
 			}
-			return { clientId, clientSecret, callbackURL };
+
+			// The allowlist is checked for shape here and for content by
+			// `createFederationRedirectPolicy`, which owns the URL rules. This
+			// only has to establish that HOCON produced a list of strings —
+			// `redirectAllowlist = "https://…"` (a bare string, the natural typo)
+			// would otherwise reach the policy as a config it cannot read.
+			const rawAllowlist = slice.redirectAllowlist;
+			let redirectAllowlist: Record<string, readonly string[]> | Record<string, never> = {};
+			if (rawAllowlist !== undefined && rawAllowlist !== null) {
+				if (!Array.isArray(rawAllowlist) || rawAllowlist.some((e) => typeof e !== "string")) {
+					throw new Error(
+						"federations.google.redirectAllowlist must be a list of URL strings, " +
+							'e.g. ["https://app.example.com/welcome"]',
+					);
+				}
+				redirectAllowlist = { redirectAllowlist: rawAllowlist as readonly string[] };
+			}
+
+			return {
+				clientId,
+				clientSecret,
+				callbackURL,
+				...redirectAllowlist,
+				...optionalString(slice, "sessionDomain"),
+				...optionalString(slice, "authCallbackUrl"),
+				...optionalString(slice, "clientUrl"),
+			};
 		},
 	},
 });

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);
+}