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

package/templates/standalone/src/configPath.mts

@@ -25,18 +25,20 @@
  * parse has, which matters because adapter selections have no disagreement
  * guard at boot; `two-phase-config.test.mts` pins this for the shipped
  * environments. A loaded module's own schema may still make something else of
- * a switch at boot.
+ * a switch at boot. Beside phase two it builds the configuration's defaults,
+ * which boot names the sections nothing loaded reads by
+ * (`configDefaultsFor`): the same references, with no file of the
+ * composition's and no environment.
  */
 
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { isDeepStrictEqual } from "node:util";
 import {
 	type AppConfig,
-	coreReference,
+	type CoreSection,
+	coerceBooleanFromEnv,
 	type Module,
 	moduleReferences,
-	readTransitionalConfig,
 } from "@o3co/auth-provider-core";
 import {
 	redisFederationGrantIntentStoreModule,
@@ -44,6 +46,13 @@ import {
 } from "@o3co/auth-provider-redis";
 import { type Config, empty, parseFile } from "@o3co/ts.hocon";
 import { ADAPTERS_SECTION, readAdapters } from "./adapters.mjs";
+import {
+	configRefused,
+	issuesAt,
+	keyRefused,
+	pathsRelocated,
+	sectionPathRefused,
+} from "./bootRefusal.mjs";
 import { MFA_SWITCH, mfaSectionForBoot, oauthForBoot, readMfaSwitch } from "./mfaSwitch.mjs";
 import { loggingModule, templateReference } from "./modules.mjs";
 import { refuseRenamedVariables, SHIPPED_FEDERATION_RENAMES } from "./rootRenames.mjs";
@@ -135,78 +144,76 @@ export function resolveLayers(own: OwnLayers, references: readonly URL[]): Recor
 	return layered.toObject() as Record<string, unknown>;
 }
 
-/**
- * What the template reads before it knows its modules, through core's
- * reader: the switches `buildModules` and its module factories choose by, and
- * the configuration's `core.sessionRequirements`, which
- * `expectedSessionRequirements` reads (the log level is `readLogging`'s). A
- * module a deployment adds that reads its configuration when it is built adds
- * those paths here, or passes them to `readSwitches` as `reads`.
- * `two-phase-config.test.mts` holds this list to what the template reads.
- *
- * Every path here and in `reads` must be one core's transitional base
- * declares (a section core's schema has, or mirrors for a package), or
- * `readSwitches` refuses it. A deployment module reading, when it is built, a
- * key of its own that core does not mirror gets it as written: raw, an
- * environment variable's string and all, without what only a package's
- * `reference.conf` sets. Parse it in the module, or read it after boot.
- */
-export const SWITCHES: readonly string[] = [
-	"core.sessionRequirements",
-	"core.federations",
-	"federation-grants.enabled",
-	"session-store.storage",
-	"oauth-session.enabled",
-	"oauth-authorization.grants",
-	"oauth.accessToken",
-];
-
 /** `core.sessionRequirements`, as the composition declares it to boot. */
-export type SessionRequirements = NonNullable<AppConfig["core"]>["sessionRequirements"];
-
-export interface SwitchesOptions {
-	/** Paths read beside `SWITCHES`: what a module a deployment adds reads when it is built. */
-	readonly reads?: readonly string[];
-}
+export type SessionRequirements = NonNullable<CoreSection["sessionRequirements"]>;
 
 /**
- * What phase one answers: the switches core's reader parsed; the composition
- * root's own `adapters` and `mfaMode`, parsed with the template's schema;
- * and the Store transport settings — the user repository's HTTP settings,
- * `repositories.user.http`, as the template's own layers hold them, unparsed
- * — which the Store-backed MFA factor store is built over.
+ * What phase one answers, from the composition's own layers over the
+ * template's `config/reference.conf` alone: the composition root's own
+ * `adapters` and `mfaMode`, parsed with the template's schema; the Store
+ * transport settings — the user repository's HTTP settings,
+ * `repositories.user.http`, unparsed — which the Store-backed MFA factor
+ * store is built over; and whether the federation-grants modules are
+ * installed (`federationGrantsInstalled`). Nothing else of the configuration
+ * is read before boot: a module reads its own section, `deps.section`, at
+ * boot.
  */
-export type Switches = AppConfig & {
+export type Switches = {
 	readonly adapters: Adapters;
 	readonly mfaMode: MfaSwitch;
 	readonly storeTransport: unknown;
+	readonly "federation-grants"?: { readonly enabled?: boolean };
 };
 
 /**
- * Phase one: the switches (`SWITCHES`, and `reads`) from the composition's
- * own layers over core's `reference.conf` alone, read with core's
- * `readTransitionalConfig`: each parsed with the schema core declares at its
- * path, everything else as written; and, from its own layers over the
- * template's `config/reference.conf`, the composition root's own `adapters`
+ * Phase one: from the composition's own layers over the template's
+ * `config/reference.conf`, the composition root's own `adapters`
  * (`readAdapters`), which refuses a selection at the path it moved from and a
  * variable renamed with one, its own MFA switch `mfaMode` (`readMfaSwitch`),
- * and the Store transport settings. A variable the template bound for a
+ * the Store transport settings, and whether federation grants are installed
+ * (`federationGrantsInstalled`). A variable the template bound for a
  * federation it ships, renamed after the entry's path under
  * `core.federations` (`SHIPPED_FEDERATION_RENAMES`), is refused here too.
- * Use it for those choices only. A switch whose
- * default only a package ships reads as unset here; set it in the template's
- * own files.
+ * Use it for those choices only. A default only a package's reference ships
+ * reads as unset here; the template's own files set what it reads.
  */
-export function readSwitches(own: OwnLayers, options: SwitchesOptions = {}): Switches {
+export function readSwitches(own: OwnLayers): Switches {
 	const template = resolveLayers(own, [templateReference()]);
 	const adapters = readAdapters(template, own.env);
 	const mfaMode = readMfaSwitch(template, own.env);
 	refuseRenamedVariables(own.env, SHIPPED_FEDERATION_RENAMES);
-	const switches = readTransitionalConfig(resolveLayers(own, [coreReference()]), [
-		...SWITCHES,
-		...(options.reads ?? []),
-	]);
-	return { ...switches, adapters, mfaMode, storeTransport: storeTransportOf(template) };
+	return {
+		adapters,
+		mfaMode,
+		storeTransport: storeTransportOf(template),
+		"federation-grants": { enabled: federationGrantsInstalled(template) },
+	};
+}
+
+/**
+ * Whether `resolved` installs the federation-grants modules: unless
+ * `federation-grants.enabled` reads as `false` with core's
+ * `coerceBooleanFromEnv`, or is not written at all. A value that does not
+ * parse installs them, so that boot refuses it at `federation-grants.enabled`
+ * rather than the feature reading as off; so does a section written as
+ * something other than a section, and any setting written at the section's
+ * old path, `federationGrants`, which boot refuses naming the new path.
+ */
+function federationGrantsInstalled(resolved: Readonly<Record<string, unknown>>): boolean {
+	if (setsAnything(resolved.federationGrants)) return true;
+	const section = resolved["federation-grants"];
+	if (section === undefined) return false;
+	if (!isPlainSection(section)) return true;
+	if (section.enabled === undefined) return false;
+	const enabled = coerceBooleanFromEnv.safeParse(section.enabled);
+	return !(enabled.success && enabled.data === false);
+}
+
+/** Whether `value` sets anything: a value, or a section with one somewhere under it. */
+function setsAnything(value: unknown): boolean {
+	if (value === undefined) return false;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return true;
+	return Object.values(value).some(setsAnything);
 }
 
 /** `repositories.user.http` in `resolved`, as written; `undefined` when absent. */
@@ -219,68 +226,85 @@ function storeTransportOf(resolved: Readonly<Record<string, unknown>>): unknown
 /**
  * The `logging` module's section, read before boot for the logger: the own
  * layers over the module's reference and core's, parsed with the module's
- * schema. A refused value is a `RangeError` naming its path under `logging`.
+ * schema. A refused value is a `config-validation-failed` `BootError` naming
+ * its path under `logging`.
  */
 export function readLogging(own: OwnLayers): LoggingSettings {
 	const resolved = resolveLayers(own, moduleReferences([loggingModule]));
 	const result = loggingSectionSchema.safeParse(resolved.logging);
 	if (!result.success) {
-		const issues = result.error.issues;
-		throw new RangeError(
+		const issues = issuesAt([loggingModule.name], result.error.issues);
+		throw configRefused(
 			`Config validation failed — ${issues.length} issue(s) found: ${issues
-				.map((issue) => `${["logging", ...issue.path.map(String)].join(".")}: ${issue.message}`)
+				.map((issue) => `${issue.path.map(String).join(".")}: ${issue.message}`)
 				.join("; ")}`,
-			{ cause: result.error },
+			issues,
+			[{ module: loggingModule.name, schemaPath: loggingModule.name }],
 		);
 	}
 	return result.data;
 }
 
 /**
- * What this composition expects of session admission, from phase one: the
- * configuration's `core.sessionRequirements` as written, with `mfa` appended
- * to `expected` when the template's MFA switch, `mfaMode`, is not `off` and
- * the list does not name it, and `secondFactorAuthority` written as `mfa`
- * beside it — the switch installs the MFA module, whose requirement registers
- * `mfa` as the second-factor authority, and boot refuses a declared name
- * nothing registers (`session-requirement-missing`) and a declared authority
- * the requirement of that name does not declare. With the switch on, a
- * written `secondFactorAuthority` other than `mfa` is a `RangeError` naming
- * the key, `mfaMode` and `MFA_MODE`, quoting nothing. With the switch `off`
- * the section is as written, and with nothing written nothing is declared:
- * boot's rule for an unwritten key applies. Computed here because HOCON has
- * no conditional.
+ * What this composition expects of session admission: what to write over
+ * the configuration's `core.sessionRequirements` — `written`, as resolved —
+ * when the template's MFA switch, `mfaMode`, is not `off`: the configuration's
+ * `expected` with `mfa` appended when the list does not name it, and
+ * `secondFactorAuthority` written as `mfa` beside it — the switch installs the
+ * MFA module, whose requirement registers `mfa` as the second-factor
+ * authority, and boot refuses a declared name nothing registers
+ * (`session-requirement-missing`) and a declared authority the requirement of
+ * that name does not declare. Every other key written there is kept, for
+ * boot to refuse. With nothing written, `mfa` alone. With the switch on, a
+ * written `secondFactorAuthority` other than `mfa` is a
+ * `config-validation-failed` `BootError` naming the key, `mfaMode` and
+ * `MFA_MODE`, quoting nothing.
+ *
+ * `undefined` hands the section on as written: with the switch `off`, and
+ * where `written` is not a section or its `expected` is not a list of names,
+ * which boot refuses at its path. Computed here because HOCON has no
+ * conditional.
  */
 export function expectedSessionRequirements(
-	switches: Pick<Switches, "core" | "mfaMode">,
-): SessionRequirements {
-	const written = switches.core?.sessionRequirements;
-	if (switches.mfaMode === "off") {
-		return written === undefined ? undefined : { ...written, expected: [...written.expected] };
-	}
-	const authority = written?.secondFactorAuthority;
+	written: unknown,
+	mfaMode: MfaSwitch,
+): SessionRequirements | undefined {
+	if (mfaMode === "off") return undefined;
+	if (written === undefined) return { expected: ["mfa"], secondFactorAuthority: "mfa" };
+	if (!isPlainSection(written)) return undefined;
+	const authority = written.secondFactorAuthority;
 	if (authority !== undefined && authority !== "mfa") {
-		throw new RangeError(
+		throw keyRefused(
 			`core.sessionRequirements.secondFactorAuthority is written and names a requirement other than the one ${MFA_SWITCH} (MFA_MODE) installs as the second-factor authority: remove it, or write mfa`,
+			"core",
+			["core", "sessionRequirements", "secondFactorAuthority"],
 		);
 	}
-	const declared = [...(written?.expected ?? [])];
+	const declared = written.expected;
+	if (!isListOfNames(declared)) return undefined;
 	return {
-		expected: declared.includes("mfa") ? declared : [...declared, "mfa"],
+		...written,
+		expected: declared.includes("mfa") ? [...declared] : [...declared, "mfa"],
 		secondFactorAuthority: "mfa",
 	};
 }
 
+/** Whether `value` is a list of strings. */
+function isListOfNames(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((name) => typeof name === "string");
+}
+
 /**
  * Whether a module in `modules` owns the top-level section `name`: its
- * section sits there or under it, or it moved from there or under it.
+ * section sits there, at the module's name, or it moved from there or under
+ * it.
  */
 function ownsSection(modules: readonly Module[], name: string): boolean {
 	const topOf = (path: string): string | undefined => path.split(".")[0];
 	return modules.some((module) => {
 		const section = module.section;
 		if (section === undefined) return false;
-		if ((section.at === undefined ? module.name : topOf(section.at)) === name) return true;
+		if (module.name === name) return true;
 		const from = section.relocatedFrom;
 		const old = from === undefined ? [] : Array.isArray(from) ? from : Object.keys(from);
 		return old.some((path) => topOf(path) === name);
@@ -298,7 +322,7 @@ function keyPrefixOf(
 }
 
 /**
- * Refuses, with a `RangeError`, a Redis intent store left on the default key
+ * Refuses, with a `BootError`, a Redis intent store left on the default key
  * prefix where the grant store's was moved, when `modules` load the Redis
  * intent store. The intent store's prefix is its own key, so a deployment
  * that moved only the grant store's would keep acquisition's records in the
@@ -313,8 +337,10 @@ function keyPrefixOf(
  *   written at all: the intent store read that key, and no loaded module
  *   relocates it.
  *
- * The defaults are what the package's `reference.conf` sets with no
- * environment. The message names the keys and variables, and quotes no value.
+ * The first is `config-validation-failed` at the intent store's key; the
+ * second `config-path-relocated`, from the old key to the intent store's. The
+ * defaults are what the package's `reference.conf` sets with no environment.
+ * The message names the keys and variables, and quotes no value.
  */
 function refuseIntentPrefixLeftAtDefault(
 	resolved: Readonly<Record<string, unknown>>,
@@ -325,14 +351,23 @@ function refuseIntentPrefixLeftAtDefault(
 	const loaded = (module: Module) => modules.some((m) => m.name === module.name);
 	const reference = intentStore.section?.reference;
 	if (!loaded(intentStore) || reference === undefined) return;
-	const intentKey =
-		"redis-federation-grant-intent-store.keyPrefix (REDIS_FEDERATION_GRANT_INTENT_STORE_KEY_PREFIX)";
+	const intentPath = `${intentStore.name}.keyPrefix`;
+	const intentVariable = "REDIS_FEDERATION_GRANT_INTENT_STORE_KEY_PREFIX";
+	const intentKey = `${intentPath} (${intentVariable})`;
 	const oldSection = resolved.redisFederationGrantStore;
 	if (!loaded(grantStore) && isPlainSection(oldSection) && Object.hasOwn(oldSection, "keyPrefix")) {
-		throw new RangeError(
+		throw pathsRelocated(
 			"redisFederationGrantStore.keyPrefix is set, and no installed module reads it: the Redis " +
 				`intent store's prefix is its own key, ${intentKey}. Set that instead, and delete ` +
 				"redisFederationGrantStore.keyPrefix",
+			[
+				{
+					module: intentStore.name,
+					from: "redisFederationGrantStore.keyPrefix",
+					to: intentPath,
+					environmentVariable: intentVariable,
+				},
+			],
 		);
 	}
 	const defaults = resolveLayers({ config: empty(), env: {} }, [reference]);
@@ -342,12 +377,14 @@ function refuseIntentPrefixLeftAtDefault(
 	if (intent === undefined || intent !== keyPrefixOf(defaults, intentStore)) return;
 	const grantKey =
 		"redis-federation-grant-store.keyPrefix (REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX)";
-	throw new RangeError(
+	throw keyRefused(
 		`${grantKey} is set off its default key prefix, and ${intentKey} is left at its ` +
 			"default. The Redis intent store's prefix is its own: acquisition's records would " +
 			"stay in the default namespace, shared with every deployment on the same Redis " +
 			`database that left it there. Set ${intentKey} as well — to the grant store's prefix ` +
 			"to keep the two together, or to one of its own",
+		intentStore.name,
+		[intentStore.name, "keyPrefix"],
 	);
 }
 
@@ -358,67 +395,44 @@ function refuseIntentPrefixLeftAtDefault(
 const ROOT_SECTIONS: readonly string[] = [ADAPTERS_SECTION, MFA_SWITCH];
 
 /**
- * The sections the template's own `config/reference.conf` sets that no module
- * in `modules` owns and that nothing has changed: as that file sets them with
- * no environment. Boot is not handed them, so a module of the template's the
- * composition does not load names nothing at boot; a section an operator's
- * layer or the environment changed is handed on, and boot names it once as a
- * section nothing owns.
- */
-function unownedTemplateDefaults(
-	resolved: Readonly<Record<string, unknown>>,
-	modules: readonly Module[],
-): readonly string[] {
-	const defaults = resolveLayers({ config: empty(), env: {} }, [templateReference()]);
-	return Object.keys(defaults).filter(
-		(name) =>
-			name !== RENAMED_VARIABLES &&
-			!ROOT_SECTIONS.includes(name) &&
-			!ownsSection(modules, name) &&
-			isDeepStrictEqual(resolved[name], defaults[name]),
-	);
-}
-
-/**
- * Refuses, with a `RangeError` naming it, a module whose section is at or
- * under one of the composition root's own sections, which phase one consumes
- * and boot is never handed: the module would read nothing its operator wrote.
+ * Refuses, with a `module-section-path-invalid` `BootError` naming it, a
+ * module whose section — at the module's name — is one of the composition
+ * root's own sections, which phase one consumes and boot is never handed:
+ * the module would read nothing its operator wrote.
  */
 function refuseModuleAtRootSections(modules: readonly Module[]): void {
 	for (const module of modules) {
-		const section = module.section;
-		if (section === undefined) continue;
-		const path = section.at ?? module.name;
-		const top = path.split(".")[0] ?? path;
-		if (ROOT_SECTIONS.includes(top)) {
-			throw new RangeError(
-				`Module "${module.name}" has its section at ${path}, under ${top}: the composition root's own section, which boot is not handed. Give the module a section of another name.`,
-			);
-		}
+		if (module.section === undefined || !ROOT_SECTIONS.includes(module.name)) continue;
+		const problem = "the composition root's own section, which boot is not handed, is read there";
+		throw sectionPathRefused(
+			`Module "${module.name}" has its section at ${module.name}: the composition root's own section, which boot is not handed. Give the module a section of another name.`,
+			module.name,
+			module.name,
+			problem,
+		);
 	}
 }
 
-/** The section a resolution captures renamed variables in: never left out. */
-const RENAMED_VARIABLES = "renamed-variables";
-
 /**
  * Phase two: what `createApp` parses once, with every loaded module's schema:
  * the composition's own layers, the same read phase one had, over the
  * `reference.conf` of every package `modules` come from, core's last,
- * resolved and unparsed, with `core.sessionRequirements` — what phase one
- * says the composition expects (`expectedSessionRequirements`) — written over
- * the resolved section when there is one to write, and the `mfa` section and
- * the `oauth` acr table as the template's MFA switch decides them
- * (`mfaSectionForBoot`, `oauthForBoot`). Left out:
- * `adapters` and `mfaMode`, the composition root's own keys, which phase one
- * consumed, and a section the template's own `reference.conf` sets for a
- * module the composition does not load, left as that file sets it
- * (`unownedTemplateDefaults`).
+ * resolved and unparsed, with `core.sessionRequirements` — what the
+ * composition expects under the MFA switch (`expectedSessionRequirements`) —
+ * written over the resolved section when there is one to write, and the
+ * `mfa` section and the `oauth` acr table as the template's MFA switch
+ * decides them (`mfaSectionForBoot`, `oauthForBoot`). Left out: `adapters`
+ * and `mfaMode`, the composition root's own keys, which phase one consumed.
+ * A section a loaded package's `reference.conf` sets for a module the
+ * composition does not load is handed on as resolved: boot tells it apart by
+ * the configuration's defaults (`configDefaultsFor`).
  *
- * Refuses, with a `RangeError`, a module whose section is under a section of
- * the composition root's (`refuseModuleAtRootSections`), what
- * `mfaSectionForBoot` refuses of the `mfa` section, and the Redis intent store left
- * on its default key prefix where the grant store's was moved
+ * Refuses, each with a `BootError` (`bootRefusal.mts`), a module whose
+ * section is a section of the composition root's
+ * (`refuseModuleAtRootSections`), what
+ * `expectedSessionRequirements` refuses of `core.sessionRequirements`, what
+ * `mfaSectionForBoot` refuses of the `mfa` section, and the Redis intent
+ * store left on its default key prefix where the grant store's was moved
  * (`refuseIntentPrefixLeftAtDefault`).
  *
  * Typed `AppConfig` because that is the `config` slot's type; read the parsed
@@ -427,13 +441,14 @@ const RENAMED_VARIABLES = "renamed-variables";
 export function resolveForBoot(
 	own: OwnLayers,
 	modules: readonly Module[],
-	switches: Pick<Switches, "core" | "mfaMode" | "adapters">,
+	switches: Pick<Switches, "mfaMode" | "adapters">,
 ): AppConfig {
 	refuseModuleAtRootSections(modules);
 	const all = resolveLayers(own, moduleReferences(modules));
 	refuseIntentPrefixLeftAtDefault(all, modules);
-	const unowned = new Set([...ROOT_SECTIONS, ...unownedTemplateDefaults(all, modules)]);
-	const layered = Object.fromEntries(Object.entries(all).filter(([name]) => !unowned.has(name)));
+	const layered = Object.fromEntries(
+		Object.entries(all).filter(([name]) => !ROOT_SECTIONS.includes(name)),
+	);
 	const { mfa: _decided, ...resolved } = layered;
 	const mfa = mfaSectionForBoot({
 		mode: switches.mfaMode,
@@ -444,17 +459,29 @@ export function resolveForBoot(
 			switches.adapters.userRepository === "http" || switches.adapters.mfaFactorStore === "store",
 		env: own.env,
 	});
-	const sessionRequirements = expectedSessionRequirements(switches);
+	// `core` written as something other than a section is handed on as
+	// written, for boot to refuse.
+	const core = isPlainSection(resolved.core) ? resolved.core : undefined;
+	const sessionRequirements =
+		resolved.core === undefined || core !== undefined
+			? expectedSessionRequirements(core?.sessionRequirements, switches.mfaMode)
+			: undefined;
 	return {
 		...resolved,
 		...(mfa === undefined ? {} : { mfa }),
 		...(resolved.oauth === undefined
 			? {}
 			: { oauth: oauthForBoot(switches.mfaMode, resolved.oauth) }),
-		...(sessionRequirements === undefined
-			? {}
-			: {
-					core: { ...(resolved.core as Record<string, unknown> | undefined), sessionRequirements },
-				}),
+		...(sessionRequirements === undefined ? {} : { core: { ...core, sessionRequirements } }),
 	} as unknown as AppConfig;
 }
+
+/**
+ * The configuration's defaults, which boot names the sections nothing loaded
+ * reads by (`bootstrapComponents.configDefaults`): the `reference.conf` of
+ * every package `modules` come from, layered as `resolveForBoot` layers them
+ * (core's last), with no file of the composition's and no environment.
+ */
+export function configDefaultsFor(modules: readonly Module[]): Record<string, unknown> {
+	return resolveLayers({ config: empty(), env: {} }, moduleReferences(modules));
+}

package/templates/standalone/src/mfaSwitch.mts

@@ -22,8 +22,9 @@
  * it; on installs the MFA package's modules over the two MFA stores
  * `adapters` selects.
  *
- * Refuses, each with a `RangeError` before boot that names the keys and
- * variables and quotes no value of a mode, a timeout or a key:
+ * Refuses, each before boot with a `config-validation-failed` `BootError`
+ * (`bootRefusal.mts`) that names the keys and variables and quotes no value
+ * of a mode, a timeout or a key:
  * - a switch outside its three values, or a file's `mfaMode` that `MFA_MODE`
  *   contradicts (`readMfaSwitch`);
  * - an MFA store kept in memory with MFA on, unless every environment name
@@ -50,6 +51,8 @@ import {
 	redisMfaTransactionStoreModule,
 } from "@o3co/auth-provider-redis";
 import { loginCompletionModule } from "@o3co/auth-provider-session";
+import { ADAPTERS_SECTION } from "./adapters.mjs";
+import { configRefused, customIssue, issuesAt, keyRefused } from "./bootRefusal.mjs";
 import { type Adapters, isPlainSection, type MfaSwitch, mfaSwitchSchema } from "./sections.mjs";
 
 /** The composition root's MFA switch, a key of its own. No module may be named after it. */
@@ -66,7 +69,7 @@ const MFA_ACR = "urn:o3co:acr:mfa";
  * `config/reference.conf` — parsed with the template's schema, under `env`,
  * the environment the layers were substituted with. A value the schema
  * refuses, or `MFA_MODE` set to other than what a file writes over it, is a
- * `RangeError` naming `mfaMode` and `MFA_MODE`.
+ * `config-validation-failed` `BootError` naming `mfaMode` and `MFA_MODE`.
  */
 export function readMfaSwitch(
 	resolved: Readonly<Record<string, unknown>>,
@@ -74,17 +77,20 @@ export function readMfaSwitch(
 ): MfaSwitch {
 	const result = mfaSwitchSchema.safeParse(resolved[MFA_SWITCH]);
 	if (!result.success) {
-		throw new RangeError(
+		throw configRefused(
 			`Config validation failed — ${MFA_SWITCH} (MFA_MODE): ${result.error.issues
 				.map((issue) => issue.message)
 				.join("; ")}`,
-			{ cause: result.error },
+			issuesAt([MFA_SWITCH], result.error.issues),
+			[{ module: MFA_SWITCH, schemaPath: MFA_SWITCH }],
 		);
 	}
 	const variable = env.MFA_MODE;
 	if (variable !== undefined && variable !== result.data) {
-		throw new RangeError(
+		throw keyRefused(
 			`MFA_MODE is set and differs from ${MFA_SWITCH}, which a configuration file writes over it: the file, not the variable, would decide whether MFA is installed. Remove ${MFA_SWITCH} from the file, or set MFA_MODE to what it says`,
+			MFA_SWITCH,
+			[MFA_SWITCH],
 		);
 	}
 	return result.data;
@@ -134,18 +140,27 @@ export function mfaModulesFor(options: {
 }): Module[] {
 	if (options.mode === "off") return [];
 	const { adapters, environment } = options;
-	const inMemory = [
-		...(adapters.mfaFactorStore === "memory"
-			? ["adapters.mfaFactorStore (ADAPTERS_MFA_FACTOR_STORE)"]
-			: []),
-		...(adapters.mfaTransactionStore === "memory"
-			? ["adapters.mfaTransactionStore (ADAPTERS_MFA_TRANSACTION_STORE)"]
-			: []),
-	];
+	const inMemory = (
+		[
+			["mfaFactorStore", "ADAPTERS_MFA_FACTOR_STORE"],
+			["mfaTransactionStore", "ADAPTERS_MFA_TRANSACTION_STORE"],
+		] as const
+	).filter(([key]) => adapters[key] === "memory");
 	const reasons = inMemory.length === 0 ? [] : memoryRefusals(environment);
 	if (reasons.length > 0) {
-		throw new RangeError(
-			`MFA is on (${MFA_SWITCH}, MFA_MODE, which installs it unless set to off) and ${inMemory.join(" and ")} ${inMemory.length === 1 ? "is" : "are"} "memory", refused because ${reasons.join(" and ")}: a store in memory loses every factor, lock and recorded email proof at a restart, after which whoever holds a password can bind a factor of their own. Select "redis" (or, for the factors, "store"); memory is for development and test alone. Outside development MFA also needs MFA_ENCRYPTION_KEY, the SMTP relay (STANDARD_SMTP_MAIL_SENDER_HOST and STANDARD_SMTP_MAIL_SENDER_FROM) or your own mail sender, and an MFA page served at MFA_PAGE_URL. A deployment that wants no MFA sets MFA_MODE=off`,
+		const refused = `"memory", refused because ${reasons.join(" and ")}`;
+		const settings = inMemory
+			.map(([key, variable]) => `${ADAPTERS_SECTION}.${key} (${variable})`)
+			.join(" and ");
+		throw configRefused(
+			`MFA is on (${MFA_SWITCH}, MFA_MODE, which installs it unless set to off) and ${settings} ${inMemory.length === 1 ? "is" : "are"} ${refused}: a store in memory loses every factor, lock and recorded email proof at a restart, after which whoever holds a password can bind a factor of their own. Select "redis" (or, for the factors, "store"); memory is for development and test alone. Outside development MFA also needs MFA_ENCRYPTION_KEY, the SMTP relay (STANDARD_SMTP_MAIL_SENDER_HOST and STANDARD_SMTP_MAIL_SENDER_FROM) or your own mail sender, and an MFA page served at MFA_PAGE_URL. A deployment that wants no MFA sets MFA_MODE=off`,
+			inMemory.map(([key, variable]) =>
+				customIssue(
+					[ADAPTERS_SECTION, key],
+					`${variable} is ${refused}, with MFA on (${MFA_SWITCH}, MFA_MODE)`,
+				),
+			),
+			[{ module: ADAPTERS_SECTION, schemaPath: ADAPTERS_SECTION }],
 		);
 	}
 	return [
@@ -202,14 +217,18 @@ export function mfaSectionForBoot(options: {
 }): unknown {
 	const { mode, written, resolved } = options;
 	if (written !== undefined && !isPlainSection(written)) {
-		throw new RangeError(
+		throw keyRefused(
 			`mfa is written as a value in the configuration; it is the MFA package's section, and ${MFA_SWITCH} (MFA_MODE) decides whether the template installs MFA. Remove mfa, and set MFA_MODE or ${MFA_SWITCH}`,
+			MFA_SECTION,
+			[MFA_SECTION],
 		);
 	}
 	const writtenMode = written === undefined ? undefined : written.mode;
 	if (writtenMode !== undefined && writtenMode !== mode) {
-		throw new RangeError(
+		throw keyRefused(
 			`mfa.mode is written in the configuration and differs from ${MFA_SWITCH} (MFA_MODE), which decides whether the template installs MFA and writes mfa.mode from it. Set MFA_MODE or ${MFA_SWITCH}, and remove mfa.mode`,
+			MFA_SECTION,
+			[MFA_SECTION, "mode"],
 		);
 	}
 	if (!options.owned) return undefined;
@@ -223,8 +242,10 @@ export function mfaSectionForBoot(options: {
 		variableKey !== MFA_DEVELOPMENT_SAMPLE_KEY &&
 		ring.some((entry) => valueAt(entry, ["key"]) === MFA_DEVELOPMENT_SAMPLE_KEY)
 	) {
-		throw new RangeError(
+		throw keyRefused(
 			"MFA_ENCRYPTION_KEY is set, and mfa.encryptionKeys holds the development sample key in its place: a ring a configuration file writes (config/development.conf's) wins over the variable, so the key you set would seal nothing. Write your key in place of the sample key in that ring, or unset MFA_ENCRYPTION_KEY",
+			MFA_SECTION,
+			[MFA_SECTION, "encryptionKeys"],
 		);
 	}
 	const storeTimeout = wholeNumber(section.storeTimeoutMs);
@@ -235,8 +256,10 @@ export function mfaSectionForBoot(options: {
 		userTimeout !== undefined &&
 		storeTimeout < userTimeout
 	) {
-		throw new RangeError(
+		throw keyRefused(
 			"mfa.storeTimeoutMs (MFA_STORE_TIMEOUT_MS) is below repositories.user.http.timeout (REPOSITORIES_USER_HTTP_TIMEOUT): one MFA Store call's time must cover the Store's own per-call timeout, or a factor-set write's lease can lapse while a Store call is still running. Raise MFA_STORE_TIMEOUT_MS to at least the user directory's timeout",
+			MFA_SECTION,
+			[MFA_SECTION, "storeTimeoutMs"],
 		);
 	}
 	return { ...section, mode };