@o3co/create-auth-provider 0.16.0 → 0.17.0-rc.1

package/templates/standalone/src/__tests__/session-requirements.test.mts

@@ -0,0 +1,299 @@
+/*
+ * 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.
+ */
+
+/**
+ * The template's posture on session admission. What it expects is its
+ * configuration's `core.sessionRequirements.expected`
+ * — `[]` in the shipped `config/application.conf` — with `mfa` added when the
+ * template's MFA switch, `mfaMode` (`MFA_MODE`), is not `off`
+ * (`expectedSessionRequirements`); under that switch the template installs
+ * the MFA module, whose requirement registers `mfa`. And what it hands boot
+ * of the MFA module's section, `mfa`: nothing unless a loaded module owns it,
+ * its mode written from the switch when the template installs MFA, and a
+ * mode the configuration writes that the switch does not say refused.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BootError, type Module } from "@o3co/auth-provider-core";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import {
+	expectedSessionRequirements,
+	readOwnLayers,
+	readSwitches,
+	resolveForBoot,
+	resolveLayers,
+	type Switches,
+} from "../configPath.mjs";
+import {
+	type Composition,
+	compose,
+	ownFiles,
+	SINGLE_ENV,
+} from "./all-modules-composition.fixture.mjs";
+
+let current: Composition | undefined;
+
+afterEach(async () => {
+	await current?.handle.dispose();
+	current = undefined;
+});
+
+/** The boot's refusal, or `undefined` when it booted (kept for disposal). */
+const refusal = (composing: Promise<Composition>): Promise<unknown> =>
+	composing.then(
+		(composition) => {
+			current = composition;
+			return undefined;
+		},
+		(caught: unknown) => caught,
+	);
+
+/** What MFA on needs in production beside the switch: a key, and a mail relay. */
+const MFA_ENV: Readonly<Record<string, string>> = {
+	MFA_ENCRYPTION_KEY: Buffer.alloc(32, 9).toString("base64"),
+	STANDARD_SMTP_MAIL_SENDER_HOST: "smtp.auth.test",
+	STANDARD_SMTP_MAIL_SENDER_FROM: "auth@auth.test",
+};
+
+describe("what the template expects of session admission", () => {
+	it("is [] in the shipped configuration under MFA_MODE=off, and the composition boots with it", async () => {
+		const own = readOwnLayers(ownFiles(), { env: SINGLE_ENV });
+		expect(resolveLayers(own, []).core).toMatchObject({ sessionRequirements: { expected: [] } });
+		expect(readSwitches(own).mfaMode).toBe("off");
+		current = await compose();
+		expect(current.config).not.toHaveProperty("mfa");
+		expect(current.config.core?.sessionRequirements).toEqual({ expected: [] });
+		expect([...(current.handle.components.sessionRequirementResolver?.entries() ?? [])]).toEqual(
+			[],
+		);
+	});
+
+	it.each(["optional", "required"] as const)(
+		"adds mfa under MFA_MODE=%s, which the MFA module the template installs registers",
+		async (mode) => {
+			current = await compose({
+				env: { ...SINGLE_ENV, ...MFA_ENV, MFA_MODE: mode },
+				environment: "test",
+			});
+			expect(current.config.core?.sessionRequirements).toEqual({
+				expected: ["mfa"],
+				secondFactorAuthority: "mfa",
+			});
+			expect(
+				[...(current.handle.components.sessionRequirementResolver?.entries() ?? [])].map(
+					([name]) => name,
+				),
+			).toEqual(["mfa"]);
+		},
+	);
+
+	it("keeps an operator's own list and adds mfa beside it, overwriting nothing", async () => {
+		const err = await refusal(
+			compose({
+				env: { ...SINGLE_ENV, ...MFA_ENV, MFA_MODE: "required" },
+				environment: "test",
+				operatorHocon: 'core.sessionRequirements.expected = ["risk"]\n',
+			}),
+		);
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).reason).toBe("session-requirement-missing");
+		expect((err as BootError).details).toMatchObject({
+			missing: ["risk"],
+			declared: ["risk", "mfa"],
+		});
+	});
+
+	it("refuses the boot when the configuration expects mfa under the switch off: nothing registers it", async () => {
+		const err = await refusal(
+			compose({ operatorHocon: 'core.sessionRequirements.expected = ["mfa"]\n' }),
+		);
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).reason).toBe("session-requirement-missing");
+		expect((err as BootError).details).toMatchObject({
+			configKey: "core.sessionRequirements.expected",
+			missing: ["mfa"],
+		});
+	});
+});
+
+describe("what the template hands boot of the mfa section", () => {
+	const ownUnder = (env: Readonly<Record<string, string>>, hocon?: string) =>
+		readOwnLayers(hocon === undefined ? ownFiles() : [operatorLayer(hocon), ...ownFiles()], {
+			env,
+		});
+	/** A module whose section is `mfa`: resolveForBoot reads its name and section alone. */
+	const reader = { name: "mfa", section: {} } as unknown as Module;
+	const mfaOf = (resolved: unknown) => (resolved as { mfa?: unknown }).mfa;
+
+	it("hands none under the switch off unless a loaded module owns the section, whatever the configuration writes there", () => {
+		const own = ownUnder(SINGLE_ENV, 'mfa.page.url = "/my-mfa"\nmfa.mdoe = "required"\n');
+		const switches = readSwitches(own);
+		expect(resolveForBoot(own, [], switches)).not.toHaveProperty("mfa");
+		// A module the deployment adds that owns it: handed as written.
+		expect(mfaOf(resolveForBoot(own, [reader], switches))).toEqual({
+			page: { url: "/my-mfa" },
+			mdoe: "required",
+		});
+	});
+
+	it("hands it, owned by the MFA module the switch installs, with the mode written from the switch over the MFA package's default", () => {
+		for (const mode of ["optional", "required"] as const) {
+			// The switch written in a layer, MFA_MODE unset: the package's reference says off.
+			const { MFA_MODE: _unset, ...env } = SINGLE_ENV;
+			const own = ownUnder(env, `mfaMode = "${mode}"\n`);
+			const switches = readSwitches(own);
+			const modules = buildModules(switches, { environment: "test" });
+			expect(mfaOf(resolveForBoot(own, modules, switches)), mode).toMatchObject({ mode });
+		}
+	});
+
+	it.each([
+		["the switch off", {}, 'mfa.mode = "required"\n'],
+		["the switch off, the mode optional", {}, 'mfa.mode = "optional"\n'],
+		["MFA_MODE=optional", { MFA_MODE: "optional" }, 'mfa.mode = "required"\n'],
+		["MFA_MODE=required", { MFA_MODE: "required" }, 'mfa.mode = "optional"\n'],
+	])(
+		"refuses, under %s, an mfa.mode the configuration writes that the switch does not say, naming both keys and quoting nothing",
+		(_label, env, hocon) => {
+			const own = ownUnder({ ...SINGLE_ENV, ...env }, hocon);
+			const switches = readSwitches(own);
+			let err: unknown;
+			try {
+				resolveForBoot(own, [reader], switches);
+			} catch (caught) {
+				err = caught;
+			}
+			expect(err).toBeInstanceOf(RangeError);
+			const message = (err as RangeError).message;
+			expect(message).toContain("mfa.mode");
+			expect(message).toContain("mfaMode");
+			expect(message).not.toMatch(/"(?:off|optional|required)"/);
+		},
+	);
+
+	it.each([
+		["the switch off", {}],
+		["MFA_MODE=required", { MFA_MODE: "required" }],
+	])(
+		"refuses, under %s, an mfa written as a value, naming mfa itself and quoting nothing",
+		(_label, env) => {
+			const own = ownUnder({ ...SINGLE_ENV, ...env }, 'mfa = "required"\n');
+			let err: unknown;
+			try {
+				resolveForBoot(own, [reader], readSwitches(own));
+			} catch (caught) {
+				err = caught;
+			}
+			expect(err).toBeInstanceOf(RangeError);
+			const message = (err as RangeError).message;
+			expect(message).toMatch(/^mfa is written as a value/);
+			expect(message).not.toContain("remove mfa.mode");
+			expect(message).toContain("mfaMode");
+			expect(message).not.toMatch(/"(?:off|optional|required)"/);
+		},
+	);
+
+	it("accepts an mfa.mode the configuration writes that the switch says", () => {
+		for (const [env, hocon] of [
+			[{}, 'mfa.mode = "off"\n'],
+			[{ MFA_MODE: "required" }, 'mfa.mode = "required"\n'],
+		] as const) {
+			const own = ownUnder({ ...SINGLE_ENV, ...env }, hocon);
+			expect(() => resolveForBoot(own, [reader], readSwitches(own)), hocon).not.toThrow();
+		}
+	});
+
+	it("is refused through the composition as through phase two: before boot, under the switch off", async () => {
+		const err = await refusal(compose({ operatorHocon: 'mfa.mode = "required"\n' }));
+		expect(err).toBeInstanceOf(RangeError);
+		expect(err).not.toBeInstanceOf(BootError);
+		expect((err as RangeError).message).toContain("mfaMode");
+	});
+});
+
+describe("expectedSessionRequirements", () => {
+	const of = (mfa: string, expected?: readonly string[], authority?: string) =>
+		expectedSessionRequirements({
+			mfaMode: mfa,
+			...(expected === undefined && authority === undefined
+				? {}
+				: {
+						core: {
+							sessionRequirements: {
+								...(expected === undefined ? {} : { expected }),
+								...(authority === undefined ? {} : { secondFactorAuthority: authority }),
+							},
+						},
+					}),
+		} as unknown as Switches);
+	const AUTHORITY = { secondFactorAuthority: "mfa" } as const;
+
+	it("is the configuration's list, with mfa added once and named the second-factor authority when the switch is not off", () => {
+		expect(of("off", ["risk"])).toEqual({ expected: ["risk"] });
+		expect(of("optional", ["risk"])).toEqual({ expected: ["risk", "mfa"], ...AUTHORITY });
+		expect(of("required", ["mfa"])).toEqual({ expected: ["mfa"], ...AUTHORITY });
+		expect(of("required")).toEqual({ expected: ["mfa"], ...AUTHORITY });
+	});
+
+	it("keeps the configuration's list as written, repeats included, and adds mfa only when it is absent", () => {
+		expect(of("required", ["risk", "risk"])).toEqual({
+			expected: ["risk", "risk", "mfa"],
+			...AUTHORITY,
+		});
+		expect(of("required", ["mfa", "risk", "mfa"])).toEqual({
+			expected: ["mfa", "risk", "mfa"],
+			...AUTHORITY,
+		});
+		expect(of("off", ["risk", "risk"])).toEqual({ expected: ["risk", "risk"] });
+	});
+
+	it("accepts a written second-factor authority the switch says, and keeps one written under the switch off", () => {
+		expect(of("required", ["mfa"], "mfa")).toEqual({ expected: ["mfa"], ...AUTHORITY });
+		expect(of("off", ["risk"], "risk")).toEqual({
+			expected: ["risk"],
+			secondFactorAuthority: "risk",
+		});
+	});
+
+	it("refuses, with the switch on, a written second-factor authority other than mfa, naming the key and the switch and quoting nothing", () => {
+		let err: unknown;
+		try {
+			of("required", ["mfa", "sentinel-requirement"], "sentinel-requirement");
+		} catch (caught) {
+			err = caught;
+		}
+		expect(err).toBeInstanceOf(RangeError);
+		const message = (err as RangeError).message;
+		expect(message).toContain("core.sessionRequirements.secondFactorAuthority");
+		expect(message).toContain("mfaMode");
+		expect(message).toContain("MFA_MODE");
+		expect(message).not.toContain("sentinel-requirement");
+	});
+
+	it("declares nothing when the configuration writes no list and the switch is off, so boot's own rule for an unwritten key applies", () => {
+		expect(of("off")).toBeUndefined();
+	});
+});
+
+/** `text` in a file of its own, a layer above the composition's files. */
+function operatorLayer(text: string): string {
+	const file = join(mkdtempSync(join(tmpdir(), "session-requirements-")), "operator.conf");
+	writeFileSync(file, text);
+	return file;
+}

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

@@ -15,19 +15,11 @@
  */
 
 /**
- * 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.
+ * The contract of the template's graceful shutdown (README, "Shutdown
+ * guarantees"): a force-close deadline on the drain, a bounded cleanup, and
+ * every stage logged through the app's own logger. `server.close()` alone
+ * waits for in-flight requests indefinitely, so one stuck request would keep
+ * the process up until the orchestrator's SIGKILL took it down mid-flight.
  */
 
 import { createServer, type Server } from "node:http";
@@ -40,13 +32,7 @@ import {
 } from "@o3co/auth-provider-core";
 import { makeValidCoreConfig } from "@o3co/auth-provider-core/testing";
 import { describe, expect, it, vi } from "vitest";
-import {
-	cleanupAllowanceFor,
-	deferExit,
-	FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
-	FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
-	installGracefulShutdown,
-} from "../shutdown.mjs";
+import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
 
 /** A `Server` double whose `close` callback fires only when we say so. */
 function makeServer() {
@@ -74,8 +60,7 @@ function makeServer() {
 
 /**
  * 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`.
+ * mismatch the day the port gains a method.
  */
 const makeLogger = () => {
 	const spy = {
@@ -134,6 +119,7 @@ function install(
 		cleanup?: () => void | Promise<void>;
 		drainTimeoutMs?: number;
 		cleanupTimeoutMs?: number;
+		cleanupAllowanceMs?: () => number | undefined;
 		logger?: ReturnType<typeof makeLogger>;
 	} = {},
 ) {
@@ -147,6 +133,9 @@ function install(
 		cleanup: opts.cleanup ?? (() => {}),
 		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
 		...(opts.cleanupTimeoutMs === undefined ? {} : { cleanupTimeoutMs: opts.cleanupTimeoutMs }),
+		...(opts.cleanupAllowanceMs === undefined
+			? {}
+			: { cleanupAllowanceMs: opts.cleanupAllowanceMs }),
 		exit,
 		onSignal: (name, handler) => signals.set(name, handler),
 		offSignal: (name) => signals.delete(name),
@@ -155,7 +144,7 @@ function install(
 	return { spies, logger, exit, signals, finishDraining, failClose };
 }
 
-describe("installGracefulShutdown (#290)", () => {
+describe("installGracefulShutdown", () => {
 	it("listens for both SIGTERM and SIGINT", async () => {
 		const { signals } = install();
 		expect([...signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
@@ -192,7 +181,6 @@ describe("installGracefulShutdown (#290)", () => {
 		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 {
@@ -217,7 +205,10 @@ describe("installGracefulShutdown (#290)", () => {
 			await vi.advanceTimersByTimeAsync(5_000);
 			expect(exit).toHaveBeenCalledWith(1);
 			// Each stage is an event: object-first, a snake_case name.
-			expect(logger.info).toHaveBeenCalledWith({ drainTimeoutMs: 5_000 }, "shutdown_draining");
+			expect(logger.info).toHaveBeenCalledWith(
+				{ drainTimeoutMs: 5_000, cleanupTimeoutMs: 5_000 },
+				"shutdown_draining",
+			);
 			expect(logger.error).toHaveBeenCalledWith(
 				{ drainTimeoutMs: 5_000 },
 				"shutdown_drain_deadline_exceeded",
@@ -385,11 +376,9 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 
 	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
-		// The guarantees above say cleanup "never wedges the process", but `finish`
-		// awaited it with no deadline — and the drain deadline is already cleared
-		// by then, so a dispose that never settles meant `exit` was never reached.
-		// The same defect was found in auth.proxy#81 and auth.policy-verifier#210,
-		// both of which took this file as their starting point.
+		// The drain deadline is already cleared when cleanup runs, so without a
+		// deadline of its own a dispose that never settles would keep `exit`
+		// from ever being reached.
 		vi.useFakeTimers();
 		try {
 			const { signals, finishDraining, exit, logger } = install({
@@ -437,9 +426,9 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 
 	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.
+		// `reason` must agree with `exitCode` on the one line an operator alerts
+		// on. The drain outcome is carried under its own key, so neither fact is
+		// lost.
 		const { signals, finishDraining, logger, exit } = install({
 			cleanup: () => Promise.reject(new Error("teardown failed")),
 		});
@@ -473,81 +462,159 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 });
 
-describe("#593 slice 7: the cleanup allowance federation grants need", () => {
-	it("is at least the 45 seconds the package asks for, and only when the feature is on", () => {
-		// The package's drain waits for a rotated credential's write; the
-		// default cleanup budget is the ten-second drain, which is shorter than
-		// the upstream hard timeout and persist budget the feature ships with —
-		// a shutdown under it abandons exactly the write the drain exists for.
-		expect(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS).toBeGreaterThanOrEqual(45_000);
-		expect(cleanupAllowanceFor({ federationGrants: { enabled: true } })).toEqual({
-			cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
-		});
-		// Off, nothing: the cleanup budget stays the drain's, as it was.
-		expect(cleanupAllowanceFor({ federationGrants: { enabled: false } })).toEqual({});
-		expect(cleanupAllowanceFor({})).toEqual({});
+describe("the cleanup allowance the handle reports", () => {
+	it("gives cleanup the allowance when it is longer than the drain", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
+				drainTimeoutMs: 5_000,
+				cleanupAllowanceMs: () => 45_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(31_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
 	});
 
-	it("grows with the configured refresh tail, so a raised budget is not cut off by a fixed timer (Copilot, #614)", () => {
-		// The longest tail one refresh has: the upstream hard timeout, the
-		// persist budget and the wait for the lock, back to back, plus an exit
-		// margin. The shipped budgets (25 s + 3 s + 5 s) land exactly on the
-		// floor; a deployment that doubles its upstream timeout gets more.
-		const shipped = {
-			upstreamHardTimeoutMs: 25_000,
-			persistRetryBudgetMs: 3_000,
-			lockWaitMs: 5_000,
-		};
-		expect(
-			25_000 + 3_000 + 5_000 + FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
-			"the margin is what makes the shipped budgets the floor",
-		).toBe(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS);
-		expect(cleanupAllowanceFor({ federationGrants: { enabled: true, ...shipped } })).toEqual({
-			cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
-		});
-		expect(
-			cleanupAllowanceFor({
-				federationGrants: { enabled: true, ...shipped, upstreamHardTimeoutMs: 60_000 },
-			}),
-		).toEqual({ cleanupTimeoutMs: 60_000 + 3_000 + 5_000 + FEDERATION_GRANTS_CLEANUP_MARGIN_MS });
-		// Lowered budgets never go below the documented minimum, and a config
-		// without budgets (built by hand) gets the floor rather than a guess.
-		expect(
-			cleanupAllowanceFor({
-				federationGrants: { enabled: true, ...shipped, upstreamHardTimeoutMs: 1_000 },
-			}),
-		).toEqual({ cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS });
-		expect(
-			cleanupAllowanceFor({ federationGrants: { enabled: true, upstreamHardTimeoutMs: 90_000 } }),
-		).toEqual({ cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS });
+	it("gives up on cleanup at the allowance, and logs it as the budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+				cleanupAllowanceMs: () => 45_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(44_999);
+			expect(exit).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(1);
+			expect(logger.error).toHaveBeenCalledWith(
+				{ cleanupTimeoutMs: 45_000 },
+				"shutdown_cleanup_timed_out",
+			);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
+		} finally {
+			vi.useRealTimers();
+		}
 	});
 
-	it("never asks a timer for more than Node can count: an oversized sum is capped, not overflowed (Copilot, #614)", () => {
-		// setTimeout takes a 32-bit signed delay; past it the timer fires after
-		// about a millisecond, which would turn a generous allowance into none.
-		const oversized = cleanupAllowanceFor({
-			federationGrants: {
-				enabled: true,
-				upstreamHardTimeoutMs: 2_000_000_000,
-				persistRetryBudgetMs: 2_000_000_000,
-				lockWaitMs: 5_000,
-			},
-		});
-		expect(oversized).toEqual({ cleanupTimeoutMs: 2_147_483_647 });
+	it("keeps the longer budget when the allowance is shorter", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+				cleanupAllowanceMs: () => 2_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(4_999);
+			expect(exit).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(1);
+			expect(logger.error).toHaveBeenCalledWith(
+				{ cleanupTimeoutMs: 5_000 },
+				"shutdown_cleanup_timed_out",
+			);
+		} finally {
+			vi.useRealTimers();
+		}
 	});
 
-	it("is honoured by the shutdown: a cleanup that needs longer than the drain is given it", async () => {
+	it("leaves cleanup its own budget when the handle reports no allowance", async () => {
 		vi.useFakeTimers();
 		try {
-			const { signals, finishDraining, exit } = install({
-				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
+			const { signals, finishDraining, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
 				drainTimeoutMs: 5_000,
-				...cleanupAllowanceFor({ federationGrants: { enabled: true } }),
+				cleanupAllowanceMs: () => undefined,
 			});
 			signals.get("SIGTERM")?.();
 			finishDraining();
-			await vi.advanceTimersByTimeAsync(31_000);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(logger.error).toHaveBeenCalledWith(
+				{ cleanupTimeoutMs: 5_000 },
+				"shutdown_cleanup_timed_out",
+			);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("reads the allowance when the signal arrives, so a tail registered after install counts", async () => {
+		vi.useFakeTimers();
+		try {
+			let allowance: number | undefined;
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+				cleanupAllowanceMs: () => allowance,
+			});
+			allowance = 60_000;
+			signals.get("SIGTERM")?.();
+			expect(logger.info).toHaveBeenCalledWith(
+				{ drainTimeoutMs: 5_000, cleanupTimeoutMs: 60_000 },
+				"shutdown_draining",
+			);
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(59_999);
+			expect(exit).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(1);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it.each([Number.NaN, Number.POSITIVE_INFINITY, -1, 0, 1.5, 2_147_483_648])(
+		"treats an allowance of %s as absent: cleanup keeps its own budget",
+		async (allowance) => {
+			// Handed to a timer, NaN or a delay past 2147483647 fires after about a
+			// millisecond, which would turn the floor into no budget at all.
+			vi.useFakeTimers();
+			try {
+				const { signals, finishDraining, exit, logger } = install({
+					cleanup: () => new Promise<void>(() => {}),
+					drainTimeoutMs: 5_000,
+					cleanupAllowanceMs: () => allowance,
+				});
+				signals.get("SIGTERM")?.();
+				finishDraining();
+				await vi.advanceTimersByTimeAsync(4_999);
+				expect(exit).not.toHaveBeenCalled();
+				await vi.advanceTimersByTimeAsync(1);
+				expect(logger.error).toHaveBeenCalledWith(
+					{ cleanupTimeoutMs: 5_000 },
+					"shutdown_cleanup_timed_out",
+				);
+			} finally {
+				vi.useRealTimers();
+			}
+		},
+	);
+
+	it("treats an allowance that cannot be read as absent, and still shuts down", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+				cleanupAllowanceMs: () => {
+					throw new Error("allowance unavailable");
+				},
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(logger.error).toHaveBeenCalledWith(
+				{ cleanupTimeoutMs: 5_000 },
+				"shutdown_cleanup_timed_out",
+			);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
 		} finally {
 			vi.useRealTimers();
 		}