@o3co/create-auth-policy-verifier 0.7.0 → 0.8.1

package/package.json

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

package/templates/standalone/README.ja.md

@@ -95,7 +95,13 @@ Authorization: Bearer <jwt>
 
 それ以外は body のパースより前に `401 { "decision": "deny", "code": "caller_unauthenticated", "message": "Caller authentication failed" }` を返します。`GET /_healthcheck` は常に非ゲートなので、コンテナの healthcheck はそのまま動作します。
 
-資格情報を未設定のままにする運用もサポートされており、ループバックであれば問題ありません。ループバック以外に bind した場合は起動時に `unauthenticated_non_loopback_bind` が warn で記録されます — 修正する価値があるのはこの組み合わせです。
+資格情報を未設定のままにする運用もサポートされており、ループバックであれば問題ありません。ループバック以外に bind した場合は起動時に `unauthenticated_non_loopback_bind` が warn で記録され、関係する 2 つの設定と何が晒されているかが示されます — 修正する価値があるのはこの組み合わせです。起動を拒否せず warn に留めているのは、ネットワーク側が正当な制御になっている場合があり、拒否すればアップグレード時に既存のコンテナデプロイをすべて壊すためです。
+
+**このテンプレートは初期状態でまさにその組み合わせです。** `docker-compose.yml` が `HTTP_HOSTNAME=0.0.0.0` を設定する一方、`HTTP_CALLER_AUTH_TOKEN` はどこにも設定されていません。したがって publish したポートがホスト外から到達できる状態で `docker compose up` すると、未認証の判定エンドポイントが公開されます。ローカル開発では問題なく、だからこそ warn に留めています。実トラフィックを流す前に、次のいずれかを行ってください。
+
+- **ポートをプライベートネットワークに置く。** セキュリティグループ、プライベートサブネット、Kubernetes の `NetworkPolicy` など、誰が接続してよいかを決める仕組みです。compose の `3000:3000` の publish はこれに該当しません — そのホストに到達できるすべてに到達を許します。
+- **`.env` に `HTTP_CALLER_AUTH_TOKEN` を設定する。** ポートに到達できるだけでは判定を要求できなくなります。攻撃者が既にネットワーク境界の内側にいる場合でも有効なのは、2 つのうちこちらだけです。なお Go の enforcement 層（[protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)）がこのヘッダを送るオプションを備えるのは**次のリリースから**です。それまで、同ライブラリを使う呼び出し元にはネットワーク側の制御が必要です。
+- **あるいは `HTTP_HOSTNAME` を外し、verifier をサイドカーとして動かす。** enforcement 層とネットワーク名前空間を共有すれば、ループバックで足ります。
 
 `GET /metrics` も非ゲートです。理由と、ループバック以外に bind したときに何を意味するかは [`/metrics` への到達方法](#metrics-への到達方法)を参照してください。
 

package/templates/standalone/README.md

@@ -96,7 +96,13 @@ Authorization: Bearer <jwt>
 
 Anything else gets `401 { "decision": "deny", "code": "caller_unauthenticated", "message": "Caller authentication failed" }`, decided before the body is parsed. `GET /_healthcheck` is never gated, so the container healthcheck keeps working.
 
-Leaving the credential unset is supported and is fine on loopback. On a non-loopback bind the server logs `unauthenticated_non_loopback_bind` at warn on boot — that combination is the one worth fixing.
+Leaving the credential unset is supported and is fine on loopback. On a non-loopback bind the server logs `unauthenticated_non_loopback_bind` at warn on boot, naming both settings and the exposure — that combination is the one worth fixing. It warns rather than refusing to boot: the network may legitimately be the control, and refusing would break every existing containerised deployment on upgrade.
+
+**This template is that combination out of the box.** `HTTP_HOSTNAME=0.0.0.0` is set in `docker-compose.yml` and `HTTP_CALLER_AUTH_TOKEN` is not set anywhere, so a `docker compose up` with the published port reachable from off-host is an unauthenticated decision endpoint. That is fine for local development and is why the warning is a warning. Before it carries traffic, do one of:
+
+- **Put the port on a private network.** A security group, a private subnet, a Kubernetes `NetworkPolicy` — something that decides who may connect. Publishing `3000:3000` from compose is not this: it reaches everything that can route to the host.
+- **Set `HTTP_CALLER_AUTH_TOKEN` in `.env`.** Then reaching the port is not enough to ask for a decision, which is the only one of the two that still holds against an attacker already inside the network boundary. Note that the Go enforcement layer ([protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)) gains the option to send this header **from its next release**; until then a caller built on it needs the network control instead.
+- **Or drop `HTTP_HOSTNAME` and run the verifier as a sidecar**, sharing a network namespace with the enforcement layer so loopback is enough.
 
 `GET /metrics` is not gated either — see [Reaching `/metrics`](#reaching-metrics) for why, and for what that means when the bind is not loopback.
 

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-policy-verifier-standalone",
-	"version": "0.7.0",
+	"version": "0.8.1",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",
@@ -19,7 +19,6 @@
 		"@o3co/auth.policy-verifier.core": "workspace:*",
 		"@o3co/auth.policy-verifier.builtins": "workspace:*",
 		"@o3co/auth.policy-verifier.server": "workspace:*",
-		"@o3co/auth.utils": "^0.0.4",
 		"@o3co/ts.hocon": "^1.13.0",
 		"express": "^5.2.1",
 		"pino": "^10.3.1"

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

@@ -0,0 +1,275 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shutdown was delegated to `@o3co/auth.utils@0.0.4`, whose guarantees no
+ * contract in this repository pinned.
+ *
+ * Reading its 22 lines answered the question and the answer was the reason to
+ * move it: **there was no force-close deadline**. `server.close()` waits for
+ * in-flight requests indefinitely, so one stuck decision meant the process
+ * never exited on its own and the orchestrator's SIGKILL took it down
+ * mid-flight. Its cleanup-failure path also wrote to `console.error`, a bare
+ * line in a composition root whose every other line is NDJSON (#107), and
+ * every exit was zero.
+ *
+ * The behaviour lives in the template now, with a deadline and the app's own
+ * logger, and these tests are the contract that was missing. `auth.provider`'s
+ * standalone template made the same move in its issue #290.
+ */
+import type { Server } from "node:http";
+import type { Logger } from "@o3co/auth.policy-verifier.core";
+import { describe, expect, it, vi } from "vitest";
+import { deferExit, installGracefulShutdown } from "../shutdown.js";
+
+/** 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,
+		finishDraining: () => closeCallback?.(),
+		failClose: (err: Error) => closeCallback?.(err),
+	};
+}
+
+/** A `Logger`-shaped spy, typed so a future port method cannot slip past. */
+const makeLogger = () => {
+	const spy = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: vi.fn(() => spy as unknown as Logger),
+	};
+	return spy satisfies Logger;
+};
+
+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 };
+}
+
+const settle = () => new Promise((resolve) => setImmediate(resolve));
+
+describe("installGracefulShutdown", () => {
+	it("listens for both SIGTERM and SIGINT", () => {
+		expect([...install().signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
+	});
+
+	it("stops accepting connections and releases idle keep-alive sockets", () => {
+		const { signals, spies } = install();
+		signals.get("SIGTERM")?.();
+		expect(spies.close).toHaveBeenCalledOnce();
+		expect(spies.closeIdleConnections).toHaveBeenCalledOnce();
+	});
+
+	it("runs cleanup once draining completes, then exits zero", async () => {
+		const cleanup = vi.fn();
+		const { signals, finishDraining, exit } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		expect(cleanup).not.toHaveBeenCalled();
+		finishDraining();
+		await settle();
+		expect(cleanup).toHaveBeenCalledOnce();
+		expect(exit).toHaveBeenCalledWith(0);
+	});
+
+	it("ignores a second signal instead of running cleanup twice", async () => {
+		const cleanup = vi.fn();
+		const { signals, spies, finishDraining, exit } = install({ cleanup });
+		const handler = signals.get("SIGTERM");
+		handler?.();
+		handler?.();
+		finishDraining();
+		await settle();
+		expect(spies.close).toHaveBeenCalledOnce();
+		expect(cleanup).toHaveBeenCalledOnce();
+		expect(exit).toHaveBeenCalledOnce();
+	});
+
+	it("forces the remaining connections closed when draining outruns the deadline", () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, spies } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+			vi.advanceTimersByTime(5_000);
+			expect(spies.closeAllConnections).toHaveBeenCalledOnce();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("exits non-zero on a forced close, so the drain outcome is visible", async () => {
+		vi.useFakeTimers();
+		let exitSpy: ReturnType<typeof vi.fn>;
+		try {
+			const { signals, exit } = install({ drainTimeoutMs: 5_000 });
+			exitSpy = exit;
+			signals.get("SIGTERM")?.();
+			vi.advanceTimersByTime(5_000);
+		} finally {
+			vi.useRealTimers();
+		}
+		await settle();
+		expect(exitSpy).toHaveBeenCalledWith(1);
+	});
+
+	it("does not force-close a drain that finished in time", () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, spies, finishDraining } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			vi.advanceTimersByTime(10_000);
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("reports a cleanup failure through the app logger, not console", async () => {
+		const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+		const err = new Error("collector teardown failed");
+		const { signals, finishDraining, logger, exit } = install({
+			cleanup: () => Promise.reject(err),
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(logger.error).toHaveBeenCalledWith({ err }, expect.stringContaining("cleanup failed"));
+		expect(consoleError).not.toHaveBeenCalled();
+		expect(exit).toHaveBeenCalledWith(1);
+		consoleError.mockRestore();
+	});
+
+	it("still exits when cleanup throws — a failed dispose must not wedge the process", async () => {
+		const { signals, finishDraining, exit } = install({
+			cleanup: () => {
+				throw new Error("boom");
+			},
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("does not report a failed close as a clean drain", async () => {
+		const err = new Error("Server is not running");
+		const { signals, failClose, logger, exit } = install();
+		signals.get("SIGTERM")?.();
+		failClose(err);
+		await settle();
+		expect(logger.error).toHaveBeenCalledWith({ err }, expect.stringContaining("close failed"));
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
+		// `finish` awaited cleanup with no deadline, and the drain deadline was
+		// already cleared by then, so a dispose that never settled meant `exit`
+		// was never reached — the wedge the deadline was added to remove.
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(logger.error).toHaveBeenCalledWith(
+				expect.objectContaining({ cleanupTimeoutMs: 5_000 }),
+				expect.stringContaining("cleanup timed out"),
+			);
+			expect(exit).toHaveBeenCalledWith(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not penalise a cleanup that finishes inside its budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => Promise.resolve(),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(10_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("defers the real exit a turn so pino's buffered destination can flush (#210 review)", async () => {
+		// `createAppLogger` uses pino's default (non-synchronous) destination, so
+		// exiting in the same tick as the last `logger.error` can drop exactly the
+		// `cleanup failed` line an operator would go looking for.
+		const exitProcess = vi.fn();
+		deferExit(3, exitProcess);
+		expect(exitProcess).not.toHaveBeenCalled();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(exitProcess).toHaveBeenCalledWith(3);
+	});
+
+	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
+		// `exitCode` became 1 while `reason` still said "drained", so the one line
+		// an operator alerts on contradicted itself. The drain outcome is still
+		// carried, under its own key, so neither fact is lost.
+		const { signals, finishDraining, logger, exit } = install({
+			cleanup: () => Promise.reject(new Error("teardown failed")),
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
+			"graceful shutdown: complete",
+		);
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("keeps reason and drain identical when cleanup succeeds", async () => {
+		const { signals, finishDraining, logger } = install({ cleanup: () => Promise.resolve() });
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "drained", drain: "drained", exitCode: 0 },
+			"graceful shutdown: complete",
+		);
+	});
+
+	it("removes its own signal listeners once shutting down", () => {
+		const { signals } = install();
+		signals.get("SIGTERM")?.();
+		expect(signals.size).toBe(0);
+	});
+});

package/templates/standalone/src/main.mts

@@ -7,9 +7,9 @@
 import { fileURLToPath } from "node:url";
 import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
 import { builtinKeyResolversModule, createApp } from "@o3co/auth.policy-verifier.server";
-import { gracefulShutdown } from "@o3co/auth.utils";
 import { loadAppConfig } from "./loadConfig.js";
 import { createAppLogger } from "./logger.js";
+import { installGracefulShutdown } from "./shutdown.js";
 
 const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
 const configDir = new URL("../config/", import.meta.url);
@@ -29,4 +29,4 @@ const server = app.listen(config.http.port, config.http.hostname, () => {
 	logger.info(`listening on http://${config.http.hostname}:${config.http.port}`);
 });
 
-gracefulShutdown(server);
+installGracefulShutdown(server, { logger });

package/templates/standalone/src/shutdown.ts

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Server } from "node:http";
+import type { Logger } from "@o3co/auth.policy-verifier.core";
+
+/**
+ * Graceful shutdown for the scaffolded server.
+ *
+ * ## Why this is in the template rather than a dependency
+ *
+ * It used to be `gracefulShutdown` from `@o3co/auth.utils@0.0.4`. For a
+ * component every protected call waits on, "does SIGTERM wait for in-flight
+ * decisions, 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 no
+ * contract here pinned. Reading it answered the question, and the answer was
+ * the reason to move it: **there was no deadline**. `server.close()` waits
+ * indefinitely, so one stuck decision 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 composition root that went to the trouble of wiring NDJSON (#107).
+ *
+ * `auth.provider`'s standalone template made the same move for the same
+ * reasons (o3co/auth.provider#290); keeping the two composition roots
+ * symmetric is what lets one aggregator pipeline serve the whole stack.
+ *
+ * ## The guarantees, stated
+ *
+ * 1. **SIGTERM and SIGINT** both start it; a second signal is ignored rather
+ *    than starting a second cleanup over the first one's work.
+ * 2. **New connections stop immediately** (`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 get `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**, logged through the app
+ *    logger and reflected in the exit code. It is bounded by
+ *    `cleanupTimeoutMs`, so a dispose that never settles cannot wedge the
+ *    process the way an unbounded `await` did.
+ * 6. **A `close` that fails is not reported as a clean drain.**
+ *
+ * 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;
+	/** Release what the composition holds — caches, clients, key resolvers. */
+	readonly cleanup?: () => void | Promise<void>;
+	/** How long in-flight requests get before connections are cut. Default 10s. */
+	readonly drainTimeoutMs?: number;
+	/**
+	 * How long `cleanup` gets before the shutdown gives up on it. Defaults to
+	 * `drainTimeoutMs`, so the worst-case shutdown is the two budgets in
+	 * sequence — size both against the orchestrator's grace period, not one.
+	 */
+	readonly cleanupTimeoutMs?: number;
+	/** Injected in tests; defaults to {@link deferExit}. */
+	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"];
+
+/**
+ * Exit after yielding the loop once.
+ *
+ * `createAppLogger` uses pino's default destination, which is not synchronous,
+ * so calling `process.exit` in the same tick as the last `logger.error` can
+ * drop exactly the lines that say why the shutdown failed. One turn is a flush
+ * window, not a guarantee: a deployment that needs certainty should pass an
+ * `exit` that flushes its own transport first.
+ */
+export function deferExit(code: number, exitProcess: (code: number) => void = process.exit): void {
+	setImmediate(() => exitProcess(code));
+}
+
+export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
+	const {
+		logger,
+		cleanup,
+		drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+		exit = deferExit,
+		onSignal = (signal, handler): void => {
+			process.on(signal, handler);
+		},
+		offSignal = (signal, handler): void => {
+			process.removeListener(signal, handler);
+		},
+	} = options;
+
+	const cleanupTimeoutMs = options.cleanupTimeoutMs ?? drainTimeoutMs;
+
+	let shuttingDown = false;
+	let finished = false;
+
+	/** Sentinel so a timed-out cleanup is reported as that, not as a throw. */
+	const CLEANUP_TIMED_OUT = Symbol("cleanup-timed-out");
+
+	/**
+	 * Await `cleanup`, but not forever. `cleanup()` is invoked inside the async
+	 * wrapper so a synchronous throw lands in the same rejection path as an
+	 * async one.
+	 */
+	const runCleanup = async (): Promise<typeof CLEANUP_TIMED_OUT | undefined> => {
+		if (!cleanup) return;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		try {
+			return await Promise.race([
+				(async (): Promise<undefined> => {
+					await cleanup();
+					return undefined;
+				})(),
+				new Promise<typeof CLEANUP_TIMED_OUT>((resolve) => {
+					timer = setTimeout(() => resolve(CLEANUP_TIMED_OUT), cleanupTimeoutMs);
+					timer.unref?.();
+				}),
+			]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	};
+
+	/** 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;
+		// `reason` names whatever decided the exit code, so the line an operator
+		// alerts on cannot say "drained" next to a non-zero code. The drain
+		// outcome keeps its own key rather than being overwritten — both facts
+		// are wanted, and a stable shape is what makes the line queryable.
+		let outcome = reason;
+		try {
+			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
+				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
+				exitCode = 1;
+				outcome = "cleanup-timeout";
+			}
+		} catch (err) {
+			// Through the app logger, not `console.error`: a shutdown that
+			// failed to release what it held 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;
+			outcome = "cleanup-failed";
+		}
+		logger.info({ reason: outcome, drain: 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,5 +1,5 @@
 {
-	"@o3co/auth.policy-verifier.core": "0.7.0",
-	"@o3co/auth.policy-verifier.builtins": "0.7.0",
-	"@o3co/auth.policy-verifier.server": "0.7.0"
+	"@o3co/auth.policy-verifier.core": "0.8.1",
+	"@o3co/auth.policy-verifier.builtins": "0.8.1",
+	"@o3co/auth.policy-verifier.server": "0.8.1"
 }