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

package/templates/standalone/src/__tests__/documented-env-overrides.test.mts

@@ -20,12 +20,18 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	type AppConfig,
+	BootError,
 	createApp,
+	defineModule,
 	type Module,
 	moduleReferences,
 	resolveAccessTokenLifetime,
 } from "@o3co/auth-provider-core";
-import { oauthModule } from "@o3co/auth-provider-oauth";
+import { createFakeIdp, type FakeIdp } from "@o3co/auth-provider-core/testing";
+import { googleFederationTypeModule } from "@o3co/auth-provider-federation-google";
+import { federationGrantsModule } from "@o3co/auth-provider-federation-grants";
+import { oidcFederationTypeModule } from "@o3co/auth-provider-federation-oidc";
+import { type OAuthSection, oauthEndpointsModule } from "@o3co/auth-provider-oauth";
 import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
 import { describe, expect, it } from "vitest";
 import { buildModules } from "../buildModules.mjs";
@@ -35,6 +41,7 @@ import {
 	readSwitches,
 	resolveConfigPaths,
 	resolveForBoot,
+	resolveLayers,
 	type Switches,
 } from "../configPath.mjs";
 import { httpModule, keyStoreModule, templateReference } from "../modules.mjs";
@@ -43,8 +50,8 @@ import { httpModule, keyStoreModule, templateReference } from "../modules.mjs";
  * Boots the shipped config with EVERY documented override supplied the way an
  * operator supplies one: as a string.
  *
- * HOCON substitutes `${?VAR}` as a string, always. `app.mts` reads its switches
- * with core's transitional reader and hands `createApp` what it resolved,
+ * HOCON substitutes `${?VAR}` as a string, always. `app.mts` reads its own
+ * switches with the template's schema and hands `createApp` what it resolved,
  * which boot parses once with plain Zod, so every schema leaf must read the
  * string itself. This suite reads through that path: `readSwitches` for what
  * is read before boot, `resolveForBoot` and `createApp` for the configuration
@@ -94,11 +101,7 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	// --- oauth tokens / policy ----------------------------------------
 	OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN: "900",
 	OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN: "7200",
-	// Deprecated alias of the default. Exported alongside the new variable on
-	// purpose, with a different value: the new variable must win.
-	OAUTH_ACCESS_TOKEN_EXPIRES_IN: "3600",
 	OAUTH_REFRESH_TOKEN_EXPIRES_IN: "86400",
-	OAUTH_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY: "reject",
 	OAUTH_OIDC_MODE: "dual",
 	OAUTH_REVOCATION_ACCESS_TOKEN: "denylist",
 	OAUTH_REVOCATION_SUBJECT: "unsupported",
@@ -131,6 +134,7 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	OAUTH_SESSION_ENABLED: "false",
 	OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED: "true",
 	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED: "true",
+	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY: "reject",
 	OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED: "true",
 	OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED: "false",
 
@@ -156,6 +160,7 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	// Which adapter fills each slot: the composition root's own section,
 	// read before the modules are chosen.
 	ADAPTERS_RATE_LIMITER: "redis",
+	ADAPTERS_ATTEMPT_COUNTER: "redis",
 	ADAPTERS_USER_SESSION_STORES: "redis",
 	ADAPTERS_ACCESS_TOKEN_DENYLIST: "redis",
 	// The replay seen-set behind private_key_jwt client authentication.
@@ -304,7 +309,9 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
  */
 const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
 	OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS:
-		"#330 tombstone — any value must fail boot with migration instructions",
+		"the variable of a removed key, and only captured — any value fails boot",
+	OAUTH_ACCESS_TOKEN_EXPIRES_IN:
+		"renamed OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN, and only captured — set alone, or to another value, it fails boot",
 	DEPLOYMENT_MODE:
 		"renamed CORE_DEPLOYMENT_MODE, and only captured — set alone, or to another value, it fails boot",
 	MEMORY_RATE_LIMITER_MAX_BUCKETS:
@@ -327,6 +334,8 @@ const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
 		"renamed OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED, and only captured — set alone, or to another value, it fails boot",
 	OAUTH_GRANTS_REFRESH_TOKEN_ENABLED:
 		"renamed OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED, and only captured — set alone, or to another value, it fails boot",
+	OAUTH_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY:
+		"renamed OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY, and only captured — set alone, or to another value, it fails boot",
 	OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED:
 		"renamed OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED, and only captured — set alone, or to another value, it fails boot",
 	OAUTH_GRANTS_JWT_BEARER_ENABLED:
@@ -437,6 +446,39 @@ const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
 		"renamed MFA_TOTP_FACTOR_ISSUER, and only captured — set alone, or to another value, it fails boot where MFA is installed",
 };
 
+/**
+ * The federation variables `config/application.conf` documents on lines it
+ * ships commented out — a key an operator binds by uncommenting it — as the
+ * string an operator would supply. They are not live substitutions, so they
+ * are not in `DOCUMENTED_ENV`; the federation cases below bind them as their
+ * comments write them (`commentedFederationBindings`).
+ */
+const COMMENTED_FEDERATION_ENV: Readonly<Record<string, string>> = {
+	CORE_FEDERATIONS_GOOGLE_SESSION_DOMAIN: ".example.com",
+	CORE_FEDERATIONS_GOOGLE_AUTH_CALLBACK_URL: "https://app.example.com/auth/callback",
+	CORE_FEDERATIONS_GOOGLE_CLIENT_URL: "https://app.example.com/",
+	CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS: "false",
+};
+
+/**
+ * Each `# <key> = ${?CORE_FEDERATIONS_<NAME>_…}` line of the shipped
+ * `config/application.conf`, uncommented as an operator's layer above it:
+ * `core.federations.<name>.<key> = ${?…}`.
+ */
+function commentedFederationBindings(): string {
+	const { applicationConfPath } = resolveConfigPaths(configDir, "production");
+	return readFileSync(applicationConfPath, "utf8")
+		.split("\n")
+		.flatMap((line) => {
+			const match =
+				/^\s*#\s*([A-Za-z]+) = \$\{\?(CORE_FEDERATIONS_([A-Z0-9]+)_[A-Z0-9_]+)\}\s*$/.exec(line);
+			if (match === null) return [];
+			const [, key, variable, name] = match as unknown as [string, string, string, string];
+			return [`core.federations.${name.toLowerCase()}.${key} = \${?${variable}}`];
+		})
+		.join("\n");
+}
+
 /**
  * The provider environment `o3co/auth`'s `tests/docker-compose.yml` sets,
  * transcribed: each renamed variable under its old and its new name, the two
@@ -507,34 +549,106 @@ function readShippedSwitches(env: Record<string, string>, configEnv = "productio
 const FEDERATION_STORES = Object.fromEntries(
 	[
 		"userSessionStore",
-		"sessionRPRegistry",
-		"sessionFamilyIndex",
-		"sessionFederationIndex",
+		"sessionLifecycle",
 		"federationTokenStore",
 		"refreshTokenFamilyRevocation",
 	].map((key) => [key, {}]),
 );
 
+/** What core handed a federation type for one entry: its callback, and its own keys as the type's schema parsed them. */
+interface Dispatched {
+	readonly callbackURL: string;
+	readonly entry: Readonly<Record<string, unknown>>;
+}
+
+/** A federation type's declaration, as far as this suite reads it. */
+interface TypeDeclaration {
+	readonly factory: (deps: unknown, instance: { name: string } & Dispatched) => unknown;
+}
+
 /**
- * The shipped layers under `env`, as `app.mts` hands them to boot, and the
- * configuration boot parsed: phase one for what the composition expects of
- * session admission, phase two resolved over the reference of every package
- * the template's modules come from (the template's own and core's) and
- * parsed once by `createApp` — no bridge on the way.
- * No module is loaded unless `modules` names one: the parse is what this
+ * `module`, a federation type module, with each type's factory recording what
+ * core handed it into `dispatched`, by the entry's name, before building the
+ * provider as the module does. The schema, the parse and the provider are the
+ * module's own.
+ */
+function recordingDispatch(module: Module, dispatched: Map<string, Dispatched>): Module {
+	const contributes = module.contributes as {
+		readonly federationTypes: Readonly<Record<string, TypeDeclaration>>;
+	};
+	const federationTypes = Object.fromEntries(
+		Object.entries(contributes.federationTypes).map(([type, declaration]) => [
+			type,
+			{
+				...declaration,
+				factory: (deps: unknown, instance: { name: string } & Dispatched) => {
+					dispatched.set(instance.name, {
+						callbackURL: instance.callbackURL,
+						entry: instance.entry,
+					});
+					return declaration.factory(deps, instance);
+				},
+			},
+		]),
+	);
+	return { ...module, contributes: { ...contributes, federationTypes } } as Module;
+}
+
+/**
+ * The upstream the documented OIDC federation's issuer names. Its type
+ * discovers the issuer at boot, so the module is handed this fake's `fetch`
+ * rather than the network. Made once per file.
+ */
+let oidcUpstream: Promise<FakeIdp> | undefined;
+const documentedOidcUpstream = (): Promise<FakeIdp> => {
+	oidcUpstream ??= createFakeIdp({
+		issuer: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_ISSUER as string,
+		discovery: true,
+		clientId: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_CLIENT_ID as string,
+	});
+	return oidcUpstream;
+};
+
+/**
+ * The shipped layers under `env`, as `app.mts` hands them to boot, booted
+ * with the federation types the template bundles: phase one for what the
+ * composition expects of session admission, phase two resolved over the
+ * reference of every package the template's modules come from (the
+ * template's own and core's) and parsed once by `createApp` — no bridge on
+ * the way. Core dispatches each enabled federation to its type, which parses
+ * the entry with its own schema; `dispatched` is what each type was handed.
+ * No other module is loaded unless `modules` names one: the parse is what this
  * suite asks about, and each key it reads is one core's schema declares, or
  * the section of a module it loads.
  */
-async function bootParsed(
+/**
+ * The oauth module's section, read without its factories: the template always
+ * loads the module, and core refuses keys of `oauth {}` where no loaded
+ * module's section is `oauth`. What refuses `oauth {}` here is the module's
+ * own section — its schema, its removed keys and variables.
+ */
+const oauthSectionReader = defineModule({
+	name: oauthEndpointsModule.name,
+	...(oauthEndpointsModule.section === undefined ? {} : { section: oauthEndpointsModule.section }),
+});
+
+async function bootDispatched(
 	env: Record<string, string>,
 	configEnv = "production",
 	operatorLayer?: string,
 	modules: readonly Module[] = [],
-): Promise<AppConfig> {
+): Promise<{ readonly parsed: AppConfig; readonly dispatched: ReadonlyMap<string, Dispatched> }> {
 	const own = readOwnLayers(ownFiles(configEnv, operatorLayer), { env });
 	const switches = readSwitches(own);
+	const dispatched = new Map<string, Dispatched>();
+	const upstream = await documentedOidcUpstream();
 	const handle = await createApp({
-		modules: [...modules],
+		modules: [
+			recordingDispatch(googleFederationTypeModule(), dispatched),
+			recordingDispatch(oidcFederationTypeModule({ fetch: upstream.fetch }), dispatched),
+			oauthSectionReader,
+			...modules,
+		],
 		bootstrapComponents: {
 			config: resolveForBoot(own, buildModules(switches, { environment: configEnv }), switches),
 			pathResolver: (s: string) => s,
@@ -544,7 +658,17 @@ async function bootParsed(
 	const parsed = handle.components.config;
 	await handle.dispose();
 	if (parsed === undefined) throw new Error("createApp booted without the parsed configuration");
-	return parsed;
+	return { parsed, dispatched };
+}
+
+/** The configuration boot parsed, as {@link bootDispatched} boots it. */
+async function bootParsed(
+	env: Record<string, string>,
+	configEnv = "production",
+	operatorLayer?: string,
+	modules: readonly Module[] = [],
+): Promise<AppConfig> {
+	return (await bootDispatched(env, configEnv, operatorLayer, modules)).parsed;
 }
 
 /** `session-store {}` as the session store's module parses it. */
@@ -560,6 +684,13 @@ function sessionStoreSection(config: AppConfig): {
 	>;
 }
 
+/** `federation-grants {}` as the federation-grants module parses it. */
+function federationGrantsSection(config: AppConfig): { readonly enabled?: boolean } {
+	const schema = federationGrantsModule.section?.schema;
+	if (schema === undefined) throw new Error("the federation-grants module declares no section");
+	return schema.parse(config["federation-grants"]) as ReturnType<typeof federationGrantsSection>;
+}
+
 /** `session {}` as the session module parses it. */
 function sessionSection(config: AppConfig): { readonly csrf?: { readonly ttlSeconds: number } } {
 	const schema = sessionModule.section?.schema;
@@ -578,13 +709,10 @@ function httpSectionOf(config: AppConfig): {
 }
 
 /** `oauth {}` as the oauth module's own schema parses it. */
-function oauthSection(config: AppConfig): {
-	readonly consentPage?: { readonly url: string };
-	readonly clientIdMetadataDocuments?: Readonly<Record<string, unknown>>;
-} {
-	const schema = oauthModule({ config }).section?.schema;
+function oauthSection(config: AppConfig): OAuthSection {
+	const schema = oauthEndpointsModule.section?.schema;
 	if (schema === undefined) throw new Error("the oauth module declares no section");
-	return schema.parse(config.oauth) as ReturnType<typeof oauthSection>;
+	return schema.parse(config.oauth) as OAuthSection;
 }
 
 /** Every `${?VAR}` in a HOCON layer, ignoring commented-out lines. */
@@ -646,14 +774,14 @@ describe("the shipped config boots with every documented override supplied as a
 		// Each of these arrives from HOCON as a string. A leftover string is
 		// not a cosmetic defect: `=== true` is how the runtime reads them.
 		expect(sessionStoreSection(config).secure).toBe(false);
-		expect(config.oauth.jwt.legacyTypAccept).toBe(true);
-		expect(config.oauth.requireEmailVerified).toBe(true);
-		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
+		expect(oauthSection(config).jwt.legacyTypAccept).toBe(true);
+		expect(oauthSection(config).requireEmailVerified).toBe(true);
+		expect(oauthSection(config).resourceIndicator?.enabled).toBe(true);
 		expect(config.core?.federations?.google?.enabled).toBe(true);
 		expect(config.core?.federations?.oidc?.enabled).toBe(true);
 		// A leftover string here would be read as "on" by a truthiness check
 		// and as "off" by `=== true`, for a feature whose whole default is off.
-		expect(config["federation-grants"]?.enabled).toBe(true);
+		expect(federationGrantsSection(config).enabled).toBe(true);
 	});
 
 	it("turns every non-boolean override into its declared type", async () => {
@@ -665,17 +793,18 @@ describe("the shipped config boots with every documented override supplied as a
 		expect(http.readinessTimeoutMs).toBe(1500);
 		expect(http.trustProxy).toEqual(["10.0.0.0/8", "loopback"]);
 		expect(config.core?.federations?.google?.accessType).toBe("online");
-		// The new default wins over the deprecated variable, and the parsed
-		// config mirrors it onto the old key for readers that predate the split.
-		expect(resolveAccessTokenLifetime(config)).toEqual({
+		expect(resolveAccessTokenLifetime({ oauth: oauthSection(config) })).toEqual({
+			defaultExpiresIn: 900,
+			maxExpiresIn: 7200,
+		});
+		expect(oauthSection(config).accessToken).toEqual({
 			defaultExpiresIn: 900,
 			maxExpiresIn: 7200,
 		});
-		expect(config.oauth.accessToken.expiresIn).toBe(900);
-		expect(config.oauth.refreshToken.expiresIn).toBe(86400);
+		expect(oauthSection(config).refreshToken.expiresIn).toBe(86400);
 		expect(sessionStoreSection(config).maxAge).toBe(3600000);
 		expect(sessionSection(config).csrf?.ttlSeconds).toBe(7200);
-		expect(config.oauth.nonce?.maxLength).toBe(256);
+		expect(oauthSection(config).nonce?.maxLength).toBe(256);
 		expect(readShippedSwitches(DOCUMENTED_ENV).adapters.consentStore).toBe("redis");
 		// A Redis store's section, which its module (not loaded here) parses.
 		const sections = config as unknown as Record<string, { keyPrefix?: unknown } | undefined>;
@@ -711,6 +840,133 @@ describe("the shipped config boots with every documented override supplied as a
 		expect(http.cors.allowedOrigins).toEqual(["https://app.example.com", "http://localhost:5173"]);
 	});
 
+	describe("the federations' variables, read by each federation's type", () => {
+		it("hands each enabled federation's type the entry its documented variables set", async () => {
+			const { dispatched } = await bootDispatched(DOCUMENTED_ENV);
+			expect(Object.fromEntries(dispatched)).toEqual({
+				google: {
+					callbackURL: DOCUMENTED_ENV.CORE_FEDERATIONS_GOOGLE_CALLBACK_URL,
+					entry: {
+						clientId: DOCUMENTED_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_ID,
+						clientSecret: DOCUMENTED_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET,
+						redirectAllowlist: [],
+						accessType: "online",
+					},
+				},
+				oidc: {
+					callbackURL: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_CALLBACK_URL,
+					entry: {
+						issuer: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_ISSUER,
+						clientId: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_CLIENT_ID,
+						clientSecret: DOCUMENTED_ENV.CORE_FEDERATIONS_OIDC_CLIENT_SECRET,
+						scopes: ["openid", "profile", "email"],
+						redirectAllowlist: [],
+					},
+				},
+			});
+		});
+
+		it("reads the Google keys the configuration documents commented out, bound as their comments write them", async () => {
+			const { dispatched } = await bootDispatched(
+				{ ...DOCUMENTED_ENV, ...COMMENTED_FEDERATION_ENV },
+				"production",
+				commentedFederationBindings(),
+			);
+			expect(dispatched.get("google")?.entry).toEqual({
+				clientId: DOCUMENTED_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_ID,
+				clientSecret: DOCUMENTED_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET,
+				redirectAllowlist: [],
+				accessType: "online",
+				sessionDomain: COMMENTED_FEDERATION_ENV.CORE_FEDERATIONS_GOOGLE_SESSION_DOMAIN,
+				authCallbackUrl: COMMENTED_FEDERATION_ENV.CORE_FEDERATIONS_GOOGLE_AUTH_CALLBACK_URL,
+				clientUrl: COMMENTED_FEDERATION_ENV.CORE_FEDERATIONS_GOOGLE_CLIENT_URL,
+				requireAuthorizationResponseIss: false,
+			});
+			// `toEqual` passes a key present as `undefined`: no variable binds
+			// `endSessionEndpoint`, so the entry must not carry the key at all.
+			expect(dispatched.get("google")?.entry).not.toHaveProperty("endSessionEndpoint");
+		});
+
+		it("hands the Google type no key the documented variables leave unset, not even as undefined", async () => {
+			const { dispatched } = await bootDispatched(DOCUMENTED_ENV);
+			const entry = dispatched.get("google")?.entry;
+			expect(entry).toBeDefined();
+			for (const key of [
+				"sessionDomain",
+				"authCallbackUrl",
+				"clientUrl",
+				"requireAuthorizationResponseIss",
+				"endSessionEndpoint",
+			]) {
+				expect(entry, key).not.toHaveProperty(key);
+			}
+		});
+
+		it("binds every variable the configuration documents commented out", () => {
+			expect(
+				commentedFederationBindings()
+					.match(/\$\{\?[A-Z0-9_]+\}/g)
+					?.sort(),
+			).toEqual(
+				Object.keys(COMMENTED_FEDERATION_ENV)
+					.map((name) => `\${?${name}}`)
+					.sort(),
+			);
+		});
+
+		/** The entry the Google type was handed under `variables`, the commented keys bound. */
+		const googleEntryUnder = async (variables: Record<string, string>) =>
+			(
+				await bootDispatched(
+					{ ...DOCUMENTED_ENV, ...variables },
+					"production",
+					commentedFederationBindings(),
+				)
+			).dispatched.get("google")?.entry;
+
+		for (const [supplied, expected] of [
+			["true", true],
+			["TRUE", true],
+			["1", true],
+			["false", false],
+			["False", false],
+			[" false ", false],
+			["0", false],
+		] as const) {
+			it(`CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS=${JSON.stringify(supplied)} reads as ${expected}`, async () => {
+				const entry = await googleEntryUnder({
+					CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS: supplied,
+				});
+				expect(entry?.requireAuthorizationResponseIss).toBe(expected);
+			});
+		}
+
+		it("refuses CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS exported empty or misspelt, naming the key, rather than turning the check off", async () => {
+			for (const supplied of ["", "no", "off", "ture"]) {
+				await expect(
+					googleEntryUnder({
+						CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS: supplied,
+					}),
+					supplied,
+				).rejects.toThrow(/core\.federations\.google\.requireAuthorizationResponseIss/);
+			}
+		});
+
+		it("reads CORE_FEDERATIONS_GOOGLE_ACCESS_TYPE as offline or online, exactly", async () => {
+			for (const supplied of ["offline", "online"]) {
+				expect(
+					(await googleEntryUnder({ CORE_FEDERATIONS_GOOGLE_ACCESS_TYPE: supplied }))?.accessType,
+				).toBe(supplied);
+			}
+			for (const supplied of ["", "Online", "offine", "true"]) {
+				await expect(
+					googleEntryUnder({ CORE_FEDERATIONS_GOOGLE_ACCESS_TYPE: supplied }),
+					supplied,
+				).rejects.toThrow(/core\.federations\.google\.accessType/);
+			}
+		});
+	});
+
 	describe("HTTP_CORS_ALLOWED_ORIGINS", () => {
 		it("reads an exported-but-empty variable as no origins, not as an error", async () => {
 			// The .env / compose / ConfigMap shape. "CORS off" is what both the
@@ -802,8 +1058,8 @@ describe("the shipped config boots with every documented override supplied as a
 	it("parses the environment the umbrella E2E boots, with SESSION_STORE_SECURE=false as a string", async () => {
 		const config = await bootParsed(UMBRELLA_E2E_ENV);
 		expect(sessionStoreSection(config).secure).toBe(false);
-		expect(config.oauth.requireEmailVerified).toBe(true);
-		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
+		expect(oauthSection(config).requireEmailVerified).toBe(true);
+		expect(oauthSection(config).resourceIndicator?.enabled).toBe(true);
 		expect(config.core?.deployment?.mode).toBe("multi");
 	});
 
@@ -814,8 +1070,14 @@ describe("the shipped config boots with every documented override supplied as a
 		// list covers core's modules only, and cannot see the template's own
 		// memory modules.
 		const { replicaUnsafeReason } = await import("@o3co/auth-provider-core");
-		for (const module of buildModules(readShippedSwitches(UMBRELLA_E2E_ENV))) {
-			expect(replicaUnsafeReason(module), module.name).toBeUndefined();
+		// Each module's section at its name: a declaration made from the
+		// section is answered for it.
+		const own = readOwnLayers(ownFiles("production"), { env: UMBRELLA_E2E_ENV });
+		const switches = readSwitches(own);
+		const modules = buildModules(switches);
+		const sections = resolveForBoot(own, modules, switches) as unknown as Record<string, unknown>;
+		for (const module of modules) {
+			expect(replicaUnsafeReason(module, sections[module.name]), module.name).toBeUndefined();
 		}
 	});
 
@@ -852,7 +1114,7 @@ describe("the shipped config boots with every documented override supplied as a
 					...DOCUMENTED_ENV,
 					OAUTH_JWT_LEGACY_TYP_ACCEPT: supplied,
 				});
-				expect(config.oauth.jwt.legacyTypAccept).toBe(expected);
+				expect(oauthSection(config).jwt.legacyTypAccept).toBe(expected);
 			});
 		}
 
@@ -916,13 +1178,13 @@ describe("the shipped config boots with every documented override supplied as a
 	});
 
 	describe("variables whose documented behaviour is to fail boot", () => {
-		it("refuses OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS, naming allowUnmarkedClients", async () => {
-			await expect(
-				bootParsed({
-					...DOCUMENTED_ENV,
-					OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS: "true",
-				}),
-			).rejects.toThrow(/allowUnmarkedClients/);
+		it("refuses OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS as the variable of a removed key, naming allowUnmarkedClients", async () => {
+			const booting = bootParsed({
+				...DOCUMENTED_ENV,
+				OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS: "true",
+			});
+			await expect(booting).rejects.toMatchObject({ reason: "environment-variable-renamed" });
+			await expect(booting).rejects.toThrow(/oauth\.authorize\.allowUnmarkedClients/);
 		});
 
 		it("refuses an access-token default above the max, naming both keys", async () => {
@@ -938,30 +1200,63 @@ describe("the shipped config boots with every documented override supplied as a
 		for (const name of [
 			"OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN",
 			"OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN",
-			"OAUTH_ACCESS_TOKEN_EXPIRES_IN",
 		]) {
 			it(`refuses an empty ${name} rather than minting already-expired tokens`, async () => {
-				await expect(bootParsed({ ...DOCUMENTED_ENV, [name]: "" })).rejects.toThrow();
+				await expect(bootParsed({ ...DOCUMENTED_ENV, [name]: "" })).rejects.toMatchObject({
+					reason: "config-validation-failed",
+				});
 			});
 		}
 
 		it("refuses MFA_MODE that is none of the three before boot, naming mfaMode", async () => {
 			const env = { ...DOCUMENTED_ENV, MFA_MODE: "on" };
-			expect(() => readShippedSwitches(env)).toThrow(RangeError);
+			expect(() => readShippedSwitches(env)).toThrow(BootError);
 			await expect(bootParsed(env)).rejects.toThrow(/mfaMode/);
 		});
 
 		for (const mode of ["optional", "required"] as const) {
 			it(`reads MFA_MODE=${mode} as the switch that installs MFA, expecting mfa`, () => {
-				const switches = readShippedSwitches({ ...DOCUMENTED_ENV, MFA_MODE: mode });
+				const own = readOwnLayers(ownFiles("production"), {
+					env: { ...DOCUMENTED_ENV, MFA_MODE: mode },
+				});
+				const switches = readSwitches(own);
 				expect(switches.mfaMode).toBe(mode);
-				expect(expectedSessionRequirements(switches)).toEqual({
+				const shipped = (resolveLayers(own, []).core as { sessionRequirements?: unknown })
+					.sessionRequirements;
+				expect(expectedSessionRequirements(shipped, switches.mfaMode)).toEqual({
 					expected: ["mfa"],
 					secondFactorAuthority: "mfa",
 				});
 			});
 		}
 
+		it("refuses OAUTH_ACCESS_TOKEN_EXPIRES_IN set alone, naming OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN", async () => {
+			const { OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN: _new, ...env } = DOCUMENTED_ENV;
+			const booting = bootParsed({ ...env, OAUTH_ACCESS_TOKEN_EXPIRES_IN: "900" });
+			await expect(booting).rejects.toMatchObject({ reason: "environment-variable-renamed" });
+			await expect(booting).rejects.toThrow(
+				/OAUTH_ACCESS_TOKEN_EXPIRES_IN was renamed OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN/,
+			);
+		});
+
+		it("refuses OAUTH_ACCESS_TOKEN_EXPIRES_IN beside its new name set to another value", async () => {
+			await expect(
+				bootParsed({ ...DOCUMENTED_ENV, OAUTH_ACCESS_TOKEN_EXPIRES_IN: "3600" }),
+			).rejects.toMatchObject({ reason: "environment-variable-renamed" });
+		});
+
+		it("boots with OAUTH_ACCESS_TOKEN_EXPIRES_IN beside its new name set to the same value, reading the new name", async () => {
+			const config = await bootParsed({
+				...DOCUMENTED_ENV,
+				OAUTH_ACCESS_TOKEN_EXPIRES_IN:
+					DOCUMENTED_ENV.OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN as string,
+			});
+			expect(oauthSection(config).accessToken).toEqual({
+				defaultExpiresIn: 900,
+				maxExpiresIn: 7200,
+			});
+		});
+
 		it("refuses DEPLOYMENT_MODE set alone, naming CORE_DEPLOYMENT_MODE", async () => {
 			const { CORE_DEPLOYMENT_MODE: _new, ...env } = DOCUMENTED_ENV;
 			await expect(bootParsed({ ...env, DEPLOYMENT_MODE: "multi" })).rejects.toThrow(