@o3co/create-auth-provider 0.12.1 → 0.14.0

package/templates/standalone/src/__tests__/supertest-loopback.test.mts

@@ -0,0 +1,125 @@
+/*
+ * 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.
+ */
+
+/**
+ * #556 — the server `request(app)` starts listens on the address supertest
+ * dials, in this project's own test run.
+ *
+ * Unpatched, supertest starts its server with `app.listen(0)` — the
+ * dual-stack wildcard `[::]:P` — and sends the request to `127.0.0.1:P`. On
+ * macOS the kernel can hand out a `P` another process already holds as
+ * `127.0.0.1:P`; the request then reaches that process, and if it never
+ * answers the test hangs until its timeout. `vitest.supertest-loopback.mts`
+ * (wired in through `setupFiles` in `vitest.config.mts`) binds the server to
+ * `127.0.0.1` instead. These tests fail if that wiring is lost.
+ */
+
+import http from "node:http";
+import net, { type AddressInfo } from "node:net";
+import express from "express";
+import request from "supertest";
+import { describe, expect, it } from "vitest";
+
+function helloApp() {
+	const app = express();
+	app.get("/hello", (_req, res) => {
+		res.status(200).send("hello");
+	});
+	return app;
+}
+
+/** Resolves with the address `server` binds, whoever calls `listen`. */
+function boundAddress(server: net.Server): Promise<AddressInfo> {
+	return new Promise((resolve) => {
+		server.once("listening", () => resolve(server.address() as AddressInfo));
+	});
+}
+
+describe("#556 — supertest's own server listens on the loopback address it dials", () => {
+	it("binds 127.0.0.1, not the dual-stack wildcard", async () => {
+		const server = http.createServer(helloApp());
+		const bound = boundAddress(server);
+
+		const res = await request(server).get("/hello");
+
+		expect(res.status).toBe(200);
+		expect(await bound).toMatchObject({ address: "127.0.0.1", family: "IPv4" });
+		// supertest still closes the server it started.
+		expect(server.listening).toBe(false);
+	});
+
+	it("rejects promptly with the request's own error when the request cannot be built", async () => {
+		// Node refuses this header value (ERR_INVALID_CHAR) while supertest builds
+		// the request. With the loopback bind that happens after the bind settles,
+		// outside the promise the test awaits; the throw must still reject that
+		// promise, as it does unpatched, and not become an unhandled rejection
+		// that leaves the request hanging until the test timeout.
+		const server = http.createServer(helloApp());
+
+		await expect(request(server).get("/hello").set("x-test", "bad\nvalue")).rejects.toMatchObject({
+			code: "ERR_INVALID_CHAR",
+		});
+		// The request never went out, so nothing would close the server it started.
+		expect(server.listening).toBe(false);
+	}, 5_000);
+
+	it("hands the same error to an .end() callback", async () => {
+		const server = http.createServer(helloApp());
+
+		const err = await new Promise<unknown>((resolve) => {
+			request(server)
+				.get("/hello")
+				.set("x-test", "bad\nvalue")
+				.end((error) => resolve(error));
+		});
+
+		expect(err).toMatchObject({ code: "ERR_INVALID_CHAR" });
+	}, 5_000);
+
+	it("serves requests an agent sends together over its one server", async () => {
+		const agent = request.agent(helloApp());
+
+		const responses = await Promise.all([agent.get("/hello"), agent.get("/hello")]);
+
+		expect(responses.map((res) => res.status)).toEqual([200, 200]);
+	});
+
+	it("fails the request, instead of hanging on another socket, when 127.0.0.1:P is taken", async () => {
+		// The collision the kernel produces by chance, produced on purpose: a
+		// socket that accepts and never answers holds 127.0.0.1:P, and the
+		// server supertest starts is steered onto P.
+		const held: net.Socket[] = [];
+		const squatter = net.createServer((socket) => {
+			held.push(socket);
+		});
+		await new Promise<void>((resolve) => squatter.listen(0, "127.0.0.1", resolve));
+		const { port } = squatter.address() as AddressInfo;
+
+		const server = http.createServer(helloApp());
+		const listen = server.listen.bind(server) as (...args: unknown[]) => net.Server;
+		(server as { listen: (...args: unknown[]) => net.Server }).listen = (_port, ...rest) =>
+			listen(port, ...rest);
+
+		try {
+			await expect(request(server).get("/hello")).rejects.toMatchObject({
+				code: "EADDRINUSE",
+			});
+		} finally {
+			for (const socket of held) socket.destroy();
+			squatter.close();
+		}
+	}, 5_000);
+});

package/templates/standalone/src/buildModules.mts

@@ -20,9 +20,12 @@ import {
 	jwksModule,
 	type Module,
 	memoryAccessTokenDenylistModule,
+	memoryConsentStoreModule,
 	memoryRateLimiterModule,
+	memoryReplaySeenSetModule,
 } from "@o3co/auth-provider-core";
 import { googleFederationModule } from "@o3co/auth-provider-federation-google";
+import { oidcFederationModule, oidcFederationNames } from "@o3co/auth-provider-federation-oidc";
 import {
 	oauthAuthorizationModule,
 	oauthModule,
@@ -31,12 +34,18 @@ import {
 import {
 	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
+	redisConsentStoreModule,
 	redisFederationTokenStoreModuleFor,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
+	redisReplaySeenSetModule,
 	redisSessionStoresModule,
 } from "@o3co/auth-provider-redis";
-import { sessionModule, sessionStoreModuleFor } from "@o3co/auth-provider-session";
+import {
+	extractFederationSection,
+	sessionModule,
+	sessionStoreModuleFor,
+} from "@o3co/auth-provider-session";
 import {
 	auditSinkModule,
 	googleFederationConfigModule,
@@ -44,6 +53,7 @@ import {
 	inMemoryFederationTokenStoreModule,
 	inMemorySessionStoresModule,
 	keyStoreModule,
+	oidcFederationConfigModule,
 	repositoriesModule,
 	standaloneRedisClientsModule,
 } from "./modules.mjs";
@@ -93,6 +103,15 @@ export interface BuildModulesOverrides {
 	readonly auditSinkModule?: Module;
 }
 
+/**
+ * The access-token lifetime core's `reference.conf` ships on the deprecated
+ * `oauth.accessToken.expiresIn`. Not a default — nothing mints with it — only
+ * what an unmodified deployment carries there, so the deprecation line can tell
+ * an operator's override from the shipped value. Pinned against the real file
+ * by `access-token-lifetime-alias.test.mts`.
+ */
+const SHIPPED_ACCESS_TOKEN_EXPIRES_IN = 3600;
+
 /**
  * Compose the standalone v0.5.0 module list from `config`. Splitting this
  * out of `app.mts` keeps the composition root testable: a smoke test can
@@ -105,10 +124,23 @@ export interface BuildModulesOverrides {
  * absent), the config-bridge module's provider throws — so the entire pair
  * MUST be conditionally included at composition time, not gated inside the
  * provider.
+ *
+ * #524: the generic OIDC federation follows the same rule, once per enabled
+ * `federations.<name>` of type "oidc": `oidcFederationModule(name)` per
+ * instance plus the one `oidcFederationConfigModule` that reads every
+ * instance's config into the slot they share. A section's `type` decides
+ * which implementation owns the name, so the two gates never both select
+ * the same section.
  */
 export function buildModules(config: AppConfig, overrides: BuildModulesOverrides = {}): Module[] {
+	// A section's `type` names the implementation: `federations.google` is the
+	// built-in Google federation only when its type is `google` (the default
+	// for that name). With `type = "oidc"` it is a generic OIDC instance named
+	// "google" (#524), and composing both would contribute the same
+	// federation and redirect-policy keys twice.
 	const googleEnabled =
-		(config.federations?.google as { enabled?: boolean } | undefined)?.enabled === true;
+		extractFederationSection(config.federations ?? {}, "google")?.type === "google";
+	const oidcFederations = oidcFederationNames(config.federations ?? {});
 
 	// Wave 5d (IH-14 + OR-M1 + OR-4) + OR-9: adapter-driven branching for
 	// the OAuth-endpoint rate limiter, the user-session-store family, AND
@@ -128,6 +160,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// endpoint would answer 200 while the token kept working. The switch here is
 	// only over WHICH denylist.
 	const accessTokenDenylistAdapter = config.accessTokenDenylist?.adapter ?? "memory";
+	// #484: the jti single-use record behind private_key_jwt client auth.
+	const replaySeenSetAdapter = config.replaySeenSet?.adapter ?? "memory";
+	// #527: the consent store behind /authorize for clients that are not
+	// first-party. `"none"` (the default) wires nothing — such clients are
+	// refused, as before — so a first-party-only deployment pays nothing and
+	// a multi-replica one is not handed a memory store it cannot run.
+	// `"redis"` (#561) is the store such a deployment selects.
+	const consentStoreAdapter = config.consentStore?.adapter ?? "none";
 	// #456: adapter switch for the federation token store. `"memory"` by
 	// default, the template's local-dev shape; `"redis"` mounts
 	// `redisFederationTokenStoreModule` off the shared socket — what the README
@@ -155,6 +195,26 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		codeRepositoryAdapter = "memory";
 	}
 
+	// The access-token lifetime's deprecated alias: `oauth.accessToken.expiresIn`
+	// (OAUTH_ACCESS_TOKEN_EXPIRES_IN) is still read as the default while
+	// `defaultExpiresIn` is unset — `resolveAccessTokenLifetime` does that, and
+	// this only says so. Core's `reference.conf` keeps the shipped lifetime on
+	// the deprecated key, so "the alias supplied the default" is every
+	// deployment that set nothing; an override of it is the one case with
+	// something to move, the reading `legacyCodeType === "redis"` gives above.
+	// See CHANGELOG for the removal version.
+	const accessToken = config.oauth.accessToken;
+	if (
+		accessToken.defaultExpiresIn === undefined &&
+		accessToken.expiresIn !== SHIPPED_ACCESS_TOKEN_EXPIRES_IN
+	) {
+		console.warn(
+			"[buildModules] `oauth.accessToken.expiresIn` (OAUTH_ACCESS_TOKEN_EXPIRES_IN) is " +
+				"deprecated; use `oauth.accessToken.defaultExpiresIn` " +
+				"(OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN) instead — see CHANGELOG for the removal version.",
+		);
+	}
+
 	const refreshTokenFamilyModules: readonly Module[] = overrides.refreshTokenFamilyModules ?? [
 		redisRefreshTokenFamilyStoreModule,
 	];
@@ -172,6 +232,8 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		userSessionStoresAdapter === "redis" ||
 		codeRepositoryAdapter === "redis" ||
 		accessTokenDenylistAdapter === "redis" ||
+		replaySeenSetAdapter === "redis" ||
+		consentStoreAdapter === "redis" ||
 		federationTokenStoreAdapter === "redis";
 
 	// The four user-session stores switch on `userSessionStores.adapter`; the
@@ -207,6 +269,18 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 			? [redisAccessTokenDenylistModule]
 			: [memoryAccessTokenDenylistModule];
 
+	// #527: opt-in. Each module provides both slots the consent step needs —
+	// the consent records and the requests parked while the page asks — so the
+	// two cannot be wired apart. The memory one declares itself replica-unsafe
+	// and `deployment.mode = "multi"` refuses it by name; the Redis one (#561)
+	// shares both over the ioredis socket.
+	const consentStoreModules: Module[] =
+		consentStoreAdapter === "redis"
+			? [redisConsentStoreModule]
+			: consentStoreAdapter === "memory"
+				? [memoryConsentStoreModule]
+				: [];
+
 	// #455 / #456: mutually-exclusive federation-token-store pair, the same
 	// shape as the session stores. One module per adapter, so the memory one
 	// can declare `replicaSafety` on its manifest and the Redis one can
@@ -217,6 +291,9 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// #473: the Redis module is built for this composition root so its
 	// plaintext guard knows which environment selected the config; it reads
 	// `deployment.mode` off the config itself.
+	const replaySeenSetModules: Module[] =
+		replaySeenSetAdapter === "redis" ? [redisReplaySeenSetModule] : [memoryReplaySeenSetModule];
+
 	const federationTokenStoreModules: Module[] =
 		federationTokenStoreAdapter === "redis"
 			? [redisFederationTokenStoreModuleFor({ environment: overrides.environment })]
@@ -245,6 +322,9 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		jwksModule,
 		sessionModule,
 		...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
+		...(oidcFederations.length > 0
+			? [oidcFederationConfigModule, ...oidcFederations.map((name) => oidcFederationModule(name))]
+			: []),
 		overrides.keyStoreModule ?? keyStoreModule,
 		overrides.repositoriesModule ?? repositoriesModule,
 		// #287: the audit sink, always wired. Unlike every switch above there is
@@ -272,6 +352,10 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// RFC 7009 access-token denylist: redis (shared revocations) or memory
 		// (single-instance dev). Always wired — see the switch above.
 		...accessTokenDenylistModules,
+		...replaySeenSetModules,
+		// Consent records for clients that are not first-party: redis
+		// (multi-replica, #561), memory (single-instance), or nothing (#527).
+		...consentStoreModules,
 		// RT family store: redis by default (closes OR-1); override path
 		// swaps to `[memoryRefreshTokenFamilyStoreModule]` for unit tests.
 		...refreshTokenFamilyModules,

package/templates/standalone/src/modules.mts

@@ -37,6 +37,7 @@ import {
 	registerBuiltinKeyStores,
 } from "@o3co/auth-provider-core";
 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 { extractFederationSection } from "@o3co/auth-provider-session";
@@ -360,11 +361,12 @@ export const storesModule: Module = defineModule({
 
 /**
  * Shared ioredis clients module — opens ONE long-lived ioredis connection
- * per replica, wraps it via `makeIoredisClients()` (returns 13 typed
+ * per replica, wraps it via `makeIoredisClients()` (returns 16 typed
  * per-purpose clients), and exposes the slots consumed by the standalone's
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
  * subject-level revocation index + watermark + rate limiter + code
- * repository + access-token denylist).
+ * repository + access-token denylist + replay seen-set + federation token
+ * store + device-code store + the consent stores).
  *
  * 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).
@@ -436,6 +438,11 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
+		// #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)
+				.replaySeenSetClient;
+		},
 		rateLimiterClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.rateLimiterClient;
@@ -498,6 +505,23 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.deviceCodeStoreClient;
 		},
+		// #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
+		// it under `consentStore.adapter = "redis"`.
+		consentStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.consentStoreClient;
+		},
+		pendingConsentStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.pendingConsentStoreClient;
+		},
 		// #456: the federation-token-store client, off the same shared socket.
 		// `redisFederationTokenStoreModule` requires it, and nothing provided
 		// it — which is why the Redis branch of the federation store could not
@@ -749,3 +773,21 @@ export const googleFederationConfigModule: Module = defineModule({
 		},
 	},
 });
+
+/**
+ * OIDC federation config bridge (#524) — supplies the `oidcFederationConfigs`
+ * slot every `oidcFederationModule(<name>)` in the manifest reads its entry
+ * from. One bridge for all instances: `readOidcFederationConfigs` walks
+ * `config.federations` and reads every enabled section of type `oidc`,
+ * refusing a malformed field by `federations.<name>.<field>` at boot.
+ * `buildModules` lists this module only when at least one such section
+ * exists.
+ */
+export const oidcFederationConfigModule: Module = defineModule({
+	name: "standalone:oidc-federation-config",
+	requires: ["config"] as const,
+	provides: {
+		oidcFederationConfigs: ({ config }) =>
+			readOidcFederationConfigs((config as AppConfig).federations),
+	},
+});

package/templates/standalone/vitest.config.mts

@@ -11,5 +11,20 @@ export default defineConfig({
 		// 20s.
 		testTimeout: 20_000,
 		hookTimeout: 20_000,
+		// #512: run the @o3co/auth-provider-* packages through vitest instead of
+		// letting Node load them natively. In a scaffolded project they are
+		// installed from npm under node_modules, which vitest externalizes by
+		// default — and an externalized package's own `import "ioredis"` /
+		// `import "redis"` never sees a `vi.mock` from a test file, so
+		// replica-safety.test.mts dialled a Redis that is not there. Inside the
+		// 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,231 @@
+/*
+ * 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.
+ *
+ * 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.
+ *
+ * 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 closes `_server` after the response, as it does for the
+			// server it would have started itself.
+			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;
+			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,15 +1,16 @@
 {
-	"@o3co/auth-provider-core": "0.12.1",
-	"@o3co/auth-provider-device-grant": "0.12.1",
-	"@o3co/auth-provider-dpop": "0.12.1",
-	"@o3co/auth-provider-mtls": "0.12.1",
-	"@o3co/auth-provider-federation-apple": "0.12.1",
-	"@o3co/auth-provider-federation-google": "0.12.1",
-	"@o3co/auth-provider-federation-github": "0.12.1",
-	"@o3co/auth-provider-oauth": "0.12.1",
-	"@o3co/auth-provider-oauth-token-exchange": "0.12.1",
-	"@o3co/auth-provider-session": "0.12.1",
-	"@o3co/auth-provider-foundation": "0.12.1",
-	"@o3co/auth-provider-redis": "0.12.1",
-	"@o3co/auth-provider-webauthn": "0.12.1"
+	"@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"
 }