@o3co/create-auth-provider 0.13.0 → 0.15.0

package/templates/standalone/src/shutdown.mts

@@ -61,10 +61,11 @@ import type { Logger } from "@o3co/auth-provider-core";
  *    reports through its callback, and treating that as success would tell an
  *    orchestrator the listener came down when it did not.
  *
- * Size `drainTimeoutMs` **below** the orchestrator's own kill grace period
- * (Kubernetes `terminationGracePeriodSeconds`, compose `stop_grace_period`,
- * both 30s by default) — the point is to close on our terms before SIGKILL
- * arrives on someone else's.
+ * Size `drainTimeoutMs` plus `cleanupTimeoutMs` **below** the orchestrator's
+ * own kill grace period (Kubernetes `terminationGracePeriodSeconds` is 30s by
+ * default, compose `stop_grace_period` 10s; with federation grants on the sum
+ * is 55s, so the grace is 60s or more) — the point is to close on our terms
+ * before SIGKILL arrives on someone else's.
  */
 export interface GracefulShutdownOptions {
 	readonly logger: Logger;
@@ -102,6 +103,71 @@ export function deferExit(code: number, exitProcess: (code: number) => void = pr
 const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
 
+/**
+ * The least cleanup allowance federation grants get (#593 slice 7): 45
+ * seconds. The package's background registry drains on dispose — it waits for
+ * a rotated upstream credential's write — and the longest tail one refresh
+ * can have is the upstream hard timeout, the persist budget and the wait for
+ * the grant's lock, back to back. With the shipped budgets (25 s + 3 s + 5 s)
+ * and {@link FEDERATION_GRANTS_CLEANUP_MARGIN_MS} that is exactly this floor;
+ * a deployment that raises a budget raises the allowance with it, below.
+ * The ten-second drain that cleanup would otherwise inherit is shorter than
+ * the tail, and a shutdown under it would abandon exactly the write the drain
+ * exists to wait for, after the IdP had moved on to the new refresh token.
+ *
+ * A host policy, not a grant setting: what it bounds is `handle.dispose()`,
+ * and the orchestrator's grace period has to cover the drain, this and an exit
+ * margin — the compose files ship 60 seconds for the shipped budgets, and an
+ * operator who raises a budget raises the grace to match.
+ */
+export const FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS = 45_000;
+
+/** What the allowance adds to the longest refresh tail: an exit margin. */
+export const FEDERATION_GRANTS_CLEANUP_MARGIN_MS = 12_000;
+
+/**
+ * The most a timer can be asked for: Node's `setTimeout` takes a 32-bit signed
+ * delay, and a larger one fires after ~1 ms instead. A sum of budgets an
+ * operator set high enough to reach it would otherwise turn the allowance
+ * into no allowance at all (Copilot, #614).
+ */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * The `cleanupTimeoutMs` to hand {@link installGracefulShutdown}, from the
+ * config: while the feature is on, the longer of the floor above and the
+ * configured refresh tail plus the margin; while it is off, nothing — the
+ * drain's own budget, as before. A fragment to spread, so an absent allowance
+ * is absent rather than `undefined`. A config that carries no budgets (one
+ * built by hand, without `reference.conf`) gets the floor.
+ */
+export function cleanupAllowanceFor(config: {
+	readonly federationGrants?:
+		| {
+				readonly enabled?: boolean | undefined;
+				readonly upstreamHardTimeoutMs?: number | undefined;
+				readonly persistRetryBudgetMs?: number | undefined;
+				readonly lockWaitMs?: number | undefined;
+		  }
+		| undefined;
+}): { readonly cleanupTimeoutMs: number } | Record<string, never> {
+	const grants = config.federationGrants;
+	if (grants?.enabled !== true) return {};
+	const budgets = [grants.upstreamHardTimeoutMs, grants.persistRetryBudgetMs, grants.lockWaitMs];
+	const tail = budgets.every((budget) => typeof budget === "number" && Number.isFinite(budget))
+		? (budgets as number[]).reduce(
+				(sum, budget) => sum + budget,
+				FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
+			)
+		: 0;
+	return {
+		cleanupTimeoutMs: Math.min(
+			Math.max(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS, tail),
+			MAX_TIMER_MS,
+		),
+	};
+}
+
 export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
 	const {
 		logger,

package/templates/standalone/vitest.config.mts

@@ -20,5 +20,11 @@ export default defineConfig({
 		// monorepo the same packages are symlinks to source and are inlined
 		// anyway; this makes the two layouts behave the same.
 		server: { deps: { inline: [/@o3co\/auth-provider-/] } },
+		// #556: the server `request(app)` starts listens on 127.0.0.1, the
+		// address supertest dials. Unpatched, macOS can give it a port another
+		// process holds on 127.0.0.1, and the request hangs on that process until
+		// the test timeout. Rationale and mechanics in the file itself. The
+		// Dockerfile `test` stage copies it; scaffold-assets.test.mts checks that.
+		setupFiles: ["./vitest.supertest-loopback.mts"],
 	},
 });

package/templates/standalone/vitest.supertest-loopback.mts

@@ -0,0 +1,250 @@
+/*
+ * 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.
+ */
+
+/**
+ * vitest setup file (#556): the server supertest starts listens on the
+ * address supertest dials.
+ *
+ * `request(app)` / `request.agent(app)` start a server with `app.listen(0)`
+ * and send the request to `127.0.0.1:<port>`. A hostless `listen` binds the
+ * dual-stack wildcard `[::]:P`, and on macOS (BSD `SO_REUSEADDR` semantics —
+ * libuv sets it on every TCP listener) the kernel will choose a `P` that
+ * another process already holds as `127.0.0.1:P`. The more specific socket
+ * wins, so the test's request is delivered to that process. When it accepts
+ * and never answers — an editor helper, in the case that was caught — the
+ * request hangs until the test timeout, in whichever supertest test drew the
+ * port, and passes on the next run. Linux refuses the conflicting bind
+ * (EADDRINUSE), so CI does not show it.
+ *
+ * Binding `127.0.0.1` explicitly removes both halves: the kernel will not
+ * give out a `127.0.0.1:P` someone else holds, and against a wildcard holder
+ * our specific socket is the one that receives. A specific-host `listen` is
+ * asynchronous (it goes through `dns.lookup`), and supertest reads the port
+ * synchronously in its constructor, so the URL is completed when the request
+ * is sent (`end`, which `then` and `expect(..., fn)` go through). A server the
+ * test started itself is never touched.
+ *
+ * Which version of supertest closes the server it started, and when, has
+ * changed under this file once (7.3.0): 7.2 closed `_server` before asserting;
+ * 7.3 tracks the servers it started itself in a private registry and closes
+ * only those, so a server this file bound is left listening. The patched
+ * `end` therefore closes the server this request started, before the test's
+ * callback, whenever supertest has not — the same order either way.
+ *
+ * supertest is loaded from the package that owns the running test file (the
+ * nearest `package.json` above it), so the patched class is the one that test
+ * imports, whatever directory vitest was started from. A package that does
+ * not declare supertest is left alone. Everything else this file cannot do —
+ * no test path, a declared supertest that does not load, a supertest whose
+ * internals no longer look like this — throws, so the guard is never silently
+ * off. That load-time check sees only the two methods' presence; a supertest
+ * that moved the `listen` out of `serverAddress` would pass it and leave the
+ * guard off. The behavioural tests catch that shape of change: this
+ * template's `supertest-loopback.test.mts` and its twin in the session
+ * package assert the address the server actually bound.
+ *
+ * This file is part of the project template and ships with every scaffold.
+ * The auth.provider workspace loads this same file for its packages (see
+ * `WORKSPACE_TEST_SETUP` in its `vitest.shared.mts`).
+ */
+
+import { once } from "node:events";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import type { Server } from "node:net";
+import { dirname, join } from "node:path";
+import { Server as TlsServer } from "node:tls";
+import { expect } from "vitest";
+
+const LOOPBACK = "127.0.0.1";
+const PATCHED = Symbol.for("o3co.auth.provider.supertest-loopback");
+const PENDING = Symbol("o3co.auth.provider.supertest-loopback.pending");
+
+type Pending = {
+	readonly server: Server;
+	readonly protocol: string;
+	readonly path: string;
+	/** Settles on `listening`, rejects on a listen `error`. */
+	readonly ready: Promise<unknown>;
+};
+
+type TestInstance = {
+	url: string;
+	_server?: Server;
+	[PENDING]?: Pending;
+};
+
+type TestPrototype = {
+	serverAddress(this: TestInstance, app: Server, path: string): string;
+	end(this: TestInstance, fn?: (err: unknown, res?: unknown) => void): TestInstance;
+	[PATCHED]?: true;
+};
+
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies",
+] as const;
+
+/** The nearest `package.json` at or above `dir`. */
+function owningManifest(dir: string): string | undefined {
+	for (let current = dir; ; current = dirname(current)) {
+		const candidate = join(current, "package.json");
+		if (existsSync(candidate)) return candidate;
+		if (dirname(current) === current) return undefined;
+	}
+}
+
+/** supertest's `Test.prototype` as the running test file sees it, or `undefined` when its package has no supertest. */
+function supertestFor(testPath: string): TestPrototype | undefined {
+	const manifestPath = owningManifest(dirname(testPath));
+	if (!manifestPath) {
+		throw new Error(`vitest.supertest-loopback.mts: no package.json above ${testPath}.`);
+	}
+	const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+	const declared = DEPENDENCY_FIELDS.some(
+		(field) => (manifest[field] as Record<string, unknown> | undefined)?.supertest !== undefined,
+	);
+	if (!declared) return undefined;
+
+	let supertest: { Test?: { prototype: TestPrototype } };
+	try {
+		supertest = createRequire(manifestPath)("supertest");
+	} catch (cause) {
+		throw new Error(
+			`vitest.supertest-loopback.mts: ${manifestPath} declares supertest, but it cannot be loaded from there; the #556 loopback guard would be off.`,
+			{ cause },
+		);
+	}
+	const proto = supertest.Test?.prototype;
+	if (typeof proto?.serverAddress !== "function" || typeof proto.end !== "function") {
+		throw new Error(
+			"vitest.supertest-loopback.mts: supertest no longer exposes Test.prototype.serverAddress/end; " +
+				"re-check the #556 loopback guard against the installed supertest before removing it.",
+		);
+	}
+	return proto;
+}
+
+/**
+ * The bind in progress per server. A second request on a server whose bind has
+ * not finished (an agent's requests sent together share one server) waits on
+ * the same bind instead of calling `listen` twice — and, like unpatched
+ * supertest when it finds a server already listening, does not own it.
+ */
+const binding = new WeakMap<Server, Promise<unknown>>();
+
+/**
+ * A throw from the test's own callback, raised where it cannot propagate to
+ * the test: reported as an uncaught exception, which fails the run by name,
+ * instead of an unhandled rejection of a promise nobody holds.
+ */
+function rethrowOutsideThisChain(err: unknown): void {
+	process.nextTick(() => {
+		throw err;
+	});
+}
+
+function patch(proto: TestPrototype): void {
+	if (proto[PATCHED]) return;
+	const originalServerAddress = proto.serverAddress;
+	const originalEnd = proto.end;
+
+	proto.serverAddress = function serverAddress(app, path) {
+		// Already listening: the test owns the server and chose its address.
+		if (app.address()) return originalServerAddress.call(this, app, path);
+
+		const protocol = app instanceof TlsServer ? "https" : "http";
+		let ready = binding.get(app);
+		if (!ready) {
+			// supertest 7.2 closes `_server` after the response; 7.3 does not,
+			// and the callback in the patched `end` below closes it instead.
+			this._server = app.listen(0, LOOPBACK);
+			// Subscribed now, not in `end`: a listen error emitted before the test
+			// sends the request must still reach it, not crash the worker as an
+			// unhandled 'error' event.
+			const bound = once(app, "listening");
+			binding.set(app, bound);
+			bound.then(
+				() => binding.delete(app),
+				() => binding.delete(app),
+			);
+			ready = bound;
+		}
+		this[PENDING] = { server: app, protocol, path, ready };
+		// No port yet; `end` fills it in before anything is sent.
+		return `${protocol}://${LOOPBACK}${path}`;
+	};
+
+	proto.end = function end(fn) {
+		const pending = this[PENDING];
+		if (!pending) return originalEnd.call(this, fn);
+		this[PENDING] = undefined;
+
+		const { server, protocol, path, ready } = pending;
+		let called = false;
+		const callback = (err: unknown, res?: unknown) => {
+			called = true;
+			// supertest 7.2 has closed the server it started by now, before the
+			// callback; 7.3 closes only servers in its own private registry, which
+			// this bind is not in. Close what this request started, if it is
+			// still open, before the callback — the order 7.2 kept.
+			if (this._server === server && server.listening) {
+				server.close(() => fn?.(err, res));
+				return;
+			}
+			fn?.(err, res);
+		};
+		// Unpatched, whatever `end` throws while building the request (a header
+		// value Node refuses, a body that will not serialize) reaches the caller
+		// at once — and `then` runs `end` inside a promise executor, so the
+		// awaited request rejects with it. Deferred, there is no caller left: the
+		// throw, like a failed bind, is handed to the request's callback, which
+		// is what rejects that promise. Nothing here may reject: a rejection of
+		// this chain is one nobody awaits.
+		const fail = (err: unknown) => {
+			if (called) return rethrowOutsideThisChain(err);
+			// The request never went out, so supertest will not close the server
+			// this request started.
+			if (this._server?.listening) this._server.close();
+			try {
+				callback(err);
+			} catch (thrown) {
+				rethrowOutsideThisChain(thrown);
+			}
+		};
+		ready
+			.then(() => {
+				const { port } = server.address() as { port: number };
+				this.url = `${protocol}://${LOOPBACK}:${port}${path}`;
+				originalEnd.call(this, callback);
+			})
+			.catch(fail);
+		return this;
+	};
+
+	proto[PATCHED] = true;
+}
+
+const { testPath } = expect.getState();
+if (!testPath) {
+	throw new Error(
+		"vitest.supertest-loopback.mts: vitest did not say which test file this setup runs for, so the #556 loopback guard cannot find supertest.",
+	);
+}
+const proto = supertestFor(testPath);
+if (proto) patch(proto);

package/templates/versions.json

@@ -1,16 +1,17 @@
 {
-	"@o3co/auth-provider-core": "0.13.0",
-	"@o3co/auth-provider-device-grant": "0.13.0",
-	"@o3co/auth-provider-dpop": "0.13.0",
-	"@o3co/auth-provider-mtls": "0.13.0",
-	"@o3co/auth-provider-federation-apple": "0.13.0",
-	"@o3co/auth-provider-federation-google": "0.13.0",
-	"@o3co/auth-provider-federation-github": "0.13.0",
-	"@o3co/auth-provider-federation-oidc": "0.13.0",
-	"@o3co/auth-provider-oauth": "0.13.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.13.0",
-	"@o3co/auth-provider-session": "0.13.0",
-	"@o3co/auth-provider-foundation": "0.13.0",
-	"@o3co/auth-provider-redis": "0.13.0",
-	"@o3co/auth-provider-webauthn": "0.13.0"
+	"@o3co/auth-provider-core": "0.15.0",
+	"@o3co/auth-provider-device-grant": "0.15.0",
+	"@o3co/auth-provider-dpop": "0.15.0",
+	"@o3co/auth-provider-mtls": "0.15.0",
+	"@o3co/auth-provider-federation-apple": "0.15.0",
+	"@o3co/auth-provider-federation-google": "0.15.0",
+	"@o3co/auth-provider-federation-github": "0.15.0",
+	"@o3co/auth-provider-federation-grants": "0.15.0",
+	"@o3co/auth-provider-federation-oidc": "0.15.0",
+	"@o3co/auth-provider-oauth": "0.15.0",
+	"@o3co/auth-provider-oauth-token-exchange": "0.15.0",
+	"@o3co/auth-provider-session": "0.15.0",
+	"@o3co/auth-provider-foundation": "0.15.0",
+	"@o3co/auth-provider-redis": "0.15.0",
+	"@o3co/auth-provider-webauthn": "0.15.0"
 }