@o3co/create-auth-provider 0.16.0 → 0.17.0-rc.2

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

@@ -19,43 +19,38 @@
  * template can turn on, switched on together from the shipped HOCON, and
  * mounted the way `app.mts` mounts it.
  *
- * What is real: the configuration (`config/*.conf` over core's
- * `reference.conf`, resolved with the environment a deployment would export),
- * `buildModules`, core's `createApp`, every module and store it selects, the
- * key store, the audit sink, `helmet` and the terminal error handler.
+ * 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, `helmet` and the
+ * terminal error handler.
  *
- * What is substituted, and why:
+ * 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.
  *
- * - The client and user repositories — `repositoriesModule` reads YAML files
- *   off disk; the in-memory repositories carry the registrations the flows
- *   need. `buildModules` offers this override for the purpose.
- * - The refresh-token family store under `deployment.mode = "single"` — the
- *   shipped composition always puts it on Redis; the memory store keeps the
- *   single-replica boot free of sockets. `buildModules` offers this override.
- * - The upstream identity providers — core's fake OpenID Provider behind a
- *   `fetch`, handed to the Google and OIDC adapters through the `fetch` option
- *   each adapter takes for exactly this. The config bridges' values are read
- *   through the template's own bridge (`googleFederationConfigModule`) and the
- *   OIDC package's reader, and only `fetch` is added.
- * - Configuration with no environment form (a map of grant connections, a key
- *   ring, a landing URL): laid over the resolved config, as an operator would
- *   write it in `application.conf`.
- *
- * `tools/composition` in the monorepo imports this file and boots the same
+ * `tools/composition` in the monorepo imports this file to boot the same
  * composition with the workspace's other modules added (`ComposeOptions`'s
- * `referenceConfs`, `extraModules`, `extraOverrides`, `extraClients` and
- * `extraUsers`), so the two suites share one fixture rather than two copies
- * that drift.
+ * `extra*` options), so the two suites share one fixture.
  */
 
 import { createHash, generateKeyPairSync, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+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,
-	AppConfigSchema,
 	ClientEntrySchema,
 	createApp,
 	defineModule,
@@ -67,15 +62,22 @@ import {
 	terminalErrorHandler,
 } from "@o3co/auth-provider-core";
 import { createFakeIdp, type FakeIdp } from "@o3co/auth-provider-core/testing";
-import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
+import { googleFederationTypeModule } from "@o3co/auth-provider-federation-google";
+import { oidcFederationTypeModule } from "@o3co/auth-provider-federation-oidc";
 import express from "express";
 import helmet from "helmet";
 import request from "supertest";
 import { beforeAll, describe, expect, it } from "vitest";
 import { buildModules } from "#/buildModules.mjs";
-import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "#/configPath.mjs";
-import { googleFederationConfigModule, oidcFederationConfigModule } from "#/modules.mjs";
+import {
+	configDefaultsFor,
+	type OwnLayers,
+	readOwnLayers,
+	readSwitches,
+	resolveConfigPaths,
+	resolveForBoot,
+	type Switches,
+} from "#/configPath.mjs";
 
 export const ISSUER = "https://auth.test";
 const OIDC_ISSUER = "https://idp.test";
@@ -93,47 +95,50 @@ 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.
+ * 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.
-	OAUTH_JWT_PRIVATE_KEY: signingKey.privateKey,
-	OAUTH_JWT_PUBLIC_KEY: signingKey.publicKey,
-	SESSION_SECRET: "all-modules-composition-session.at-least-32-bytes.ok",
-	SESSION_SECURE: "false",
-	SESSION_NAME: "auth.session",
-	DEPLOYMENT_MODE: "single",
-	SESSION_STORAGE_TYPE: "memory",
-	USER_SESSION_STORES_ADAPTER: "memory",
-	RATE_LIMITER_ADAPTER: "memory",
-	OAUTH_CODE_ADAPTER: "memory",
-	ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
-	REPLAY_SEEN_SET_ADAPTER: "memory",
-	FEDERATION_TOKEN_STORE_TYPE: "memory",
-	CONSENT_STORE_ADAPTER: "memory",
-	FEDERATION_GRANT_STORE_ADAPTER: "memory",
-	FEDERATION_GRANT_INTENT_STORE_ADAPTER: "memory",
+	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.
-	CLIENT_USER_TYPE: "yaml",
-	OAUTH_GRANTS_SESSION_ENABLED: "true",
-	OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED: "true",
-	OAUTH_GRANTS_REFRESH_TOKEN_ENABLED: "true",
-	OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED: "true",
-	OAUTH_CIMD_ENABLED: "true",
+	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",
-	FEDERATIONS_GOOGLE_ENABLED: "true",
-	FEDERATIONS_GOOGLE_CLIENT_ID: "google-client",
-	FEDERATIONS_GOOGLE_CLIENT_SECRET: "google-secret",
-	FEDERATIONS_OIDC_ENABLED: "true",
-	FEDERATIONS_OIDC_ISSUER: OIDC_ISSUER,
-	FEDERATIONS_OIDC_CLIENT_ID: "oidc-client",
-	FEDERATIONS_OIDC_CLIENT_SECRET: "oidc-secret",
+	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",
 };
 
 /**
@@ -142,20 +147,22 @@ export const SINGLE_ENV: Readonly<Record<string, string>> = {
  */
 export const MULTI_ENV: Readonly<Record<string, string>> = {
 	...SINGLE_ENV,
-	DEPLOYMENT_MODE: "multi",
-	SESSION_STORAGE_TYPE: "redis",
-	SESSION_STORAGE_REDIS_URL: "redis://redis.test:6379",
-	REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "redis://redis.test:6379",
-	USER_SESSION_STORES_ADAPTER: "redis",
-	RATE_LIMITER_ADAPTER: "redis",
-	OAUTH_CODE_ADAPTER: "redis",
-	ACCESS_TOKEN_DENYLIST_ADAPTER: "redis",
-	REPLAY_SEEN_SET_ADAPTER: "redis",
-	FEDERATION_TOKEN_STORE_TYPE: "redis",
+	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,
-	CONSENT_STORE_ADAPTER: "redis",
-	FEDERATION_GRANT_STORE_ADAPTER: "redis",
-	FEDERATION_GRANT_INTENT_STORE_ADAPTER: "redis",
+	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. */
@@ -163,46 +170,80 @@ export const CONNECTION = "calendar";
 
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
+const quoted = (value: string) => JSON.stringify(value);
+
 /**
- * The shipped HOCON under `env`, with what has no environment form laid over
- * it: the federations' landing page, the grant key ring and one grant
- * connection. `referenceConfs` — other packages' `reference.conf` files — are
- * layered between `application.conf` and core's, as a deployment layers them.
+ * 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>>,
-	referenceConfs: readonly string[] = [],
-): AppConfig {
-	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
-	const read = (path: string) => parseFile(path, { env: { ...env } });
-	const layered = [
-		applicationConfPath,
-		...referenceConfs,
-		resolveLibraryReferenceConfPath(),
-	].reduce((config, path) => config.withFallback(read(path)), read(envConfPath));
-	const resolved = validate(layered, AppConfigSchema);
-	const federations = resolved.federations as Record<string, Record<string, unknown>>;
-	return {
-		...resolved,
-		federations: {
-			...federations,
-			google: { ...federations.google, clientUrl: FEDERATION_LANDING },
-			oidc: { ...federations.oidc, clientUrl: FEDERATION_LANDING },
-		},
-		federationGrants: {
-			...resolved.federationGrants,
-			encryptionKeys: [{ id: "k-test", key: ENCRYPTION_KEY }],
-			connections: {
-				[CONNECTION]: {
-					federation: "oidc",
-					scopes: ["openid", "offline_access", "calendar.read"],
-					boundary: "production",
-					maxAccessTokenLifetime: 3600,
-					callbackURL: `${ISSUER}/session/federation-grants/callback/${CONNECTION}`,
-				},
-			},
-		},
-	} as unknown as AppConfig;
+	own: OwnLayers = readOwnLayers(ownFiles(env), { env }),
+): Switches {
+	return readSwitches(own);
 }
 
 // ---------------------------------------------------------------------------
@@ -327,30 +368,55 @@ let upstreams: Promise<{ fakes: Upstreams; reset: () => void }> | undefined;
  * 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),
 	}));
-	const { fakes, reset } = await upstreams;
-	reset();
-	return fakes;
+	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);
+
 /**
- * Snapshots each fake's settings — every property that is not a function —
- * and returns what puts them back: primitives reassigned, objects restored in
+ * 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.
  *
- * What a fake keeps in its closure is not restored either: 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, so a later boot's login is unaffected;
- * 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 a fake of its own with `createFakeIdp`.
+ * 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) => ({
@@ -399,7 +465,7 @@ async function createUpstreams(): Promise<Upstreams> {
 		oidc: await createFakeIdp({
 			issuer: OIDC_ISSUER,
 			discovery: true,
-			clientId: SINGLE_ENV.FEDERATIONS_OIDC_CLIENT_ID,
+			clientId: SINGLE_ENV.CORE_FEDERATIONS_OIDC_CLIENT_ID,
 			sub: OIDC_SUB,
 		}),
 		// Google's endpoints are fixed in the adapter, not discovered.
@@ -409,58 +475,12 @@ async function createUpstreams(): Promise<Upstreams> {
 			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.FEDERATIONS_GOOGLE_CLIENT_ID,
+			clientId: SINGLE_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_ID,
 			sub: GOOGLE_SUB,
 		}),
 	};
 }
 
-/**
- * What one of the template's config bridges provides for `config`. Read
- * through a record, not the typed slot: a program that loads this file without
- * a federation package's ComponentMap augmentation (`tools/composition` does)
- * has no key to name.
- */
-const bridged = <T,>(module: Module, slot: string, config: AppConfig): T => {
-	const provider = (module.provides as Record<string, unknown> | undefined)?.[slot];
-	if (typeof provider !== "function") throw new Error(`${module.name} provides no ${slot}`);
-	return (provider as (deps: { config: AppConfig }) => T)({ config });
-};
-
-/**
- * The two federation config slots, read by the template's own bridges
- * (`oidcFederationConfigModule`, `googleFederationConfigModule`), with each
- * adapter's `fetch` pointed at its fake upstream. Only for the federations the
- * config enables — which is when `buildModules` lists the bridges.
- */
-async function federationOverrides(
-	config: AppConfig,
-	upstreams: Upstreams,
-): Promise<Record<string, unknown>> {
-	const overrides: Record<string, unknown> = {};
-	const modules = buildModules(config).map((m) => m.name);
-	if (modules.includes(oidcFederationConfigModule.name)) {
-		const oidc = bridged<Record<string, object>>(
-			oidcFederationConfigModule,
-			"oidcFederationConfigs",
-			config,
-		);
-		overrides.oidcFederationConfigs = Object.fromEntries(
-			Object.entries(oidc).map(([name, entry]) => [
-				name,
-				{ ...entry, fetch: upstreams.oidc.fetch },
-			]),
-		);
-	}
-	if (modules.includes(googleFederationConfigModule.name)) {
-		overrides.googleFederationConfig = {
-			...bridged<object>(googleFederationConfigModule, "googleFederationConfig", config),
-			fetch: upstreams.google.fetch,
-		};
-	}
-	return overrides;
-}
-
 // ---------------------------------------------------------------------------
 // Logger spy
 // ---------------------------------------------------------------------------
@@ -567,18 +587,30 @@ export type ModuleOrder = typeof AS_LISTED | typeof REVERSED;
 
 export interface ComposeOptions {
 	readonly env?: Readonly<Record<string, string>>;
-	/** Other packages' `reference.conf` files, layered above core's (see `resolveConfig`). */
-	readonly referenceConfs?: readonly 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: AppConfig) => readonly Module[];
-	/** Components laid over the boot's, beside the federation config slots. */
-	readonly extraOverrides?: (config: AppConfig) => Record<string, unknown>;
+	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 the resolved config before anything reads it. */
+	/**
+	 * 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). */
@@ -593,15 +625,18 @@ export interface ComposeOptions {
 }
 
 /** The module list the template boots for `config`, as `app.mts` builds it. */
-export function composedModules(config: AppConfig, options: ComposeOptions = {}): Module[] {
+export function composedModules(config: Switches, options: ComposeOptions = {}): Module[] {
 	let modules = [
 		...buildModules(config, {
-			environment: "production",
+			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);
@@ -612,7 +647,10 @@ export function composedModules(config: AppConfig, options: ComposeOptions = {})
 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;
@@ -625,21 +663,40 @@ export interface Composition {
  * boot's `logger` component.
  */
 export async function compose(options: ComposeOptions = {}): Promise<Composition> {
-	const base = resolveConfig(options.env ?? SINGLE_ENV, options.referenceConfs);
-	const config = options.config ? options.config(base) : base;
+	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, pathResolver: (s) => s, logger },
-		overrideComponents: {
-			...(await federationOverrides(config, fakes)),
-			...options.extraOverrides?.(config),
-		} as never,
+		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", config.http.trustProxy);
+	app.set("trust proxy", httpSettings.trustProxy);
 	app.use(
 		helmet({
 			contentSecurityPolicy: { directives: { defaultSrc: ["'none'"], frameAncestors: ["'none'"] } },
@@ -647,7 +704,7 @@ export async function compose(options: ComposeOptions = {}): Promise<Composition
 	);
 	app.use(handle.router);
 	if (options.terminalErrorHandler !== false) app.use(terminalErrorHandler(logger));
-	return { app, handle, config, modules, logger, upstreams: fakes };
+	return { app, handle, config: parsed, resolved, modules, logger, upstreams: fakes };
 }
 
 // ---------------------------------------------------------------------------
@@ -765,12 +822,17 @@ export const DISCOVERY_PATHS = [
 /**
  * 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.
+ * 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>): void {
+export function expectValidMetadata(
+	doc: Record<string, unknown>,
+	{ authorizationCode = true }: { readonly authorizationCode?: boolean } = {},
+): void {
 	expect(doc.issuer).toBe(ISSUER);
 	for (const field of [
-		"authorization_endpoint",
 		"token_endpoint",
 		"jwks_uri",
 		"response_types_supported",
@@ -786,13 +848,20 @@ export function expectValidMetadata(doc: Record<string, unknown>): void {
 			expect(url.search + url.hash, field).toBe("");
 		}
 		if (field.endsWith("_supported") && Array.isArray(value)) {
-			expect(value.length, field).toBeGreaterThan(0);
+			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);
 		}
 	}
-	expect(doc.response_types_supported).toEqual(["code"]);
-	expect(doc.code_challenge_methods_supported).toEqual(["S256"]);
+	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");
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -937,7 +1006,7 @@ export const TOO_LARGE = { error: "invalid_request", error_description: "body_to
 // ---------------------------------------------------------------------------
 
 /**
- * The parts of the #685 outage rule, each checked on its own so a case pins
+ * 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);
@@ -981,6 +1050,11 @@ export interface OutageCase<C extends Composition = Composition> {
 	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. */
@@ -1011,6 +1085,14 @@ export function describeOutages<C extends Composition>(
 ): 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[] = [];
@@ -1090,13 +1172,20 @@ export function describeOutages<C extends Composition>(
 					expect(err).toMatchObject({ name: expect.any(String) });
 					expect(err).not.toBeInstanceOf(Error);
 				});
-				check("no-warn", "writes no warn line for it", () => {
-					const warns = lines
+				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));
-					expect(warns).toEqual([]);
+				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);
+					});
+				}
 			});
 		}
 	});