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

package/templates/standalone/src/__tests__/all-modules-composition.fixture.mts

@@ -1,1188 +0,0 @@
-/*
- * 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 composition `all-modules-composition*.test.mts` boot: every module this
- * template can turn on, switched on together from the shipped HOCON, and
- * mounted the way `app.mts` mounts it.
- *
- * Real: the configuration (`config/*.conf` over every loaded package's
- * `reference.conf`, core's last, under the environment a deployment would
- * export) read in `app.mts`'s two phases (`readSwitches`, then
- * `resolveForBoot` for `createApp`), `buildModules`, core's `createApp`, every
- * module and store it selects, the key store, the audit sink, the security
- * headers (`securityHeaders`) and the terminal error handler.
- *
- * Substituted (the first two are overrides `buildModules` offers):
- * - client and user repositories: in memory, not YAML off disk;
- * - the refresh-token family store under `core.deployment.mode = "single"`: memory,
- *   not the shipped Redis, so the single-replica boot opens no sockets;
- * - upstream identity providers: core's fake OpenID Provider, through the
- *   `fetch` option the Google and OIDC federation type modules take: each is
- *   the module `buildModules` lists, built with that option, and the entries
- *   it handles are read as shipped;
- * - configuration with no environment form (grant connections, a key ring, a
- *   landing URL): one more HOCON layer above the shipped ones.
- *
- * `tools/composition` in the monorepo imports this file to boot the same
- * composition with the workspace's other modules added (`ComposeOptions`'s
- * `extra*` options), so the two suites share one fixture.
- */
-
-import { createHash, generateKeyPairSync, randomBytes } from "node:crypto";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import http from "node:http";
-import type { AddressInfo } from "node:net";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-	type AppConfig,
-	ClientEntrySchema,
-	createApp,
-	defineModule,
-	InMemoryClientRepository,
-	InMemoryUserRepository,
-	type Logger,
-	type Module,
-	memoryRefreshTokenFamilyStoreModule,
-	terminalErrorHandler,
-} from "@o3co/auth-provider-core";
-import { createFakeIdp, type FakeIdp } from "@o3co/auth-provider-core/testing";
-import { googleFederationTypeModule } from "@o3co/auth-provider-federation-google";
-import { oidcFederationTypeModule } from "@o3co/auth-provider-federation-oidc";
-import express from "express";
-import request from "supertest";
-import { beforeAll, describe, expect, it } from "vitest";
-import { buildModules } from "#/buildModules.mjs";
-import {
-	configDefaultsFor,
-	type OwnLayers,
-	readOwnLayers,
-	readSwitches,
-	resolveConfigPaths,
-	resolveForBoot,
-	type Switches,
-} from "#/configPath.mjs";
-import { securityHeaders } from "#/securityHeaders.mjs";
-
-export const ISSUER = "https://auth.test";
-const OIDC_ISSUER = "https://idp.test";
-/** Where a federated login lands the browser when the start carried no `redirect_to`. */
-export const FEDERATION_LANDING = "https://app.test/home";
-
-const signingKey = generateKeyPairSync("ed25519", {
-	publicKeyEncoding: { type: "spki", format: "pem" },
-	privateKeyEncoding: { type: "pkcs8", format: "pem" },
-});
-/** 32 bytes, base64 — the shape every at-rest encryption key here takes. */
-const ENCRYPTION_KEY = Buffer.alloc(32, 7).toString("base64");
-
-/**
- * One replica, every store in memory, every feature the template can switch
- * on switched on: the four token grants, the consent step with Client ID
- * Metadata Documents, federation grants, the Google federation and the
- * shipped generic OIDC one. MFA, on by default, is switched off: the suites
- * about MFA turn it on with `MFA_MODE`.
- */
-export const SINGLE_ENV: Readonly<Record<string, string>> = {
-	MFA_MODE: "off",
-	OAUTH_JWT_ISSUER: ISSUER,
-	// The shipped default algorithm (EdDSA), with the key pair inline.
-	KEY_STORE_LOCAL_PRIVATE_KEY: signingKey.privateKey,
-	KEY_STORE_LOCAL_PUBLIC_KEY: signingKey.publicKey,
-	SESSION_STORE_SECRET: "all-modules-composition-session.at-least-32-bytes.ok",
-	SESSION_STORE_SECURE: "false",
-	SESSION_STORE_NAME: "auth.session",
-	CORE_DEPLOYMENT_MODE: "single",
-	SESSION_STORE_STORAGE_TYPE: "memory",
-	ADAPTERS_USER_SESSION_STORES: "memory",
-	ADAPTERS_RATE_LIMITER: "memory",
-	ADAPTERS_ATTEMPT_COUNTER: "memory",
-	ADAPTERS_CODE_REPOSITORY: "memory",
-	ADAPTERS_ACCESS_TOKEN_DENYLIST: "memory",
-	ADAPTERS_REPLAY_SEEN_SET: "memory",
-	ADAPTERS_FEDERATION_TOKEN_STORE: "memory",
-	ADAPTERS_CONSENT_STORE: "memory",
-	ADAPTERS_FEDERATION_GRANT_STORE: "memory",
-	ADAPTERS_FEDERATION_GRANT_INTENT_STORE: "memory",
-	// The user repository is replaced (see the header); `yaml` keeps the
-	// shipped `http` adapter's URL requirements out of config validation.
-	ADAPTERS_USER_REPOSITORY: "yaml",
-	OAUTH_SESSION_ENABLED: "true",
-	OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED: "true",
-	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED: "true",
-	OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED: "true",
-	OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ENABLED: "true",
-	FEDERATION_GRANTS_ENABLED: "true",
-	FEDERATION_GRANTS_CONSENT_URL: "/consent/grants",
-	// The in-memory user repository covers no registration; `required` is a
-	// Store's statement that it does (see the federation-grants README).
-	FEDERATION_GRANTS_IDENTITY_LOOKUP: "unsupported",
-	CORE_FEDERATIONS_GOOGLE_ENABLED: "true",
-	CORE_FEDERATIONS_GOOGLE_CLIENT_ID: "google-client",
-	CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET: "google-secret",
-	CORE_FEDERATIONS_OIDC_ENABLED: "true",
-	CORE_FEDERATIONS_OIDC_ISSUER: OIDC_ISSUER,
-	CORE_FEDERATIONS_OIDC_CLIENT_ID: "oidc-client",
-	CORE_FEDERATIONS_OIDC_CLIENT_SECRET: "oidc-secret",
-};
-
-/**
- * The same deployment on more than one replica: every shared store on Redis,
- * express-session's own included (the umbrella E2E's shape).
- */
-export const MULTI_ENV: Readonly<Record<string, string>> = {
-	...SINGLE_ENV,
-	CORE_DEPLOYMENT_MODE: "multi",
-	SESSION_STORE_STORAGE_TYPE: "redis",
-	SESSION_STORE_STORAGE_REDIS_URL: "redis://redis.test:6379",
-	REDIS_CLIENTS_URL: "redis://redis.test:6379",
-	ADAPTERS_USER_SESSION_STORES: "redis",
-	ADAPTERS_RATE_LIMITER: "redis",
-	// The login's attempt counter, shared: per process, `multi` refuses the login.
-	ADAPTERS_ATTEMPT_COUNTER: "redis",
-	ADAPTERS_CODE_REPOSITORY: "redis",
-	ADAPTERS_ACCESS_TOKEN_DENYLIST: "redis",
-	ADAPTERS_REPLAY_SEEN_SET: "redis",
-	ADAPTERS_FEDERATION_TOKEN_STORE: "redis",
-	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: ENCRYPTION_KEY,
-	ADAPTERS_CONSENT_STORE: "redis",
-	ADAPTERS_FEDERATION_GRANT_STORE: "redis",
-	ADAPTERS_FEDERATION_GRANT_INTENT_STORE: "redis",
-};
-
-/** The grant connection the federation-grant flows use, on the shipped `oidc` federation. */
-export const CONNECTION = "calendar";
-
-const configDir = fileURLToPath(new URL("../../config", import.meta.url));
-
-const quoted = (value: string) => JSON.stringify(value);
-
-/**
- * What has no environment form — the federations' landing page and one grant
- * connection — as an operator writes it: a HOCON file of their own, the
- * highest layer. Written once per process.
- */
-const OPERATOR_LAYER: string = (() => {
-	const file = join(mkdtempSync(join(tmpdir(), "all-modules-composition-")), "operator.conf");
-	writeFileSync(
-		file,
-		`core.federations.google.clientUrl = ${quoted(FEDERATION_LANDING)}
-core.federations.oidc.clientUrl = ${quoted(FEDERATION_LANDING)}
-federation-grants {
-  connections {
-    ${CONNECTION} {
-      federation = "oidc"
-      scopes = ["openid", "offline_access", "calendar.read"]
-      boundary = "production"
-      maxAccessTokenLifetime = 3600
-      callbackURL = ${quoted(`${ISSUER}/session/federation-grants/callback/${CONNECTION}`)}
-    }
-  }
-}
-`,
-	);
-	return file;
-})();
-
-/** `text` in a file of its own, for a layer above the composition's files. */
-function hoconFile(text: string): string {
-	const file = join(mkdtempSync(join(tmpdir(), "all-modules-operator-")), "operator.conf");
-	writeFileSync(file, text);
-	return file;
-}
-
-/**
- * The Redis grant store's key ring, which has no environment form either, in
- * a layer of its own: an operator writes it where that store is installed,
- * since written for a store the composition does not load it reaches nothing
- * and boot may name its section. Written once per process.
- */
-const GRANT_KEY_RING_LAYER: string = (() => {
-	const file = join(mkdtempSync(join(tmpdir(), "all-modules-composition-")), "grant-keys.conf");
-	writeFileSync(
-		file,
-		`redis-federation-grant-store.encryptionKeys = [{ id = "k-test", key = ${quoted(ENCRYPTION_KEY)} }]\n`,
-	);
-	return file;
-})();
-
-/**
- * The composition's own files under `env`, highest first: the operator's
- * layers — the grant key ring among them where `env` turns federation grants
- * on and puts their store on Redis — then the shipped production ones.
- */
-export function ownFiles(env: Readonly<Record<string, string>> = SINGLE_ENV): string[] {
-	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
-	const grantStoreOnRedis =
-		env.FEDERATION_GRANTS_ENABLED === "true" && env.ADAPTERS_FEDERATION_GRANT_STORE === "redis";
-	const keyRing = grantStoreOnRedis ? [GRANT_KEY_RING_LAYER] : [];
-	return [OPERATOR_LAYER, ...keyRing, envConfPath, applicationConfPath];
-}
-
-/**
- * Phase one, as `app.mts` reads it: the switches `buildModules` chooses the
- * modules by, from the composition's own files under `env` over the
- * template's `reference.conf`.
- */
-export function resolveConfig(
-	env: Readonly<Record<string, string>>,
-	own: OwnLayers = readOwnLayers(ownFiles(env), { env }),
-): Switches {
-	return readSwitches(own);
-}
-
-// ---------------------------------------------------------------------------
-// Registrations
-// ---------------------------------------------------------------------------
-
-export const WEB = { id: "web", secret: "web-secret", redirectUri: "https://rp.test/cb" } as const;
-export const M2M = { id: "m2m", secret: "m2m-secret" } as const;
-export const WORKER = {
-	id: "worker",
-	secret: "worker-secret",
-	redirectUri: "https://worker.test/connected",
-} as const;
-/** Not first-party: `/authorize` sends its user through the consent step. */
-export const THIRD = {
-	id: "third",
-	secret: "third-secret",
-	redirectUri: "https://third.test/cb",
-} as const;
-
-export const ALICE = { username: "alice", password: "correct-horse-battery", sub: "u-alice" };
-/** The subjects the fake IdPs sign in, as the Store has them linked. */
-const OIDC_SUB = "idp-sub";
-const GOOGLE_SUB = "google-sub";
-
-type ClientEntry = ReturnType<typeof ClientEntrySchema.parse>;
-
-const clientEntries = (
-	extra: Readonly<Record<string, Record<string, unknown>>> = {},
-): Map<string, ClientEntry> =>
-	new Map<string, ClientEntry>([
-		...Object.entries(extra).map(
-			([id, entry]) => [id, ClientEntrySchema.parse(entry)] as [string, ClientEntry],
-		),
-		[
-			WEB.id,
-			ClientEntrySchema.parse({
-				tokenEndpointAuthMethod: "client_secret_basic",
-				clientSecret: WEB.secret,
-				allowedRedirectUris: [WEB.redirectUri],
-				allowedScopes: ["openid", "profile", "email", "offline_access"],
-				allowedGrantTypes: ["authorization_code", "refresh_token", "session"],
-				firstParty: true,
-			}),
-		],
-		[
-			M2M.id,
-			ClientEntrySchema.parse({
-				tokenEndpointAuthMethod: "client_secret_basic",
-				clientSecret: M2M.secret,
-				allowedScopes: ["api.read"],
-				allowedGrantTypes: ["client_credentials"],
-			}),
-		],
-		[
-			WORKER.id,
-			ClientEntrySchema.parse({
-				tokenEndpointAuthMethod: "client_secret_basic",
-				clientSecret: WORKER.secret,
-				allowedScopes: ["openid"],
-				allowedGrantTypes: [],
-				allowedFederationGrantConnections: [CONNECTION],
-				federationGrantRedirectUris: [WORKER.redirectUri],
-			}),
-		],
-		[
-			THIRD.id,
-			ClientEntrySchema.parse({
-				tokenEndpointAuthMethod: "client_secret_basic",
-				clientSecret: THIRD.secret,
-				allowedRedirectUris: [THIRD.redirectUri],
-				allowedScopes: ["openid"],
-				allowedGrantTypes: ["authorization_code"],
-			}),
-		],
-	]);
-
-const testRepositoriesModule = (
-	extraClients: Readonly<Record<string, Record<string, unknown>>> = {},
-	extraUsers: Readonly<Record<string, Record<string, unknown>>> = {},
-): Module =>
-	defineModule({
-		name: "test:repositories",
-		provides: {
-			clientRepository: () => new InMemoryClientRepository(clientEntries(extraClients)),
-			userRepository: () =>
-				new InMemoryUserRepository(
-					new Map([
-						[
-							ALICE.username,
-							{
-								id: ALICE.sub,
-								password: ALICE.password,
-								email: "alice@example.com",
-								token: `oidc:${OIDC_SUB}`,
-							},
-						],
-						["bob", { id: "u-bob", password: "bob-password-long", token: `google:${GOOGLE_SUB}` }],
-						...Object.entries(extraUsers),
-					]) as ConstructorParameters<typeof InMemoryUserRepository>[0],
-				),
-		},
-	});
-
-// ---------------------------------------------------------------------------
-// Upstream identity providers
-// ---------------------------------------------------------------------------
-
-export interface Upstreams {
-	readonly oidc: FakeIdp;
-	readonly google: FakeIdp;
-}
-
-let upstreams: Promise<{ fakes: Upstreams; reset: () => void }> | undefined;
-
-/**
- * The two fake upstreams, made once per test file — each generates an RSA key,
- * and a login's state lives in the authorization it recorded, so boots can
- * share them — and put back as they were made before every boot (`compose`
- * calls this). A test may set a fake's knobs for its own boot; it may not
- * rotate a fake's key, which cannot be put back, and the next boot refuses to
- * run if one did.
- */
-export async function sharedUpstreams(): Promise<Upstreams> {
-	const { fakes, reset } = await madeUpstreams();
-	reset();
-	return fakes;
-}
-
-/** The two fake upstreams, made on first use and never reset here. */
-function madeUpstreams(): Promise<{ fakes: Upstreams; reset: () => void }> {
-	upstreams ??= createUpstreams().then((fakes) => ({
-		fakes,
-		reset: resettable(fakes.oidc, fakes.google),
-	}));
-	return upstreams;
-}
-
-/** A `fetch` that reaches the shared fake upstream `name`. */
-const upstreamFetch =
-	(name: keyof Upstreams): typeof fetch =>
-	async (input, init) =>
-		(await madeUpstreams()).fakes[name].fetch(input, init);
-
-/**
- * The federation type modules `buildModules` lists, by name, each built as
- * the template builds it but with a `fetch` that reaches its fake upstream.
- */
-const UPSTREAM_TYPE_MODULES: ReadonlyMap<string, () => Module> = new Map([
-	[
-		googleFederationTypeModule().name,
-		() => googleFederationTypeModule({ fetch: upstreamFetch("google") }),
-	],
-	[
-		oidcFederationTypeModule().name,
-		() => oidcFederationTypeModule({ fetch: upstreamFetch("oidc") }),
-	],
-]);
-
-/**
- * Snapshots each fake's settings (every property that is not a function) and
- * returns what puts them back: primitives reassigned, objects restored in
- * place (a fake may hold its own reference to one), recorded requests
- * cleared. A fake's signing key is checked, not restored: a rotated key is
- * refused.
- *
- * A fake's closure is not restored: core's fake IdP remembers whether consent
- * was granted (`consentGranted`), how many codes it issued (`codesIssued`) and
- * every authorization it recorded.
- * Codes and authorizations are keyed per login; consent is not, and it decides
- * Google's refresh token only under `refreshTokenOnlyOnConsent`. That knob is
- * therefore forbidden on a shared fake (the next reset refuses to run if a test
- * set it); a test that needs it makes its own fake with `createFakeIdp`.
- */
-export function resettable(...fakes: readonly object[]): () => void {
-	const snapshots = fakes.map((fake) => ({
-		fake: fake as Record<string, unknown>,
-		clone: new Map(
-			Object.entries(fake)
-				.filter(([name, value]) => typeof value !== "function" && name !== "requests")
-				.map(([name, value]) => [name, structuredClone(value)]),
-		),
-		kid: currentKidOf(fake),
-	}));
-	return () => {
-		for (const { fake, clone, kid } of snapshots) {
-			if (fake.refreshTokenOnlyOnConsent === true) {
-				throw new Error(
-					"a test set refreshTokenOnlyOnConsent on a shared fake upstream: the consent it reads is closure state no reset restores; make a fake of its own instead",
-				);
-			}
-			if (currentKidOf(fake) !== kid) {
-				throw new Error(
-					"a test rotated a shared fake upstream's key: the fakes are shared by every boot in the file; make a fake of its own instead",
-				);
-			}
-			for (const [name, original] of clone) {
-				const current = fake[name];
-				if (typeof current === "object" && current !== null && !Array.isArray(current)) {
-					for (const key of Object.keys(current)) delete (current as Record<string, unknown>)[key];
-					Object.assign(current, structuredClone(original));
-				} else {
-					fake[name] = structuredClone(original);
-				}
-			}
-			const requests = fake.requests;
-			if (Array.isArray(requests)) requests.splice(0);
-		}
-	};
-}
-
-const currentKidOf = (fake: object): string | undefined => {
-	const currentKid = (fake as { currentKid?: unknown }).currentKid;
-	return typeof currentKid === "function" ? (currentKid as () => string)() : undefined;
-};
-
-async function createUpstreams(): Promise<Upstreams> {
-	return {
-		oidc: await createFakeIdp({
-			issuer: OIDC_ISSUER,
-			discovery: true,
-			clientId: SINGLE_ENV.CORE_FEDERATIONS_OIDC_CLIENT_ID,
-			sub: OIDC_SUB,
-		}),
-		// Google's endpoints are fixed in the adapter, not discovered.
-		google: await createFakeIdp({
-			issuer: "https://accounts.google.com",
-			authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
-			tokenEndpoint: "https://oauth2.googleapis.com/token",
-			jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
-			userinfoEndpoint: "https://www.googleapis.com/oauth2/v3/userinfo",
-			clientId: SINGLE_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_ID,
-			sub: GOOGLE_SUB,
-		}),
-	};
-}
-
-// ---------------------------------------------------------------------------
-// Logger spy
-// ---------------------------------------------------------------------------
-
-export interface LogLine {
-	readonly level: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
-	readonly args: readonly unknown[];
-}
-
-export interface RecordingLogger extends Logger {
-	readonly lines: LogLine[];
-}
-
-/** A `Logger` that records every call, its children's included, in one list. */
-export function createRecordingLogger(): RecordingLogger {
-	const lines: LogLine[] = [];
-	const make = (bindings: Record<string, unknown>): Logger => {
-		const at =
-			(level: LogLine["level"]) =>
-			(...args: unknown[]): void => {
-				const [first, ...rest] = args;
-				lines.push({
-					level,
-					args:
-						typeof first === "object" && first !== null && Object.keys(bindings).length > 0
-							? [{ ...bindings, ...first }, ...rest]
-							: args,
-				});
-			};
-		return {
-			trace: at("trace"),
-			debug: at("debug"),
-			info: at("info"),
-			warn: at("warn"),
-			error: at("error"),
-			fatal: at("fatal"),
-			child: (more) => make({ ...bindings, ...more }),
-		} as Logger;
-	};
-	return Object.assign(make({}), { lines }) as RecordingLogger;
-}
-
-// ---------------------------------------------------------------------------
-// Composition
-// ---------------------------------------------------------------------------
-
-/** A switch an outage wrapper reads on every call. */
-export interface Outage {
-	down: boolean;
-}
-
-/** What a store adapter's client throws when its connection is refused. */
-const connectionRefused = (): Error =>
-	Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:6379"), { code: "ECONNREFUSED" });
-
-/** Every method of `target` rejects while `outage.down`, and is the real one otherwise. */
-function failWhileDown<T extends object>(target: T, outage: Outage): T {
-	return new Proxy(target, {
-		get(object, property) {
-			const value = Reflect.get(object, property, object);
-			if (typeof value !== "function") return value;
-			return (...args: unknown[]): unknown =>
-				outage.down
-					? Promise.reject(connectionRefused())
-					: (value as (...a: unknown[]) => unknown).apply(object, args);
-		},
-	});
-}
-
-/**
- * `modules` with the provider of `slot` wrapped by {@link failWhileDown}: the
- * real module, named and declared as it is, handing out the real store.
- */
-function withOutage(modules: readonly Module[], slot: string, outage: Outage): Module[] {
-	let found = false;
-	const wrapped = modules.map((module) => {
-		const provides = module.provides as
-			| Record<string, (deps: unknown) => unknown | Promise<unknown>>
-			| undefined;
-		const provider = provides?.[slot];
-		if (provider === undefined) return module;
-		found = true;
-		return {
-			...module,
-			provides: {
-				...provides,
-				[slot]: async (deps: unknown) => failWhileDown((await provider(deps)) as object, outage),
-			},
-		} as Module;
-	});
-	if (!found) throw new Error(`no module in the composition provides ${slot}`);
-	return wrapped;
-}
-
-/** The order `buildModules` lists the modules in. */
-export const AS_LISTED = "as listed";
-/**
- * Every module after the first in reverse. The first, express-session's
- * middleware, is placed by list position alone (`buildModules` says so), so
- * it stays first; everything else changes place.
- */
-export const REVERSED = "reversed";
-export type ModuleOrder = typeof AS_LISTED | typeof REVERSED;
-
-export interface ComposeOptions {
-	readonly env?: Readonly<Record<string, string>>;
-	/** The name the configuration was selected by, as `app.mts` hands `buildModules` it; `production` by default. */
-	readonly environment?: string;
-	/** HOCON an operator writes above the composition's own files, read in both phases. */
-	readonly operatorHocon?: string;
-	/** The deployment's own mail sender modules, handed to `buildModules` as `mailSenderModules`. */
-	readonly mailSenderModules?: readonly Module[];
-	/** Modules added after the template's own, before the order and the outage apply. */
-	readonly extraModules?: (config: Switches) => readonly Module[];
-	/** Components laid over the boot's (`overrideComponents`). */
-	readonly extraOverrides?: (config: Switches) => Record<string, unknown>;
-	/** Client registrations beside the fixture's own, as `ClientEntrySchema` input. */
-	readonly extraClients?: Readonly<Record<string, Record<string, unknown>>>;
-	/** Users beside the fixture's own, keyed by username. */
-	readonly extraUsers?: Readonly<Record<string, Record<string, unknown>>>;
-	/**
-	 * Adjust what `createApp` is handed, as resolved, as an operator's own
-	 * layer would.
-	 */
-	readonly config?: (config: AppConfig) => AppConfig;
-	/**
-	 * Adjust phase one's switches: what only phase one reads, such as the
-	 * Store transport settings a hand-built root passes.
-	 */
-	readonly switches?: (switches: Switches) => Switches;
-	readonly order?: ModuleOrder;
-	readonly outage?: { readonly slot: string; readonly outage: Outage };
-	/** Keep the shipped Redis refresh-token family store (the `multi` boot). */
-	readonly shippedRefreshTokenFamilyStore?: boolean;
-	/**
-	 * Mount core's terminal error handler after the composed router again, as
-	 * `app.mts` does for its host routes (the default). `false` mounts the
-	 * router alone, as a composition root that copies nothing of `app.mts`
-	 * does.
-	 */
-	readonly terminalErrorHandler?: boolean;
-}
-
-/** The module list the template boots for `config`, as `app.mts` builds it. */
-export function composedModules(config: Switches, options: ComposeOptions = {}): Module[] {
-	let modules = [
-		...buildModules(config, {
-			environment: options.environment ?? "production",
-			repositoriesModule: testRepositoriesModule(options.extraClients, options.extraUsers),
-			...(options.mailSenderModules === undefined
-				? {}
-				: { mailSenderModules: options.mailSenderModules }),
-			...(options.shippedRefreshTokenFamilyStore
-				? {}
-				: { refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule] }),
-		}).map((module) => UPSTREAM_TYPE_MODULES.get(module.name)?.() ?? module),
-		...(options.extraModules?.(config) ?? []),
-	];
-	if (options.outage) modules = withOutage(modules, options.outage.slot, options.outage.outage);
-	if (options.order === REVERSED) modules = [modules[0], ...modules.slice(1).reverse()];
-	return modules;
-}
-
-export interface Composition {
-	readonly app: express.Express;
-	readonly handle: Awaited<ReturnType<typeof createApp>>;
-	/** The configuration boot parsed: what the handle's `config` slot holds. */
-	readonly config: AppConfig;
-	/** What `createApp` was handed: the configuration as resolved (phase two), unparsed. */
-	readonly resolved: AppConfig;
-	readonly modules: readonly Module[];
-	readonly logger: RecordingLogger;
-	readonly upstreams: Upstreams;
-}
-
-/**
- * Boots the composition and mounts it as `app.mts` does: its security headers
- * (`securityHeaders`), the composed router, and the terminal error handler last (unless
- * `terminalErrorHandler` is `false`), all on one logger that is also the
- * boot's `logger` component.
- */
-export async function compose(options: ComposeOptions = {}): Promise<Composition> {
-	const env = options.env ?? SINGLE_ENV;
-	// The composition's own layers, read once for both phases, as `app.mts`
-	// reads them. Phase one: the switches the modules are chosen by.
-	const own = readOwnLayers(
-		options.operatorHocon === undefined
-			? ownFiles(env)
-			: [hoconFile(options.operatorHocon), ...ownFiles(env)],
-		{ env },
-	);
-	const switches = resolveConfig(env, own);
-	const config = options.switches ? options.switches(switches) : switches;
-	const fakes = await sharedUpstreams();
-	const modules = composedModules(config, options);
-	const logger = createRecordingLogger();
-	// Phase two: the configuration as resolved over every loaded package's
-	// reference.conf, which createApp parses once, and its defaults.
-	const forBoot = resolveForBoot(own, modules, config);
-	const resolved = options.config ? options.config(forBoot) : forBoot;
-	const handle = await createApp({
-		modules,
-		bootstrapComponents: {
-			config: resolved,
-			configDefaults: configDefaultsFor(modules),
-			pathResolver: (s) => s,
-			logger,
-		},
-		overrideComponents: { ...options.extraOverrides?.(config) } as never,
-	});
-	const parsed = handle.components.config;
-	if (parsed === undefined) throw new Error("createApp booted without the parsed configuration");
-	const httpSettings = handle.components.httpSettings;
-	if (httpSettings === undefined) throw new Error("createApp booted without httpSettings");
-	const app = express();
-	app.set("trust proxy", httpSettings.trustProxy);
-	app.use(securityHeaders());
-	app.use(handle.router);
-	if (options.terminalErrorHandler !== false) app.use(terminalErrorHandler(logger));
-	return { app, handle, config: parsed, resolved, modules, logger, upstreams: fakes };
-}
-
-// ---------------------------------------------------------------------------
-// Flows
-// ---------------------------------------------------------------------------
-
-export const basic = (client: { id: string; secret: string }): string =>
-	`Basic ${Buffer.from(`${client.id}:${client.secret}`).toString("base64")}`;
-
-const cookiesOf = (res: request.Response): string[] =>
-	(res.headers["set-cookie"] as unknown as string[] | undefined) ?? [];
-
-/** The browser half: a CSRF pair, then the password login. */
-export async function login(
-	app: express.Express,
-): Promise<{ readonly res: request.Response; readonly cookies: string[] }> {
-	const csrf = await request(app).get("/session/csrf");
-	const res = await request(app)
-		.post("/session/login")
-		.set("Cookie", cookiesOf(csrf))
-		.set(csrf.body.header_name as string, csrf.body.csrf_token as string)
-		.type("form")
-		.send({ username: ALICE.username, password: ALICE.password });
-	return { res, cookies: res.status === 200 ? cookiesOf(res) : cookiesOf(csrf) };
-}
-
-export const PKCE = (() => {
-	const verifier = randomBytes(32).toString("base64url");
-	return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
-})();
-
-export function authorize(
-	app: express.Express,
-	cookies: readonly string[],
-	client: { id: string; redirectUri: string } = WEB,
-): request.Test {
-	return request(app)
-		.get("/oauth/authorize")
-		.set("Cookie", [...cookies])
-		.query({
-			response_type: "code",
-			client_id: client.id,
-			redirect_uri: client.redirectUri,
-			scope: client === WEB ? "openid profile offline_access" : "openid",
-			state: "af0ifjsldkj",
-			nonce: "n-0S6_WzA2Mj",
-			code_challenge: PKCE.challenge,
-			code_challenge_method: "S256",
-		});
-}
-
-export const codeFrom = (res: request.Response): string => {
-	const code = new URL(res.headers.location as string).searchParams.get("code");
-	if (code === null) throw new Error(`no code in ${res.status} ${res.headers.location}`);
-	return code;
-};
-
-export function redeem(app: express.Express, code: string): request.Test {
-	return request(app).post("/oauth/token").set("Authorization", basic(WEB)).type("form").send({
-		grant_type: "authorization_code",
-		code,
-		redirect_uri: WEB.redirectUri,
-		code_verifier: PKCE.verifier,
-	});
-}
-
-/** Log in, authorize with PKCE, redeem: the web client's tokens. */
-export async function webTokens(app: express.Express): Promise<Record<string, string>> {
-	const { cookies } = await login(app);
-	const res = await redeem(app, codeFrom(await authorize(app, cookies)));
-	if (res.status !== 200) throw new Error(`code exchange answered ${res.status}`);
-	return res.body as Record<string, string>;
-}
-
-/**
- * Start a federated login and play the upstream. What comes back sends the
- * callback when called — a function, because a supertest request is a
- * thenable, and returning one from an async function would send it.
- */
-export async function federatedCallback(
-	app: express.Express,
-	name: "oidc" | "google",
-	upstream: FakeIdp,
-): Promise<() => request.Test> {
-	const start = await request(app).get(`/session/oauth/federation/${name}`);
-	if (start.status !== 302) throw new Error(`federation start answered ${start.status}`);
-	const answer = upstream.authorize(start.headers.location as string);
-	return () =>
-		request(app)
-			.get(`/session/oauth/federation/${name}/callback`)
-			.set("Cookie", cookiesOf(start))
-			.query({ code: answer.code, state: answer.state ?? "", iss: answer.iss });
-}
-
-export function lodgeGrant(app: express.Express): request.Test {
-	return request(app).post("/oauth/federation-grants").set("Authorization", basic(WORKER)).send({
-		connection: CONNECTION,
-		sub: ALICE.sub,
-		redirect_uri: WORKER.redirectUri,
-		state: "worker-state",
-	});
-}
-
-export { cookiesOf };
-
-// ---------------------------------------------------------------------------
-// Discovery
-// ---------------------------------------------------------------------------
-
-export const DISCOVERY_PATHS = [
-	"/.well-known/openid-configuration",
-	"/.well-known/oauth-authorization-server",
-] as const;
-
-/**
- * What RFC 8414 §2 and OpenID Connect Discovery §3 require of the document
- * this composition serves, and what each advertised URL must be: https, on
- * the issuer's origin. `authorizationCode` says whether the composition
- * registers that grant (it does unless a test switches it off): with it the
- * document names the authorization endpoint and lists the code response type
- * and PKCE; without it, none of them.
- */
-export function expectValidMetadata(
-	doc: Record<string, unknown>,
-	{ authorizationCode = true }: { readonly authorizationCode?: boolean } = {},
-): void {
-	expect(doc.issuer).toBe(ISSUER);
-	for (const field of [
-		"token_endpoint",
-		"jwks_uri",
-		"response_types_supported",
-		"subject_types_supported",
-		"id_token_signing_alg_values_supported",
-	]) {
-		expect(doc[field], field).toBeDefined();
-	}
-	for (const [field, value] of Object.entries(doc)) {
-		if (field.endsWith("_endpoint") || field === "jwks_uri") {
-			const url = new URL(value as string);
-			expect(url.origin, field).toBe(ISSUER);
-			expect(url.search + url.hash, field).toBe("");
-		}
-		if (field.endsWith("_supported") && Array.isArray(value)) {
-			if (field !== "response_types_supported") expect(value.length, field).toBeGreaterThan(0);
-			for (const entry of value) expect(typeof entry, field).toBe("string");
-			expect(new Set(value).size, `${field} repeats a value`).toBe(value.length);
-		}
-	}
-	if (authorizationCode) {
-		expect(doc.authorization_endpoint).toBe(`${ISSUER}/oauth/authorize`);
-		expect(doc.response_types_supported).toEqual(["code"]);
-		expect(doc.code_challenge_methods_supported).toEqual(["S256"]);
-	} else {
-		expect(doc).not.toHaveProperty("authorization_endpoint");
-		expect(doc.response_types_supported).toEqual([]);
-		expect(doc).not.toHaveProperty("code_challenge_methods_supported");
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Known defects
-// ---------------------------------------------------------------------------
-
-const templateManifest = JSON.parse(
-	readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
-) as { dependencies: Record<string, string> };
-
-/** The template's `@o3co/auth-provider-*` dependencies, as its `package.json` names them. */
-export const TEMPLATE_DEPENDENCIES: readonly string[] = Object.keys(
-	templateManifest.dependencies,
-).filter((name) => name.startsWith("@o3co/auth-provider-"));
-
-/**
- * Inside the monorepo the template names its siblings `workspace:*`; a
- * scaffold, and CI's packed-tarball run, name versions or tarballs.
- */
-export const inMonorepo =
-	templateManifest.dependencies["@o3co/auth-provider-core"]?.startsWith("workspace:") === true;
-
-/**
- * A contract the composition breaks today. `it.fails` in the monorepo, where
- * the fix lands beside this file and flips it; skipped in a scaffold, which
- * pins released packages and would otherwise turn red on the upgrade that
- * carries the fix.
- */
-export const knownDefect = (inMonorepo ? it.fails : it.skip) as unknown as typeof it;
-
-// ---------------------------------------------------------------------------
-// Manifests
-// ---------------------------------------------------------------------------
-
-/** The names a module contributes under `kind`: its own name for a list-shaped kind. */
-export const contributionNames = (module: Module, kind: string): string[] => {
-	const contribution = (module.contributes as Record<string, unknown> | undefined)?.[kind];
-	if (contribution === undefined) return [];
-	return Array.isArray(contribution) ? [module.name] : Object.keys(contribution as object);
-};
-
-// ---------------------------------------------------------------------------
-// Bodies
-// ---------------------------------------------------------------------------
-
-export const KIB = 1024;
-export const JSON_TYPE = "application/json";
-export const FORM_TYPE = "application/x-www-form-urlencoded";
-
-export type Send = (
-	app: express.Express,
-	path: string,
-	contentType: string,
-	body: string,
-	headers?: Record<string, string>,
-) => Promise<{ status: number; body: Record<string, unknown> }>;
-
-/** A POST with its `Content-Length` declared, through supertest. */
-export const withLength: Send = async (app, path, contentType, body, headers = {}) => {
-	const res = await request(app)
-		.post(path)
-		.set(headers)
-		.set("Content-Type", contentType)
-		.send(body);
-	return { status: res.status, body: res.body as Record<string, unknown> };
-};
-
-/**
- * A POST whose body has no `Content-Length` — `Transfer-Encoding: chunked`,
- * one KiB a chunk — so only a parser's own running count can bound it.
- * supertest always sets the length, hence a raw request on a real socket.
- */
-export const postChunked: Send = async (app, path, contentType, body, headers = {}) => {
-	const server = http.createServer(app);
-	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
-	try {
-		const { port } = server.address() as AddressInfo;
-		return await new Promise((resolve, reject) => {
-			let answered = false;
-			const req = http.request(
-				{
-					host: "127.0.0.1",
-					port,
-					path,
-					method: "POST",
-					// One connection per request, closed after it: nothing keeps the server open.
-					agent: false,
-					headers: { ...headers, "content-type": contentType, "transfer-encoding": "chunked" },
-				},
-				(res) => {
-					answered = true;
-					let text = "";
-					res.setEncoding("utf8");
-					res.on("data", (chunk: string) => {
-						text += chunk;
-					});
-					res.on("end", () => {
-						let parsed: Record<string, unknown> = {};
-						try {
-							parsed = JSON.parse(text) as Record<string, unknown>;
-						} catch {
-							// Not JSON: the status carries the verdict.
-						}
-						resolve({ status: res.statusCode ?? 0, body: parsed });
-					});
-				},
-			);
-			// A server that answers 413 mid-body may close the socket while the
-			// rest is still being written; that is the answer, not a failure.
-			req.on("error", (err) => {
-				if (!answered) reject(err);
-			});
-			for (let at = 0; at < body.length; at += KIB) req.write(body.slice(at, at + KIB));
-			req.end();
-		});
-	} finally {
-		await new Promise<void>((resolve) => server.close(() => resolve()));
-	}
-};
-
-export const TRANSFERS: ReadonlyArray<readonly [string, Send]> = [
-	["with Content-Length", withLength],
-	["chunked", postChunked],
-];
-
-/** A JSON body: `fields`, and `bytes` of padding. */
-export const padJson = (bytes: number, fields: Record<string, unknown> = {}): string =>
-	JSON.stringify({ ...fields, pad: "a".repeat(bytes) });
-
-/** A form body: `fields`, and `bytes` of padding. */
-export const padForm = (bytes: number, fields: string): string =>
-	`${fields}&pad=${"a".repeat(bytes)}`;
-
-/**
- * What a parser's refusal of an oversized body is answered with on a route
- * of the composed router — by core's terminal handler, which ends it.
- */
-export const TOO_LARGE = { error: "invalid_request", error_description: "body_too_large" };
-
-// ---------------------------------------------------------------------------
-// Outages
-// ---------------------------------------------------------------------------
-
-/**
- * The parts of the outage rule, each checked on its own so a case pins
- * only what is broken and asserts the rest:
- *
- * - `answer` — the status and error code (a redirect's location and code);
- * - `one-error-line` — exactly one error-level line, object-first with a name;
- * - `event-name` — that name (checked only where the case names one);
- * - `store-field` — a `store`, `step` or `site` field naming what failed;
- * - `projection` — its `err` is core's `loggableError` projection;
- * - `no-warn` — no warn line for the outage beside it.
- */
-export type OutagePredicate =
-	| "answer"
-	| "one-error-line"
-	| "event-name"
-	| "store-field"
-	| "projection"
-	| "no-warn";
-
-export interface OutageCase<C extends Composition = Composition> {
-	/** The module whose route answers. */
-	readonly module: string;
-	/** The ComponentMap slot whose store goes down. */
-	readonly slot: string;
-	readonly surface: string;
-	/** Drives the route, taking the store down at the step under test. */
-	readonly run: (app: express.Express, outage: Outage, c: C) => Promise<request.Response>;
-	readonly answer:
-		| { readonly status: number; readonly error?: string }
-		| { readonly redirect: string; readonly error: string };
-	/**
-	 * The one line's name. Absent where the composition writes no such line
-	 * today — and then `event-name` is not checked at all, so the fix that
-	 * flips such a row adds its `event` in the same change.
-	 */
-	readonly event?: string;
-	/** Warn lines this route writes whatever the store does — not the outage's. */
-	readonly unrelatedWarns?: readonly string[];
-	/**
-	 * Why `store-field` does not apply: the line is not an outage's 503, the
-	 * request succeeds. Absent, the predicate is checked.
-	 */
-	readonly storeFieldNotRequired?: string;
-	/** The predicates the composition breaks today, each naming its defect. */
-	readonly defects?: Partial<Record<OutagePredicate, string>>;
-	/**
-	 * The warn lines a `no-warn` defect writes, pinned exactly while it stands,
-	 * so the defect covers those lines and no other.
-	 */
-	readonly defectWarns?: readonly string[];
-}
-
-/** The same defect text for every predicate that depends on the one missing line. */
-export const withoutTheLine = (
-	defect: string,
-): Pick<Record<OutagePredicate, string>, "one-error-line" | "store-field" | "projection"> => ({
-	"one-error-line": defect,
-	"store-field": `no error line to carry it: ${defect}`,
-	projection: `no error line to carry it: ${defect}`,
-});
-
-/** The object argument of a log line, when the line is object-first. */
-export const fieldsOf = (line: LogLine | undefined): Record<string, unknown> =>
-	typeof line?.args[0] === "object" && line.args[0] !== null
-		? (line.args[0] as Record<string, unknown>)
-		: {};
-
-/**
- * One `describe` per case: the case's composition is booted and its flow run
- * once, the store taken down at the step under test, and each predicate is its
- * own test — a plain `it` where the composition keeps it, `knownDefect` where
- * it does not.
- */
-export function describeOutages<C extends Composition>(
-	title: string,
-	cases: readonly OutageCase<C>[],
-	boot: (outage: { readonly slot: string; readonly outage: Outage }) => Promise<C>,
-): void {
-	describe(title, () => {
-		for (const c of cases) {
-			if (
-				c.defectWarns !== undefined &&
-				(c.defects?.["no-warn"] === undefined || c.defectWarns.length === 0)
-			) {
-				throw new Error(
-					`${c.module}: ${c.slot} down at ${c.surface}: defectWarns pins the lines of a no-warn defect, so it needs defects["no-warn"] and at least one line`,
-				);
-			}
-			describe(`${c.module}: ${c.slot} down at ${c.surface}`, () => {
-				let res: request.Response;
-				let lines: LogLine[] = [];
-				let tookDown = false;
-
-				beforeAll(async () => {
-					let composition: C | undefined;
-					let from = -1;
-					let down = false;
-					const outage: Outage = {
-						get down() {
-							return down;
-						},
-						set down(value: boolean) {
-							if (value && from < 0) from = composition?.logger.lines.length ?? 0;
-							down = value;
-						},
-					};
-					composition = await boot({ slot: c.slot, outage });
-					try {
-						res = await c.run(composition.app, outage, composition);
-						tookDown = from >= 0;
-						// Everything logged from the moment the store went down is the outage's.
-						lines = composition.logger.lines.slice(Math.max(from, 0));
-					} finally {
-						await composition.handle.dispose();
-					}
-				});
-
-				const errors = () => lines.filter((line) => line.level === "error");
-				const check = (predicate: OutagePredicate, name: string, assertion: () => void) => {
-					const defect = c.defects?.[predicate];
-					(defect === undefined ? it : knownDefect)(name, assertion);
-				};
-
-				// Plain whatever the case pins: a pinned predicate must fail for its
-				// defect, not because the flow never reached the step under test.
-				it("reaches the step under test and takes the store down there", () => {
-					expect(tookDown).toBe(true);
-				});
-				check("answer", "answers as an outage", () => {
-					if ("redirect" in c.answer) {
-						expect(res.status).toBe(302);
-						const location = new URL(res.headers.location as string);
-						expect(`${location.origin}${location.pathname}`).toBe(c.answer.redirect);
-						expect(location.searchParams.get("error")).toBe(c.answer.error);
-					} else {
-						expect(res.status).toBe(c.answer.status);
-						expect(res.body.error).toBe(c.answer.error);
-						expect(res.headers["www-authenticate"]).toBeUndefined();
-					}
-				});
-				check("one-error-line", "logs exactly one error line, object-first with a name", () => {
-					expect(
-						errors().map((line) => line.args[1] ?? line.args[0]),
-						"exactly one error line",
-					).toHaveLength(1);
-					expect(typeof errors()[0]?.args[0]).toBe("object");
-					expect(typeof errors()[0]?.args[1]).toBe("string");
-				});
-				if (c.event !== undefined) {
-					const event = c.event;
-					check("event-name", `names it ${event}`, () => {
-						expect(errors().map((line) => line.args[1])).toEqual([event]);
-					});
-				}
-				if (c.storeFieldNotRequired === undefined) {
-					check("store-field", "names what failed (store, step or site)", () => {
-						const fields = fieldsOf(errors()[0]);
-						expect(
-							["store", "step", "site"].filter((field) => typeof fields[field] === "string"),
-						).not.toEqual([]);
-					});
-				}
-				check("projection", "carries the error's projection", () => {
-					const err = fieldsOf(errors()[0]).err;
-					expect(err).toMatchObject({ name: expect.any(String) });
-					expect(err).not.toBeInstanceOf(Error);
-				});
-				const outageWarns = () =>
-					lines
-						.filter((line) => line.level === "warn")
-						.map((line) => (typeof line.args[1] === "string" ? line.args[1] : String(line.args[0])))
-						.filter((event) => !(c.unrelatedWarns ?? []).includes(event));
-				check("no-warn", "writes no warn line for it", () => {
-					expect(outageWarns()).toEqual([]);
-				});
-				if (c.defectWarns !== undefined) {
-					const pinned = c.defectWarns;
-					it(`writes exactly the warn lines its no-warn defect names: ${pinned.join(", ")}`, () => {
-						expect(outageWarns()).toEqual(pinned);
-					});
-				}
-			});
-		}
-	});
-}