@o3co/create-auth-provider 0.14.0 → 0.16.0

package/templates/standalone/src/logger.mts

@@ -44,10 +44,13 @@ export function createAppLogger(config: AppConfig): Logger {
 	return pino({
 		name: "provider",
 		level: config.logging.level,
-		// `err` is pino's conventional key for an Error, and every structured
-		// event in this stack uses it — `logger.error({ err }, "…_error")`.
-		// Without the serialiser an Error stringifies to `{}` and the stack is
-		// lost exactly where it is needed.
+		// `err` is pino's conventional key for an error, and every structured
+		// event in this stack uses it — `logger.error({ err: loggableError(err) },
+		// "…_error")`. Core's projection is plain data with no `message`, so
+		// this serialiser hands it through as it is, every cause's fields
+		// included. It is here for an Error handed to it as it is, which would
+		// otherwise stringify to `{}`, the stack lost exactly where it is
+		// needed.
 		serializers: { err: stdSerializers.err },
 	});
 }

package/templates/standalone/src/modules.mts

@@ -30,6 +30,7 @@ import {
 	defineModule,
 	type LifecycleRegistrar,
 	type Logger,
+	loggableError,
 	type Module,
 	type ReadinessRegistrar,
 	registerBuiltinAuditSinks,
@@ -39,7 +40,11 @@ import {
 import type { GoogleProviderConfig } from "@o3co/auth-provider-federation-google";
 import { readOidcFederationConfigs } from "@o3co/auth-provider-federation-oidc";
 import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
-import { makeIoredisClients } from "@o3co/auth-provider-redis/ioredis";
+import {
+	makeIoredisClients,
+	makeIoredisFederationGrantIntentStoreClient,
+	makeIoredisFederationGrantStoreClient,
+} from "@o3co/auth-provider-redis/ioredis";
 import { extractFederationSection } from "@o3co/auth-provider-session";
 // Named import is required here, not default. ioredis is CJS and its entry
 // does `module.exports = Redis` with the class re-exported as both `default`
@@ -366,7 +371,11 @@ export const storesModule: Module = defineModule({
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
  * subject-level revocation index + watermark + rate limiter + code
  * repository + access-token denylist + replay seen-set + federation token
- * store + device-code store + the consent stores).
+ * store + device-code store + WebAuthn challenge store + the consent stores),
+ * and the two federation-grant stores' clients from their own factories.
+ * Every store module `@o3co/auth-provider-redis` ships finds its client
+ * slot here, including the ones this template does not select — pinned by
+ * `all-modules-composition.multi.test.mts`.
  *
  * Per F4 PR1 (D-2 v2) + Wave 5d unification: the previous design opened a
  * separate ioredis socket per Redis-backed module (3+ sockets per replica).
@@ -392,11 +401,12 @@ export const storesModule: Module = defineModule({
  * the single connection cleanly.
  *
  * Conditional inclusion: `buildModules` only adds this module to the
- * manifest when at least one Redis-backed adapter is selected
- * (`userSessionStores.adapter = "redis"` OR `rateLimiter.adapter = "redis"`
- * — refresh-token-family is always Redis-backed in production). Adding the
- * module unconditionally would open an ioredis socket for memory-only
- * deployments.
+ * manifest when at least one composed module needs a Redis client
+ * (`usingRedisAnywhere` there): an adapter switch set to `"redis"` — the two
+ * federation-grant store switches only while `federationGrants.enabled` —
+ * and the refresh-token family store, which is Redis-backed unless a test
+ * override replaces it. Adding the module unconditionally would open an
+ * ioredis socket for memory-only compositions.
  */
 export const standaloneRedisClientsModule: Module = defineModule({
 	name: "standalone:redis-clients",
@@ -438,6 +448,28 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
+		// #593 slice 7: the grant store and the intent store, off the same
+		// socket. Consumed by the Redis grant modules when their switches say
+		// "redis"; provided whenever this module is installed, as every slot
+		// here is, because a slot is cheap and the socket is the cost.
+		federationGrantStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.federationGrantStoreClient;
+		},
+		federationGrantIntentStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.federationGrantIntentStoreClient;
+		},
 		// #484: the replay seen-set behind private_key_jwt client assertions.
 		replaySeenSetClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
@@ -505,6 +537,15 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.deviceCodeStoreClient;
 		},
+		// The WebAuthn challenge store's client, off the same shared socket, for
+		// the reason the device-code slot above is here: this template does not
+		// mount WebAuthn, and a deployment that adds `webauthnModule` with
+		// `redisChallengeStoreModule` would otherwise be refused at boot for a
+		// `challengeStoreClient` nothing provided.
+		challengeStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.challengeStoreClient;
+		},
 		// #561: the consent stores' clients, off the same shared socket.
 		// `redisConsentStoreModule` requires both — it provides the consent
 		// records and the parked requests together — and `buildModules` selects
@@ -630,13 +671,26 @@ const SHARED_REDIS_TIMEOUTS = {
 // on PR #121). When `lifecycleRegistrar` is undefined (test scenarios
 // that don't seed it), each call creates a fresh client; tests are
 // isolated and don't need cross-slot sharing.
-const clientsCache = new WeakMap<LifecycleRegistrar, ReturnType<typeof makeIoredisClients>>();
+/**
+ * Every per-purpose client off the one socket: the general bundle, plus the
+ * two the federation-grant stores need (#593 slice 7). Those two have their
+ * own factories in the Redis package, so a Cluster deployment can give the
+ * grants a connection of their own; this template shares the socket, as it
+ * does for every other store.
+ */
+type StandaloneRedisClients = ReturnType<typeof makeIoredisClients> & {
+	readonly federationGrantStoreClient: ReturnType<typeof makeIoredisFederationGrantStoreClient>;
+	readonly federationGrantIntentStoreClient: ReturnType<
+		typeof makeIoredisFederationGrantIntentStoreClient
+	>;
+};
+const clientsCache = new WeakMap<LifecycleRegistrar, StandaloneRedisClients>();
 function getOrCreateClients(
 	config: AppConfig,
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
 	readinessRegistrar?: ReadinessRegistrar,
 	injectedLogger?: Logger,
-): ReturnType<typeof makeIoredisClients> {
+): StandaloneRedisClients {
 	const logger = injectedLogger ?? consoleLogger;
 	const cached = lifecycleRegistrar ? clientsCache.get(lifecycleRegistrar) : undefined;
 	if (cached) return cached;
@@ -656,9 +710,11 @@ function getOrCreateClients(
 
 	// Attach an error handler so unhandled "error" events do not crash the
 	// process. Initial connection failures surface here; downstream adapter
-	// operations then fail visibly.
+	// operations then fail visibly. It logs the projection: ioredis puts the
+	// command a reply answered on the error, and for a refused handshake that
+	// is `AUTH` with the configured password.
 	io.on("error", (err: unknown) => {
-		logger.error({ err }, "standalone_redis_clients_error");
+		logger.error({ err: loggableError(err) }, "standalone_redis_clients_error");
 	});
 
 	lifecycleRegistrar?.register(async () => {
@@ -676,7 +732,11 @@ function getOrCreateClients(
 	// The wrapper opens its own connections for refresh rotation
 	// (`refreshTokenFamilyClient.duplicate()`), which inherit no listeners from
 	// `io`; passing the logger lets those report through the same channel.
-	const clients = makeIoredisClients(io, { logger });
+	const clients: StandaloneRedisClients = {
+		...makeIoredisClients(io, { logger }),
+		federationGrantStoreClient: makeIoredisFederationGrantStoreClient(io),
+		federationGrantIntentStoreClient: makeIoredisFederationGrantIntentStoreClient(io),
+	};
 	if (lifecycleRegistrar) clientsCache.set(lifecycleRegistrar, clients);
 	return clients;
 }
@@ -703,6 +763,47 @@ function optionalString(
 	return { [field]: value };
 }
 
+/**
+ * An optional boolean from the `federations.google` slice. HOCON gives a
+ * boolean; an environment override (`${?VAR}`) gives the string, in the
+ * spellings core's `coerceBooleanFromEnv` accepts: "true" / "false" / "1" /
+ * "0", trimmed and in any case. One deliberate difference: that coercion reads
+ * an empty value as false, and this refuses it. HOCON substitutes an
+ * exported-but-empty variable as "", and for a security switch that must not
+ * quietly turn the check off. Anything else is refused too — a typo that
+ * silently reads as either value is worse than a boot failure.
+ */
+function optionalBoolean(
+	slice: Record<string, unknown>,
+	field: string,
+): Record<string, boolean> | Record<string, never> {
+	const value = slice[field];
+	if (value === undefined || value === null) return {};
+	if (typeof value === "boolean") return { [field]: value };
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true" || normalized === "1") return { [field]: true };
+		if (normalized === "false" || normalized === "0") return { [field]: false };
+	}
+	throw new Error(
+		`federations.google.${field} must be one of true, false, "true", "false", "1" or "0" when present`,
+	);
+}
+
+/**
+ * `accessType` from the `federations.google` slice: `"offline"` or `"online"`,
+ * exactly, or absent. `federation-google` refuses any other value too; this
+ * refuses it first, naming the key, as the fields above do.
+ */
+function optionalAccessType(
+	slice: Record<string, unknown>,
+): { accessType: "offline" | "online" } | Record<string, never> {
+	const value = slice.accessType;
+	if (value === undefined || value === null) return {};
+	if (value === "offline" || value === "online") return { accessType: value };
+	throw new Error('federations.google.accessType must be "offline" or "online" when present');
+}
+
 /**
  * Google federation config bridge — supplies the typed `googleFederationConfig`
  * ComponentMap slot from the `config.federations.google` slice.
@@ -769,6 +870,11 @@ export const googleFederationConfigModule: Module = defineModule({
 				...optionalString(slice, "sessionDomain"),
 				...optionalString(slice, "authCallbackUrl"),
 				...optionalString(slice, "clientUrl"),
+				// #597: absent means the provider's default, which is to require it.
+				...optionalBoolean(slice, "requireAuthorizationResponseIss"),
+				// Absent means the provider's default, "offline": consent on every
+				// sign-in, and a refresh token for every session.
+				...optionalAccessType(slice),
 			};
 		},
 	},

package/templates/standalone/src/routes.mts

@@ -0,0 +1,95 @@
+/*
+ * 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 host's routes, in the order `app.mts` mounts them: liveness, readiness
+ * and the metrics scrape ahead of the composed auth router — so they keep
+ * answering while the auth pipeline is degraded, which is when an operator
+ * needs them — then that router, then core's terminal error handler, last,
+ * because Express hands an error only to handlers mounted after the route
+ * that raised it. A function rather than inline in `app.mts`, so the order
+ * and the handler can be tested as the process mounts them.
+ *
+ * The handler is core's `terminalErrorHandler`, the one that already ends
+ * the composed router, so an error one of the host's routes lets through
+ * is answered as every other route's is: `500 server_error` /
+ * `unexpected_error` in the RFC 6749 envelope with `Cache-Control:
+ * no-store`, logged once as `unhandled_request_error` with the path through
+ * `auditErrorText` and the error's `loggableError` projection; a refusal an
+ * `http-errors` error marks as the client's keeps its 4xx; a response whose
+ * headers already went out is closed rather than handed to Express's final
+ * handler, which would print the stack.
+ */
+
+import {
+	createHealthcheckRouter,
+	createReadinessRouter,
+	type Logger,
+	type ReadinessProbe,
+	terminalErrorHandler,
+} from "@o3co/auth-provider-core";
+import express, { type Express, type Router } from "express";
+import type { Metrics } from "./metrics.mjs";
+
+export interface MountRoutesOptions {
+	/** The router `createApp` composed (`handle.router`). */
+	readonly router: Router;
+	/** The readiness probes the builders registered (`handle.readinessProbes`). */
+	readonly probes: readonly ReadinessProbe[];
+	/** Per-probe deadline, in milliseconds: `config.http.readinessTimeoutMs`. */
+	readonly readinessTimeoutMs: number;
+	readonly metrics: Metrics;
+	readonly logger: Logger;
+}
+
+/** Mount the host's routes, the composed router and the terminal error handler on `app`. */
+export function mountRoutes(app: Express, options: MountRoutesOptions): void {
+	// Liveness: the process is up and its event loop is turning. Deliberately
+	// static — restarting the process would not bring Redis back, so a Redis
+	// outage must not read as "this container is broken, kill it".
+	app.use(createHealthcheckRouter(express));
+
+	// Readiness: can this replica serve right now? Redis backs sessions,
+	// authorization codes and refresh-token families in the deployable
+	// defaults, so a replica that has lost it answers 503 here and should be
+	// taken out of rotation. Probes are contributed by the builders that own
+	// each connection; a memory-only deployment registers none and is always
+	// ready.
+	app.use(
+		createReadinessRouter(express, {
+			probes: options.probes,
+			timeoutMs: options.readinessTimeoutMs,
+			logger: options.logger,
+		}),
+	);
+
+	// Prometheus scrape endpoint. Same reasoning as the probes above: it has to
+	// keep answering while the auth pipeline is degraded, because that is when
+	// the series matter.
+	app.use(
+		options.metrics.route(express, {
+			probes: options.probes,
+			probeTimeoutMs: options.readinessTimeoutMs,
+		}),
+	);
+
+	// The composed auth router, which ends in core's terminal handler.
+	app.use(options.router);
+	// Core's terminal handler again, LAST (#293 item 8), for the host routes
+	// above: Express routes an error only to handlers registered after the
+	// route that threw it. See the file header.
+	app.use(terminalErrorHandler(options.logger));
+}

package/templates/standalone/src/shutdown.mts

@@ -15,7 +15,7 @@
  */
 
 import type { Server } from "node:http";
-import type { Logger } from "@o3co/auth-provider-core";
+import { type Logger, loggableError } from "@o3co/auth-provider-core";
 
 /**
  * Graceful shutdown for the scaffolded server (#290).
@@ -54,17 +54,25 @@ import type { Logger } from "@o3co/auth-provider-core";
  *    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**, and its failure is logged
- *    through the app logger and reflected in the exit code. It never wedges the
- *    process: a dispose that throws still exits, and one that never settles is
- *    cut off at `cleanupTimeoutMs`.
+ *    through the app logger — as core's `loggableError` projection, never the
+ *    error, which holds every cleanup's own error — and reflected in the exit
+ *    code. It never wedges the process: a dispose that throws still exits, and
+ *    one that never settles is cut off at `cleanupTimeoutMs`.
  * 6. **A `close` that fails is not reported as a clean drain.** `server.close`
  *    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.
+ * Every stage is one object-first line under a snake_case event name:
+ * `shutdown_draining` (info, `drainTimeoutMs`), `shutdown_drain_deadline_exceeded`
+ * (error), `shutdown_server_close_failed` (error, `err`), `shutdown_cleanup_timed_out`
+ * (error, `cleanupTimeoutMs`), `shutdown_cleanup_failed` (error, `err`) and
+ * `shutdown_complete` (info, `reason`, `drain`, `exitCode`).
+ *
+ * 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 +110,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,
@@ -160,7 +233,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		let outcome = reason;
 		try {
 			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
-				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
+				logger.error({ cleanupTimeoutMs }, "shutdown_cleanup_timed_out");
 				exitCode = 1;
 				outcome = "cleanup-timeout";
 			}
@@ -168,12 +241,14 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 			// Through the app logger, not `console.error`: a shutdown that
 			// failed to release its Redis connections 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");
+			// pipeline drops. The projection, not the error: `dispose()`
+			// rejects with every cleanup's own error on `errors`, a store's
+			// write — and what it wrote — among them.
+			logger.error({ err: loggableError(err) }, "shutdown_cleanup_failed");
 			exitCode = 1;
 			outcome = "cleanup-failed";
 		}
-		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
+		logger.info({ reason: outcome, drain: reason, exitCode }, "shutdown_complete");
 		exit(exitCode);
 	};
 
@@ -181,13 +256,10 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		if (shuttingDown) return;
 		shuttingDown = true;
 		for (const signal of SIGNALS) offSignal(signal, handler);
-		logger.info({ drainTimeoutMs }, "graceful shutdown: draining");
+		logger.info({ drainTimeoutMs }, "shutdown_draining");
 
 		const deadline = setTimeout(() => {
-			logger.error(
-				{ drainTimeoutMs },
-				"graceful shutdown: drain deadline exceeded, closing remaining connections",
-			);
+			logger.error({ drainTimeoutMs }, "shutdown_drain_deadline_exceeded");
 			server.closeAllConnections();
 			void finish(1, "drain-timeout");
 		}, drainTimeoutMs);
@@ -203,7 +275,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 				// 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");
+				logger.error({ err: loggableError(err) }, "shutdown_server_close_failed");
 				void finish(1, "close-failed");
 				return;
 			}

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

@@ -37,13 +37,24 @@
  * 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.
+ * 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
@@ -160,8 +171,8 @@ function patch(proto: TestPrototype): void {
 		const protocol = app instanceof TlsServer ? "https" : "http";
 		let ready = binding.get(app);
 		if (!ready) {
-			// supertest closes `_server` after the response, as it does for the
-			// server it would have started itself.
+			// 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
@@ -188,6 +199,14 @@ function patch(proto: TestPrototype): void {
 		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

package/templates/versions.json

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