@o3co/create-auth-provider 0.9.0 → 0.11.0

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

@@ -0,0 +1,231 @@
+/*
+ * 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 { request as httpRequest } from "node:http";
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { createMetrics } from "../metrics.mjs";
+
+function buildApp(probes: Parameters<ReturnType<typeof createMetrics>["route"]>[1]["probes"] = []) {
+	const metrics = createMetrics();
+	const app = express();
+	app.use(metrics.middleware);
+	app.use(metrics.route(express, { probes, probeTimeoutMs: 100 }));
+
+	const api = express.Router();
+	api.get("/widgets/:id", (_req, res) => {
+		res.status(200).json({ ok: true });
+	});
+	api.get("/boom", (_req, res) => {
+		res.status(500).json({ ok: false });
+	});
+	app.use("/api", api);
+	return app;
+}
+
+describe("GET /metrics", () => {
+	it("serves the Prometheus text exposition format", async () => {
+		const res = await request(buildApp()).get("/metrics");
+
+		expect(res.status).toBe(200);
+		expect(res.headers["content-type"]).toContain("text/plain");
+		// Node process defaults are namespaced so they cannot collide with
+		// anything else scraped from the same job.
+		expect(res.text).toContain("auth_provider_process_cpu_user_seconds_total");
+	});
+
+	it("records latency by method, route and status", async () => {
+		const app = buildApp();
+		await request(app).get("/api/widgets/42");
+		await request(app).get("/api/boom");
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('route="/api/widgets/:id"');
+		expect(res.text).toContain('status="200"');
+		expect(res.text).toContain('status="500"');
+	});
+
+	it("labels by the route pattern, not the URL, so the label set stays bounded", async () => {
+		// Labelling by path would mint a series per id and eventually take down
+		// the system that is supposed to be watching this one.
+		const app = buildApp();
+		for (const id of ["1", "2", "3"]) {
+			await request(app).get(`/api/widgets/${id}`);
+		}
+
+		const res = await request(app).get("/metrics");
+		const series = res.text
+			.split("\n")
+			.filter((l) => l.startsWith("http_request_duration_seconds_count"));
+
+		expect(series.some((l) => l.includes('route="/api/widgets/:id"'))).toBe(true);
+		expect(res.text).not.toContain('route="/api/widgets/1"');
+	});
+
+	it("collapses unmatched requests into a single bucket", async () => {
+		// 404 probes from the internet carry attacker-chosen paths.
+		const app = buildApp();
+		await request(app).get(`/nope/${"x".repeat(50)}`);
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('route="unmatched"');
+		expect(res.text).not.toContain("xxxxx");
+	});
+
+	it("collapses unknown HTTP methods into one label", async () => {
+		// req.method is attacker-controlled — Node's HTTP parser accepts any
+		// valid token, so `FOO` and `M000001` arrive as readily as `GET`. An
+		// unbounded method label is the same cardinality bomb as an unbounded
+		// route label, reachable without any access to /metrics. Sent over a real
+		// socket because supertest cannot express a non-standard method.
+		const app = buildApp();
+		const server = app.listen(0);
+		const port = (server.address() as { port: number }).port;
+		try {
+			for (const method of ["FOO", "M000001", "PURGE"]) {
+				await new Promise<void>((resolve) => {
+					const req = httpRequest(
+						{ host: "127.0.0.1", port, path: "/api/widgets/1", method },
+						(res) => {
+							res.resume();
+							res.once("end", resolve);
+						},
+					);
+					req.once("error", () => resolve());
+					req.end();
+				});
+			}
+
+			const res = await request(app).get("/metrics");
+
+			expect(res.text).toContain('method="other"');
+			expect(res.text).not.toContain('method="M000001"');
+			expect(res.text).not.toContain('method="FOO"');
+		} finally {
+			server.close();
+		}
+	});
+
+	it("counts a request whose client disconnects before the response finishes", async () => {
+		// `close` fires without `finish` when a client or proxy gives up
+		// mid-handler, and those are disproportionately the slow and failing
+		// requests RED metrics exist to surface.
+		const metrics = createMetrics();
+		const app = express();
+		app.use(metrics.middleware);
+		app.use(metrics.route(express, { probes: [], probeTimeoutMs: 100 }));
+		app.get("/slow", (_req, res) => {
+			// Never responds; the test aborts the socket instead.
+			void res;
+		});
+
+		const server = app.listen(0);
+		const port = (server.address() as { port: number }).port;
+		try {
+			const controller = new AbortController();
+			const pending = fetch(`http://127.0.0.1:${port}/slow`, {
+				signal: controller.signal,
+			}).catch(() => undefined);
+			await new Promise((resolve) => setTimeout(resolve, 30));
+			controller.abort();
+			await pending;
+			await new Promise((resolve) => setTimeout(resolve, 30));
+
+			const res = await request(app).get("/metrics");
+			const slow = res.text
+				.split("\n")
+				.filter((l) => l.startsWith("http_request_duration_seconds_count"))
+				.filter((l) => l.includes('route="/slow"'));
+			expect(slow.length).toBeGreaterThan(0);
+		} finally {
+			server.close();
+		}
+	});
+
+	it("observes a response exactly once even though both finish and close fire", async () => {
+		const app = buildApp();
+		await request(app).get("/api/widgets/1");
+
+		const res = await request(app).get("/metrics");
+		const line = res.text
+			.split("\n")
+			.find(
+				(l) =>
+					l.startsWith("http_request_duration_seconds_count") &&
+					l.includes('route="/api/widgets/:id"'),
+			);
+		expect(line?.trim().endsWith(" 1")).toBe(true);
+	});
+
+	it("publishes a per-dependency gauge from the readiness probes", async () => {
+		const app = buildApp([
+			{ name: "redis", check: async () => "PONG" },
+			{
+				name: "session-store",
+				check: async () => {
+					throw new Error("ECONNREFUSED");
+				},
+			},
+		]);
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('auth_dependency_up{dependency="redis"} 1');
+		expect(res.text).toContain('auth_dependency_up{dependency="session-store"} 0');
+	});
+
+	it("re-samples dependencies on every scrape instead of caching a verdict", async () => {
+		let healthy = true;
+		const app = buildApp([
+			{
+				name: "redis",
+				check: async () => {
+					if (!healthy) throw new Error("down");
+					return "PONG";
+				},
+			},
+		]);
+
+		expect((await request(app).get("/metrics")).text).toContain(
+			'auth_dependency_up{dependency="redis"} 1',
+		);
+		healthy = false;
+		expect((await request(app).get("/metrics")).text).toContain(
+			'auth_dependency_up{dependency="redis"} 0',
+		);
+	});
+
+	it("joins an in-flight probe rather than issuing one per scrape", async () => {
+		// A partitioned backend never answers, and a scrape loop would otherwise
+		// stack one command per scrape against the dependency already in trouble.
+		const check = vi.fn(() => new Promise(() => {}));
+		const app = buildApp([{ name: "redis", check }]);
+
+		await request(app).get("/metrics");
+		await request(app).get("/metrics");
+
+		expect(check).toHaveBeenCalledTimes(1);
+	});
+
+	it("is never cached", async () => {
+		const res = await request(buildApp()).get("/metrics");
+
+		expect(res.headers["cache-control"]).toBe("no-store");
+	});
+});

package/templates/standalone/src/__tests__/refresh-token-family-client-module.test.mts

@@ -31,6 +31,7 @@ vi.mock("ioredis", () => {
 		}
 		on = vi.fn();
 		quit = vi.fn(async () => "OK" as const);
+		ping = vi.fn(async () => "PONG" as const);
 		// Minimal command surface — `makeIoredisClients` only invokes these
 		// during construction in some paths; tests never exercise the wrapped
 		// client itself, so most stubs are unused.
@@ -168,7 +169,50 @@ describe("D-2 / standaloneRedisClientsModule", () => {
 		expect(onSpies[0]).toHaveBeenCalledWith("error", expect.any(Function));
 	});
 
-	it("declares 'config' as required and 'lifecycleRegistrar' as optional", async () => {
+	it("bounds every command and every connect attempt (#286)", async () => {
+		// Without these the driver's defaults apply: no command timeout at all,
+		// a 10s connect timeout, and 20 reconnect attempts before a queued
+		// command is failed. A partition therefore parks in-flight `/token`
+		// requests indefinitely instead of erroring, which is what stops the
+		// fail-closed rate-limit policy from ever shedding load.
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		const options = redisCtorCalls[0]?.options;
+		expect(options?.commandTimeout).toBe(1_000);
+		expect(options?.connectTimeout).toBe(5_000);
+		expect(options?.maxRetriesPerRequest).toBe(3);
+		// `lazyConnect: false` is the driver default, but it is declared in
+		// SHARED_REDIS_TIMEOUTS as a load-bearing decision (connect at boot,
+		// not at first command) — pin it so a future flip has to come here.
+		expect(options?.lazyConnect).toBe(false);
+	});
+
+	it("keeps the offline queue ON, explicitly, because one socket serves every purpose (#286)", async () => {
+		// `enableOfflineQueue` is a per-CONNECTION option and every adapter in
+		// this template draws from the single socket built below, so the
+		// "off for the rate limiter, on elsewhere" split is not expressible
+		// here. Asserting the explicit `true` rather than accepting the
+		// driver default is the point: the value is a decision (see the
+		// comment in `getOrCreateClients`), and a future change that wants
+		// `false` has to come through this test.
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		expect(redisCtorCalls[0]?.options?.enableOfflineQueue).toBe(true);
+	});
+
+	it("declares 'config' as required and both registrars as optional", async () => {
 		const { standaloneRedisClientsModule } = await importModule();
 		const m = standaloneRedisClientsModule as {
 			requires?: readonly string[];
@@ -176,5 +220,36 @@ describe("D-2 / standaloneRedisClientsModule", () => {
 		};
 		expect(m.requires).toContain("config");
 		expect(m.optional).toContain("lifecycleRegistrar");
+		expect(m.optional).toContain("readinessRegistrar");
+	});
+
+	it("registers one readiness probe for the shared connection, not one per slot", async () => {
+		// Every Redis-backed adapter draws from a single socket, so a probe per
+		// consumed slot would report the same connection six times.
+		const probes: Array<{ name: string; check: () => Promise<unknown> }> = [];
+		const readinessRegistrar = { register: (p: (typeof probes)[number]) => probes.push(p) };
+
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		const lifecycleRegistrar: LifecycleRegistrar = { register: () => {} };
+
+		await provides.refreshTokenFamilyClient({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+			readinessRegistrar,
+		});
+		await provides.rateLimiterClient({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+			readinessRegistrar,
+		});
+
+		expect(redisCtorCalls).toHaveLength(1);
+		expect(probes.map((p) => p.name)).toEqual(["redis"]);
+		await expect(probes[0]?.check()).resolves.toBe("PONG");
 	});
 });

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