@o3co/create-auth-provider 0.14.0 → 0.15.0

package/templates/standalone/src/__tests__/federation-grants-survive-logout.test.mts

@@ -0,0 +1,431 @@
+/*
+ * 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.
+ */
+
+/**
+ * #593 acceptance criterion 8, at the two HTTP logout endpoints (D14).
+ *
+ * A federation grant outlives the session it was agreed through. The proof of
+ * that used to be a direct call to `cascadeLogout()` — which is the cascade
+ * `/oauth/logout` runs, and not what `/session/logout` runs: that endpoint has
+ * its own record hygiene (`invalidateSessionRecords`) and reaches the grant
+ * store on no path, by construction. A proof of the helper is not a proof of
+ * the endpoints. So this drives both, on the standalone, as a deployment
+ * composes them: a grant seeded beside a live browser session, the session's
+ * records gone afterwards, the grant and its credential exactly as they were,
+ * and `/token` still disclosing.
+ *
+ * The seeded grant's access token is fresh, so the disclosure is the cached
+ * one and no upstream is asked — the OIDC federation the connection names is
+ * configured with `discovery = false` and hand-typed endpoints so that the
+ * deployment boots without a network.
+ */
+
+import { createHmac } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	type FederationTokenStore,
+	federationGrantAuthorizationRevision,
+	federationGrantIdentityRevision,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	type MemoryFederationGrantStore,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+	type UserSessionStore,
+} from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+
+const DAY = 86_400_000;
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+const ISSUER = "https://auth.test";
+const JWT_SECRET = "federation-grants-survive-logout.at-least-32-bytes.ok";
+const UPSTREAM = "https://issuer.example";
+const UPSTREAM_CLIENT_ID = "provider-client";
+const ENCRYPTION_KEY = Buffer.alloc(32, 9).toString("base64");
+
+const CLIENT_ID = "worker";
+const CLIENT_SECRET = "worker-secret-value";
+const BASIC = `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`;
+const USERNAME = "alice";
+const PASSWORD = "correct-horse-battery-staple";
+const SUB = "u-alice";
+
+const CONNECTION = "calendar";
+const SCOPES: readonly string[] = ["openid", "offline_access", "calendar.read"];
+const BOUNDARY = "production";
+const GRANT_ID = "g-1";
+const REFRESH_TOKEN = "SENTINEL-refresh-token";
+const ACCESS_TOKEN = "upstream-access-token";
+
+const ENV: Readonly<Record<string, string>> = {
+	OAUTH_JWT_ALGORITHM: "HS256",
+	OAUTH_JWT_SECRET: JWT_SECRET,
+	OAUTH_JWT_ISSUER: ISSUER,
+	SESSION_SECRET: "federation-grants-survive-logout-session.at-least-32-bytes.ok",
+	SESSION_SECURE: "false",
+	SESSION_NAME: "auth.session",
+	SESSION_STORAGE_TYPE: "memory",
+	CLIENT_USER_TYPE: "yaml",
+	REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "redis://redis.test:6379",
+	USER_SESSION_STORES_ADAPTER: "memory",
+	RATE_LIMITER_ADAPTER: "memory",
+	OAUTH_CODE_ADAPTER: "memory",
+	ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+	REPLAY_SEEN_SET_ADAPTER: "memory",
+	FEDERATION_TOKEN_STORE_TYPE: "memory",
+	CONSENT_STORE_ADAPTER: "none",
+	FEDERATION_GRANT_STORE_ADAPTER: "memory",
+	FEDERATION_GRANT_INTENT_STORE_ADAPTER: "memory",
+	FEDERATION_GRANTS_ENABLED: "true",
+	FEDERATION_GRANTS_CONSENT_URL: "/consent/grants",
+	// The connect flow is not driven here, and the bundled repository has no
+	// identity lookup; "unsupported" is the declaration a deployment without one
+	// makes (#613), and what lets a connection be configured at all.
+	FEDERATION_GRANTS_IDENTITY_LOOKUP: "unsupported",
+};
+
+/**
+ * The shipped configuration under the environment above, with the two lists
+ * that have no environment form (comment 9 on #593) written over it: the
+ * upstream federation the connection names, and the connection.
+ */
+function resolveConfig(): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	const config = validate(
+		parseFile(envConfPath, { env: ENV })
+			.withFallback(parseFile(applicationConfPath, { env: ENV }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env: ENV })),
+		AppConfigSchema,
+	);
+	return {
+		...config,
+		federations: {
+			...config.federations,
+			upstream: {
+				enabled: true,
+				type: "oidc",
+				issuer: UPSTREAM,
+				clientId: UPSTREAM_CLIENT_ID,
+				clientSecret: "provider-secret",
+				callbackURL: `${ISSUER}/session/oauth/federation/upstream/callback`,
+				scopes: [...SCOPES],
+				discovery: false,
+				endpoints: {
+					authorizationEndpoint: `${UPSTREAM}/authorize`,
+					tokenEndpoint: `${UPSTREAM}/token`,
+					jwksUri: `${UPSTREAM}/jwks`,
+				},
+				redirectAllowlist: [],
+			},
+		},
+		federationGrants: {
+			...config.federationGrants,
+			encryptionKeys: [{ id: "k-test", key: ENCRYPTION_KEY }],
+			connections: {
+				[CONNECTION]: {
+					federation: "upstream",
+					scopes: [...SCOPES],
+					boundary: BOUNDARY,
+					maxAccessTokenLifetime: 3600,
+					callbackURL: `${ISSUER}/session/federation-grants/callback/${CONNECTION}`,
+				},
+			},
+		},
+	} as AppConfig;
+}
+
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: CLIENT_SECRET,
+							allowedRedirectUris: [],
+							allowedScopes: ["openid", "profile"],
+							allowedAudiences: [],
+							allowedGrantTypes: ["session"],
+							backchannelLogoutSessionRequired: true,
+							frontchannelLogoutSessionRequired: true,
+							allowedAzpForFederationToken: false,
+							allowedFederationGrantConnections: [CONNECTION],
+						},
+					],
+				]),
+			),
+		userRepository: () =>
+			new InMemoryUserRepository(
+				new Map([[USERNAME, { id: SUB, password: PASSWORD, email: "alice@example.com" }]]),
+			),
+	} as never,
+});
+
+const testKeyStoreModule = defineModule({
+	name: "test:key-store",
+	requires: ["config"] as const,
+	provides: {
+		keyStore: async ({ config: c }) => {
+			const factory = createKeyStoreFactory();
+			registerBuiltinKeyStores(factory);
+			return factory.create({
+				type: "local",
+				...((c as AppConfig).oauth.jwt.signingKey.local ?? {}),
+			});
+		},
+	},
+});
+
+/** The grant as the connect flow would have left it, a fresh upstream token in hand. */
+async function seedGrant(store: MemoryFederationGrantStore): Promise<void> {
+	const at = new Date();
+	// The revisions as `connections.mts` resolves them from the configuration
+	// above: the federation's issuer and client, the connection's scopes and
+	// boundary, no resource, no authorization parameters.
+	const resolved = {
+		upstreamIssuer: UPSTREAM,
+		upstreamClientId: UPSTREAM_CLIENT_ID,
+		scopes: SCOPES,
+		boundary: BOUNDARY,
+		authorizationParams: {},
+	};
+	await store.createPending({
+		id: GRANT_ID,
+		subject: SUB,
+		clientId: CLIENT_ID,
+		connection: CONNECTION,
+		intent: { handle: "h", expiresAt: new Date(at.getTime() + 600_000) },
+		now: at,
+	});
+	const written = await store.activate({
+		grantId: GRANT_ID,
+		intentHandle: "h",
+		authorization: {
+			identityRevision: federationGrantIdentityRevision(resolved),
+			authorizationRevision: federationGrantAuthorizationRevision(resolved),
+			upstream: { issuer: UPSTREAM, subject: "upstream-alice" },
+			scopes: [...SCOPES],
+			consent: { at, sid: "sid-consent", scopes: [...SCOPES] },
+			authorizedAt: at,
+			expiresAt: new Date(at.getTime() + 30 * DAY),
+		},
+		credentials: {
+			refreshToken: REFRESH_TOKEN,
+			accessToken: {
+				value: ACCESS_TOKEN,
+				tokenType: "Bearer",
+				obtainedAt: at,
+				issuedLifetime: 3600,
+				scopes: [...SCOPES],
+			},
+		},
+		now: at,
+	});
+	if (!written.ok) throw new Error("fixture: the grant was not activated");
+}
+
+const base64url = (value: unknown): string =>
+	Buffer.from(JSON.stringify(value)).toString("base64url");
+
+/**
+ * An id_token for the session, signed with the deployment's own HS256 key, as
+ * the RP would present it: `/oauth/logout` reads `sid` from the hint and from
+ * nothing else.
+ */
+function idTokenHint(sid: string): string {
+	const header = base64url({ alg: "HS256", kid: "v0", typ: "JWT" });
+	const now = Math.floor(Date.now() / 1000);
+	const payload = base64url({
+		iss: ISSUER,
+		sub: SUB,
+		aud: CLIENT_ID,
+		sid,
+		iat: now,
+		exp: now + 3600,
+	});
+	const signature = createHmac("sha256", JWT_SECRET)
+		.update(`${header}.${payload}`)
+		.digest("base64url");
+	return `${header}.${payload}.${signature}`;
+}
+
+const claimsOf = (jwt: string): Record<string, unknown> =>
+	JSON.parse(Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8")) as Record<
+		string,
+		unknown
+	>;
+
+describe("#593 AC8: a grant outlives the browser session at both logout endpoints (D14)", () => {
+	let handleRef: Awaited<ReturnType<typeof createApp>> | undefined;
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	async function boot() {
+		const config = resolveConfig();
+		const handle = await createApp({
+			modules: buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			bootstrapComponents: { config, pathResolver: (s) => s },
+		});
+		handleRef = handle;
+		const components = handle.components as {
+			federationGrantStore: MemoryFederationGrantStore;
+			userSessionStore: UserSessionStore;
+			federationTokenStore: FederationTokenStore;
+		};
+		await seedGrant(components.federationGrantStore);
+		const app = express();
+		app.use(handle.router);
+		return { app, config, ...components };
+	}
+
+	/** The real browser half: a CSRF pair, a login, and the cookies plus the token the login reissued. */
+	async function login(app: express.Express, config: AppConfig) {
+		const csrfRes = await request(app).get("/session/csrf");
+		expect(csrfRes.status).toBe(200);
+		const csrfToken = csrfRes.body.csrf_token as string;
+		const headerName = csrfRes.body.header_name as string;
+		const csrfCookies = csrfRes.headers["set-cookie"] as unknown as string[];
+
+		const loginRes = await request(app)
+			.post("/session/login")
+			.set("Cookie", csrfCookies)
+			.set(headerName, csrfToken)
+			.type("form")
+			.send({ username: USERNAME, password: PASSWORD });
+		expect(loginRes.status).toBe(200);
+
+		const cookies = loginRes.headers["set-cookie"] as unknown as string[];
+		const csrfCookiePrefix = `${config.session.name}.csrf=`;
+		const reissued = cookies
+			.find((c) => c.startsWith(csrfCookiePrefix))
+			?.slice(csrfCookiePrefix.length)
+			.split(";")[0];
+		expect(reissued).toBeDefined();
+		return { cookies, csrfToken: decodeURIComponent(reissued as string), headerName };
+	}
+
+	/** The session's `sid`, read off the access token the session grant mints for it. */
+	async function sidOf(app: express.Express, cookies: string[]): Promise<string> {
+		const res = await request(app)
+			.post("/oauth/token")
+			.set("Authorization", BASIC)
+			.set("Cookie", cookies)
+			.type("form")
+			.send({ grant_type: "session" });
+		expect(res.status).toBe(200);
+		const sid = claimsOf(res.body.access_token as string).sid;
+		expect(typeof sid).toBe("string");
+		return sid as string;
+	}
+
+	const disclose = (app: express.Express) =>
+		request(app)
+			.post(`/oauth/federation-grants/${GRANT_ID}/token`)
+			.set("Authorization", BASIC)
+			.send({ sub: SUB });
+
+	/**
+	 * What a logout has to leave: the record, its credential — the values, not
+	 * only a readable state, since a rotated or dropped refresh token beside an
+	 * untouched access token would still read `"ok"` — and a disclosure that
+	 * still answers.
+	 */
+	async function expectGrantUntouched(app: express.Express, store: MemoryFederationGrantStore) {
+		expect((await store.find(GRANT_ID, new Date()))?.status).toBe("active");
+		const opened = await store.open(GRANT_ID, new Date());
+		if (opened?.credentials.state !== "ok")
+			throw new Error("the grant's credential is not readable");
+		expect(opened.credentials.value).toMatchObject({
+			refreshToken: REFRESH_TOKEN,
+			accessToken: { value: ACCESS_TOKEN },
+		});
+		const response = await disclose(app);
+		expect(response.status).toBe(200);
+		expect(response.body.access_token).toBe(ACCESS_TOKEN);
+	}
+
+	it("POST /session/logout ends the session's own records and leaves the grant spendable", async () => {
+		const { app, config, federationGrantStore, userSessionStore, federationTokenStore } =
+			await boot();
+		const { cookies, csrfToken, headerName } = await login(app, config);
+		const sid = await sidOf(app, cookies);
+		// A session-bound upstream token beside the grant: the record #276's
+		// guarantee is about, keyed by this session.
+		await federationTokenStore.attach(sid, "upstream", {
+			accessToken: "session-bound-upstream-token",
+			expiresAt: null,
+		});
+		expect(await userSessionStore.get(sid)).not.toBeNull();
+		await expectGrantUntouched(app, federationGrantStore);
+
+		const logout = await request(app)
+			.post("/session/logout")
+			.set("Cookie", cookies)
+			.set(headerName, csrfToken);
+		expect([200, 204]).toContain(logout.status);
+
+		// The session-bound records are gone (#276 holds) ...
+		expect(await userSessionStore.get(sid)).toBeNull();
+		expect(await federationTokenStore.get(sid, "upstream")).toBeNull();
+		// ... and the grant is not among them.
+		await expectGrantUntouched(app, federationGrantStore);
+	});
+
+	it("POST /oauth/logout runs the cascade and leaves the grant spendable", async () => {
+		const { app, config, federationGrantStore, userSessionStore, federationTokenStore } =
+			await boot();
+		const { cookies } = await login(app, config);
+		const sid = await sidOf(app, cookies);
+		await federationTokenStore.attach(sid, "upstream", {
+			accessToken: "session-bound-upstream-token",
+			expiresAt: null,
+		});
+		expect(await userSessionStore.get(sid)).not.toBeNull();
+		await expectGrantUntouched(app, federationGrantStore);
+
+		const logout = await request(app)
+			.post("/oauth/logout")
+			.type("form")
+			.send({ id_token_hint: idTokenHint(sid) });
+		expect(logout.status).toBe(200);
+
+		expect(await userSessionStore.get(sid)).toBeNull();
+		expect(await federationTokenStore.get(sid, "upstream")).toBeNull();
+		await expectGrantUntouched(app, federationGrantStore);
+	});
+});

package/templates/standalone/src/__tests__/google-federation-config-module.test.mts

@@ -112,3 +112,60 @@ describe("googleFederationConfigModule — redirect-policy plumbing (#278)", ()
 		expect(out.redirectAllowlist).toEqual(["https://app.example.com/dashboard"]);
 	});
 });
+
+describe("googleFederationConfigModule — requireAuthorizationResponseIss (#597)", () => {
+	it("is absent by default, so the provider's own default (required) applies", () => {
+		expect("requireAuthorizationResponseIss" in buildConfig(credentials)).toBe(false);
+	});
+
+	it("forwards the operator's escape hatch", () => {
+		expect(
+			buildConfig({ ...credentials, requireAuthorizationResponseIss: false })
+				.requireAuthorizationResponseIss,
+		).toBe(false);
+		expect(
+			buildConfig({ ...credentials, requireAuthorizationResponseIss: true })
+				.requireAuthorizationResponseIss,
+		).toBe(true);
+	});
+
+	it("reads the strings an environment override produces", () => {
+		expect(
+			buildConfig({ ...credentials, requireAuthorizationResponseIss: "false" })
+				.requireAuthorizationResponseIss,
+		).toBe(false);
+		expect(
+			buildConfig({ ...credentials, requireAuthorizationResponseIss: "true" })
+				.requireAuthorizationResponseIss,
+		).toBe(true);
+	});
+
+	it("reads the spellings every other env-overridable boolean accepts", () => {
+		for (const [raw, expected] of [
+			["False", false],
+			[" false ", false],
+			["0", false],
+			["TRUE", true],
+			["1", true],
+		] as const) {
+			expect(
+				buildConfig({ ...credentials, requireAuthorizationResponseIss: raw })
+					.requireAuthorizationResponseIss,
+			).toBe(expected);
+		}
+	});
+
+	it("refuses an empty value, which elsewhere reads as false: exported-but-empty must not switch this check off", () => {
+		expect(() => buildConfig({ ...credentials, requireAuthorizationResponseIss: "" })).toThrow(
+			/federations\.google\.requireAuthorizationResponseIss/,
+		);
+	});
+
+	it("refuses anything else: a typo must not silently switch the check off, or leave it on", () => {
+		for (const bad of ["no", "off", 0, 1, []]) {
+			expect(() => buildConfig({ ...credentials, requireAuthorizationResponseIss: bad })).toThrow(
+				/federations\.google\.requireAuthorizationResponseIss/,
+			);
+		}
+	});
+});

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

@@ -412,3 +412,17 @@ function dockerignoreExcludes(dockerignore: string, file: string): boolean {
 	}
 	return excluded;
 }
+
+describe("#593 slice 7 — the compose files give the process time to finish a shutdown", () => {
+	it.each(["/docker-compose.yml", "/docker-compose.production.yml"])(
+		"%s declares a stop_grace_period covering the HTTP drain, the grants cleanup and an exit margin",
+		(rel) => {
+			// compose's own default is ten seconds — the drain budget alone. With
+			// federation grants on, the cleanup that drains a rotated credential's
+			// write gets 45 more, and SIGKILL must arrive after that, not during.
+			const match = /^\s+stop_grace_period:\s*(\d+)s\s*$/m.exec(read(rel));
+			expect(match, `${rel} has no stop_grace_period`).not.toBeNull();
+			expect(Number(match?.[1])).toBeGreaterThanOrEqual(60);
+		},
+	);
+});

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

@@ -33,7 +33,13 @@
 import type { Server } from "node:http";
 import type { Logger } from "@o3co/auth-provider-core";
 import { describe, expect, it, vi } from "vitest";
-import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
+import {
+	cleanupAllowanceFor,
+	deferExit,
+	FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
+	FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
+	installGracefulShutdown,
+} from "../shutdown.mjs";
 
 /** A `Server` double whose `close` callback fires only when we say so. */
 function makeServer() {
@@ -80,7 +86,13 @@ const makeLogger = () => {
 };
 
 /** Drive one shutdown without touching the real `process` or exiting. */
-function install(opts: { cleanup?: () => void | Promise<void>; drainTimeoutMs?: number } = {}) {
+function install(
+	opts: {
+		cleanup?: () => void | Promise<void>;
+		drainTimeoutMs?: number;
+		cleanupTimeoutMs?: number;
+	} = {},
+) {
 	const { server, spies, finishDraining, failClose } = makeServer();
 	const logger = makeLogger();
 	const exit = vi.fn();
@@ -90,6 +102,7 @@ function install(opts: { cleanup?: () => void | Promise<void>; drainTimeoutMs?:
 		logger,
 		cleanup: opts.cleanup ?? (() => {}),
 		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
+		...(opts.cleanupTimeoutMs === undefined ? {} : { cleanupTimeoutMs: opts.cleanupTimeoutMs }),
 		exit,
 		onSignal: (name, handler) => signals.set(name, handler),
 		offSignal: (name) => signals.delete(name),
@@ -322,3 +335,84 @@ describe("installGracefulShutdown (#290)", () => {
 		expect(signals.size).toBe(0);
 	});
 });
+
+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({});
+	});
+
+	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("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("is honoured by the shutdown: a cleanup that needs longer than the drain is given it", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
+				drainTimeoutMs: 5_000,
+				...cleanupAllowanceFor({ federationGrants: { enabled: true } }),
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(31_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+});

package/templates/standalone/src/app.mts

@@ -29,7 +29,7 @@ import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
-import { installGracefulShutdown } from "./shutdown.mjs";
+import { cleanupAllowanceFor, installGracefulShutdown } from "./shutdown.mjs";
 import { createTerminalErrorHandler } from "./terminalError.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
@@ -164,8 +164,16 @@ await (async (): Promise<void> => {
 	// from the code you deploy. See `shutdown.mts` for the stated guarantees
 	// and for the deadline the previous implementation did not have. Size
 	// `drainTimeoutMs` below your orchestrator's kill grace period.
+	//
+	// #593 slice 7: with federation grants on, cleanup gets the longest refresh
+	// tail the configured budgets allow plus a margin — 45 s under the shipped
+	// ones — rather than inheriting the drain's ten: the dispose is what waits
+	// for a rotated credential's write. The compose files size
+	// `stop_grace_period` to cover the drain, this and an exit margin for the
+	// shipped budgets; a raised budget raises both.
 	installGracefulShutdown(server, {
 		logger,
 		cleanup: () => handle.dispose(),
+		...cleanupAllowanceFor(config),
 	});
 })();