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

package/templates/standalone/src/__tests__/three-tier-resolution.test.mts

@@ -15,21 +15,27 @@
  */
 
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema, coreReference } from "@o3co/auth-provider-core";
+import type { AppConfig } from "@o3co/auth-provider-core";
+import { type OAuthSection, oauthEndpointsModule } from "@o3co/auth-provider-oauth";
 import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
 import { describe, expect, it } from "vitest";
 import { readAdapters } from "../adapters.mjs";
 import { buildModules } from "../buildModules.mjs";
-import { resolveConfigPaths, type Switches } from "../configPath.mjs";
-import { readMfaSwitch } from "../mfaSwitch.mjs";
+import {
+	readOwnLayers,
+	readSwitches,
+	resolveConfigPaths,
+	resolveForBoot,
+	type Switches,
+} from "../configPath.mjs";
 import { templateReference } from "../modules.mjs";
+import { type BothPhases, withSwitches } from "./library-references.fixture.mjs";
 
 // config/ is two levels above this test file:
 //   src/__tests__/ → src/ → standalone/ → config/
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
-// Provide required secrets so AppConfigSchema parse succeeds. These are
+// Provide the secrets the template's files require. These are
 // test-only values — no real keys are embedded here. SESSION_STORE_SECRET
 // carries a 256-bit entropy floor, so these clear it (the '.' characters keep
 // them outside the base64 alphabet, so the UTF-8 length is what counts).
@@ -40,30 +46,32 @@ const testEnv = {
 };
 
 /**
- * The three tiers under `env`, parsed with core's schema, beside the
- * composition root's `adapters` and `mfaMode` phase one reads from the
- * template's own layers.
+ * The three tiers under `env`, as `app.mts` reads them: what phase one reads
+ * of the template's own layers, laid over what phase two hands boot — the
+ * own layers over the reference of every package the chosen modules come
+ * from, resolved and unparsed.
  */
-function buildResolvedConfig(env: string, extraEnv: Record<string, string> = {}): Switches {
+function buildResolvedConfig(env: string, extraEnv: Record<string, string> = {}): BothPhases {
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, env);
-	const libraryReferencePath = fileURLToPath(coreReference());
-	const resolvedEnv = { ...testEnv, ...extraEnv };
-	const own = parseFile(envConfPath, { env: resolvedEnv })
-		.withFallback(parseFile(applicationConfPath, { env: resolvedEnv }))
-		.withFallback(parseFile(fileURLToPath(templateReference()), { env: resolvedEnv }));
-	return {
-		...validate(
-			own.withFallback(parseFile(libraryReferencePath, { env: resolvedEnv })),
-			AppConfigSchema,
-		),
-		adapters: readAdapters(own.toObject() as Record<string, unknown>, resolvedEnv),
-		mfaMode: readMfaSwitch(own.toObject() as Record<string, unknown>, resolvedEnv),
-		storeTransport: undefined,
-	};
+	const own = readOwnLayers([envConfPath, applicationConfPath], {
+		env: { ...testEnv, ...extraEnv },
+	});
+	const switches = readSwitches(own);
+	return withSwitches(
+		resolveForBoot(own, buildModules(switches), switches) as unknown as Record<string, unknown>,
+		switches,
+	);
+}
+
+/** `oauth.resourceIndicator` as the section's owner, the oauth module, parses it at boot. */
+function parsedResourceIndicator(config: AppConfig): { readonly enabled?: unknown } | undefined {
+	const schema = oauthEndpointsModule.section?.schema;
+	if (schema === undefined) throw new Error("the oauth module declares no section");
+	return (schema.parse(config.oauth) as { resourceIndicator?: { enabled?: unknown } })
+		.resourceIndicator;
 }
 
-// The oauth-authorization module's section, which core mirrors for the one
-// key read before the modules are chosen (`grants`), kept as written: the
+// The oauth-authorization module's section as resolved, unparsed: the
 // runtime shape is a string from env substitution, a boolean from a literal.
 type GrantEntry = { enabled?: unknown };
 const grants = (config: AppConfig) =>
@@ -71,6 +79,9 @@ const grants = (config: AppConfig) =>
 		| Record<string, GrantEntry | undefined>
 		| undefined) ?? {};
 
+/** `oauth {}` as the resolution leaves it, read as the shape the oauth module parses. */
+const oauthOf = (config: AppConfig): OAuthSection => config.oauth as OAuthSection;
+
 describe("three-tier HOCON resolution (env → application.conf → reference.conf)", () => {
 	it("template application.conf wins over reference.conf for grant.enabled", () => {
 		const config = buildResolvedConfig("development");
@@ -83,15 +94,15 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		const config = buildResolvedConfig("development");
 		// nonce.maxLength is library-owned in both layers (template doesn't
 		// override it). Verifies precedence falls through.
-		expect(config.oauth.nonce?.maxLength).toBe(256);
+		expect(oauthOf(config).nonce?.maxLength).toBe(256);
 	});
 
 	it("env var at template layer can disable a template-enabled grant (precedence: env-override line must be repeated)", () => {
 		// The env-override line is repeated at the template layer alongside
 		// `enabled = true`; without it, the package reference's substitution is
-		// shadowed by the template's literal `true`. The value stays a string:
-		// core mirrors the section as written, and the module reads the switch
-		// with its own schema, `"false"` as off.
+		// shadowed by the template's literal `true`. The value stays a string
+		// until boot: the module reads the switch with its own schema, `"false"`
+		// as off.
 		const config = buildResolvedConfig("development", {
 			OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED: "false",
 		});
@@ -132,7 +143,8 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		// schema coercion (coerceBooleanFromEnv) can produce a boolean value.
 		// Without the HOCON block the field resolves to undefined.
 		const config = buildResolvedConfig("development");
-		expect(config.oauth.resourceIndicator?.enabled).toBe(false);
+		expect(oauthOf(config).resourceIndicator?.enabled).toBe(false);
+		expect(parsedResourceIndicator(config)?.enabled).toBe(false);
 	});
 
 	it("env var OAUTH_RESOURCE_INDICATOR_ENABLED=true reaches resolved config and coerces to boolean true", () => {
@@ -143,7 +155,8 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		const config = buildResolvedConfig("development", {
 			OAUTH_RESOURCE_INDICATOR_ENABLED: "true",
 		});
-		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
+		expect(oauthOf(config).resourceIndicator?.enabled).toBe("true");
+		expect(parsedResourceIndicator(config)?.enabled).toBe(true);
 	});
 
 	// The selection is the composition root's own, `adapters.auditSink`,
@@ -190,7 +203,7 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 
 		it("resolves oauth.revocation.accessToken to denylist with nothing set", () => {
 			const config = buildResolvedConfig("production");
-			expect(config.oauth.revocation?.accessToken).toBe("denylist");
+			expect(oauthOf(config).revocation?.accessToken).toBe("denylist");
 		});
 
 		it("picks the replica-safe denylist module for that resolved config", () => {
@@ -221,8 +234,11 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 			});
 			const modules = buildModules(config);
 			expect(modules.map((m) => m.name)).toContain("redis-access-token-denylist");
+			// Each module's section at its name: a declaration made from the
+			// section is answered for it.
+			const sections = config as unknown as Record<string, unknown>;
 			for (const module of modules) {
-				expect(replicaUnsafeReason(module), module.name).toBeUndefined();
+				expect(replicaUnsafeReason(module, sections[module.name]), module.name).toBeUndefined();
 			}
 		});
 
@@ -239,7 +255,7 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 			const config = buildResolvedConfig("production", {
 				OAUTH_REVOCATION_ACCESS_TOKEN: "unsupported",
 			});
-			expect(config.oauth.revocation?.accessToken).toBe("unsupported");
+			expect(oauthOf(config).revocation?.accessToken).toBe("unsupported");
 		});
 	});
 });

package/templates/standalone/src/__tests__/two-phase-config.test.mts

@@ -17,52 +17,58 @@
 /**
  * The template reads its configuration in two phases, as `app.mts` does:
  *
- * 1. `readSwitches` — its own files over core's `reference.conf`, read with
- *    core's transitional reader — parses only `SWITCHES`, what the template
- *    reads before it knows its modules: the switches `buildModules` chooses
- *    them by, and the configuration's `core.sessionRequirements`, which
- *    `expectedSessionRequirements` reads (the log level is the `logging`
- *    module's section, which `readLogging` reads with that module's schema:
- *    `own-modules.test.mts`) — and the composition root's own `adapters` and
- *    `mfaMode`, over the template's own reference, with the template's
- *    schema (`adapters.test.mts`, `mfa-switch.test.mts`), and the Store
- *    transport settings beside them, unparsed;
+ * 1. `readSwitches` — its own files over the template's own `reference.conf`
+ *    — reads only what the template reads before it knows its modules: the
+ *    composition root's own `adapters` and `mfaMode`, with the template's
+ *    schema (`adapters.test.mts`, `mfa-switch.test.mts`), the Store transport
+ *    settings beside them, unparsed, and whether federation grants are
+ *    installed, from `federation-grants.enabled` read with core's
+ *    `coerceBooleanFromEnv` (the log level is the `logging` module's
+ *    section, which `readLogging` reads with that module's schema:
+ *    `own-modules.test.mts`);
  * 2. `resolveForBoot` — its own files over the `reference.conf` of every
  *    package its modules come from, core's last — handed to `createApp`
  *    unparsed, which parses it once with every loaded module's schema.
  *
- * Phase one must read each switch as a parse of the same layers with
- * `AppConfigSchema` (through the HOCON library's Zod bridge) does, and nothing
- * but its switches, so that a section a package's reference completes (known
- * only in phase two) does not refuse it.
+ * Phase one must read `federation-grants.enabled` as the federation-grants
+ * module's own schema and boot's parse do, and install the module for a value
+ * they refuse, so that boot refuses it; and it reads nothing else, so that a
+ * section a package's reference completes (known only in phase two) does not
+ * refuse it.
  */
 
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { AppConfigSchema, coreReference, createApp, type Module } from "@o3co/auth-provider-core";
+import {
+	BootError,
+	createApp,
+	defineModule,
+	type Module,
+	moduleReferences,
+} from "@o3co/auth-provider-core";
+import {
+	federationGrantsConfigSchema,
+	federationGrantsModules,
+} from "@o3co/auth-provider-federation-grants";
+import { oauthEndpointsModule } from "@o3co/auth-provider-oauth";
 import {
 	redisFederationGrantIntentStoreModule,
 	redisFederationGrantStoreModule,
 } from "@o3co/auth-provider-redis";
-import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
 import { describe, expect, it } from "vitest";
 import { ADAPTERS_SECTION } from "../adapters.mjs";
 import { buildModules } from "../buildModules.mjs";
 import {
-	expectedSessionRequirements,
 	readOwnLayers,
 	readSwitches,
 	resolveConfigPaths,
 	resolveForBoot,
 	resolveLayers,
-	SWITCHES,
 	type Switches,
 } from "../configPath.mjs";
 import { MFA_SWITCH } from "../mfaSwitch.mjs";
-import { templateReference } from "../modules.mjs";
 
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
@@ -93,22 +99,24 @@ const ENVIRONMENTS: Readonly<Record<string, Readonly<Record<string, string>>>> =
 	},
 };
 
+/** What phase one answers: the composition root's own keys, and the one switch of a module's section it decides by. */
+const PHASE_ONE_PATHS: readonly string[] = [
+	ADAPTERS_SECTION,
+	MFA_SWITCH,
+	"storeTransport",
+	"federation-grants.enabled",
+];
+
 const ownFiles = (environment: string): string[] => {
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, environment);
 	return [envConfPath, applicationConfPath];
 };
 
-/** The layers parsed with `AppConfigSchema` through the bridge: how phase one must read each switch. */
-function preParsed(environment: string, env: Readonly<Record<string, string>>): unknown {
-	const read = (file: string) => parseFile(file, { env: { ...env } });
-	const [top, application] = ownFiles(environment) as [string, string];
-	return validate(
-		read(top)
-			.withFallback(read(application))
-			.withFallback(read(fileURLToPath(templateReference())))
-			.withFallback(read(fileURLToPath(coreReference()))),
-		AppConfigSchema,
-	);
+/** `federation-grants.enabled` as the federation-grants module's own schema parses the same layers. */
+function ownerReads(environment: string, env: Readonly<Record<string, string>>): unknown {
+	const own = readOwnLayers(ownFiles(environment), { env });
+	const resolved = resolveLayers(own, moduleReferences(federationGrantsModules));
+	return federationGrantsConfigSchema.parse(resolved["federation-grants"])?.enabled;
 }
 
 /** The value at a dotted path, or `undefined`. */
@@ -145,27 +153,125 @@ function recording(config: unknown): { readonly config: Switches; readonly reads
 	return { config: wrap(config as object, "") as Switches, reads };
 }
 
-describe("phase one reads each switch as the template's AppConfigSchema pre-parse read it", () => {
+describe("phase one reads federation-grants.enabled as the federation-grants module reads it", () => {
 	for (const environment of ["development", "production"]) {
 		for (const [name, env] of Object.entries(ENVIRONMENTS)) {
 			it(`${environment}, ${name}`, () => {
-				const before = preParsed(environment, env);
 				const switches = readSwitches(readOwnLayers(ownFiles(environment), { env }));
-				const changed = SWITCHES.filter(
-					(path) =>
-						JSON.stringify(valueAt(before, path)) !== JSON.stringify(valueAt(switches, path)),
-				);
-				expect(changed).toEqual([]);
+				expect(switches["federation-grants"]?.enabled).toBe(ownerReads(environment, env) ?? false);
 			});
 		}
 	}
 
+	it.each([
+		["true", true],
+		["1", true],
+		[" TRUE ", true],
+		["false", false],
+		["0", false],
+		["", false],
+	])("reads FEDERATION_GRANTS_ENABLED=%j as the module's schema does: %s", (value, enabled) => {
+		const env = { ...REQUIRED_ENV, FEDERATION_GRANTS_ENABLED: value };
+		const switches = readSwitches(readOwnLayers(ownFiles("production"), { env }));
+		expect(switches["federation-grants"]?.enabled).toBe(enabled);
+		expect(ownerReads("production", env)).toBe(enabled);
+	});
+
+	it.each([
+		["true", true],
+		["false", false],
+	])("reads federation-grants.enabled = %s written in HOCON", (literal, enabled) => {
+		const operator = operatorLayer(`federation-grants.enabled = ${literal}\n`);
+		const switches = readSwitches(
+			readOwnLayers([operator, ...ownFiles("production")], { env: REQUIRED_ENV }),
+		);
+		expect(switches["federation-grants"]?.enabled).toBe(enabled);
+	});
+
+	it.each([
+		'federation-grants = "x"',
+		"federation-grants = null",
+		"federation-grants.enabled = 1",
+		"federation-grants.enabled = null",
+	])("installs the modules for %s, which the module's schema refuses", (hocon) => {
+		const operator = operatorLayer(`${hocon}\n`);
+		const own = readOwnLayers([operator, ...ownFiles("production")], {
+			env: { ...REQUIRED_ENV, MFA_MODE: "off" },
+		});
+		const resolved = resolveLayers(own, moduleReferences(federationGrantsModules));
+		expect(federationGrantsConfigSchema.safeParse(resolved["federation-grants"]).success).toBe(
+			false,
+		);
+		const switches = readSwitches(own);
+		expect(switches["federation-grants"]?.enabled).toBe(true);
+		expect(
+			buildModules(switches, { environment: "production" }).map((module) => module.name),
+		).toContain("federation-grants");
+	});
+
+	it("leaves the modules out for an empty section at the old path, federationGrants {}, which sets nothing", () => {
+		const operator = operatorLayer("federationGrants {}\n");
+		const switches = readSwitches(
+			readOwnLayers([operator, ...ownFiles("production")], {
+				env: { ...REQUIRED_ENV, MFA_MODE: "off" },
+			}),
+		);
+		expect(switches["federation-grants"]?.enabled).toBe(false);
+		expect(
+			buildModules(switches, { environment: "production" }).map((module) => module.name),
+		).not.toContain("federation-grants");
+	});
+
+	it("reads the switch unwritten as off", () => {
+		const operator = operatorLayer('mfaMode = "off"\n');
+		const switches = readSwitches(readOwnLayers([operator], { env: {} }));
+		expect(switches["federation-grants"]?.enabled).toBe(false);
+	});
+
+	it("installs the modules for a value the module's schema refuses, so that boot refuses it naming the key", async () => {
+		const env = { ...REQUIRED_ENV, MFA_MODE: "off", FEDERATION_GRANTS_ENABLED: "yes" };
+		expect(() => ownerReads("production", env)).toThrow();
+		const own = readOwnLayers(ownFiles("production"), { env });
+		const switches = readSwitches(own);
+		expect(switches["federation-grants"]?.enabled).toBe(true);
+		const modules = buildModules(switches, { environment: "production" });
+		expect(modules.map((module) => module.name)).toContain("federation-grants");
+		const err = await createApp({
+			modules,
+			bootstrapComponents: {
+				config: resolveForBoot(own, modules, switches),
+				pathResolver: (s: string) => s,
+			},
+		}).then(
+			async (handle) => {
+				await handle.dispose();
+				return undefined;
+			},
+			(caught: unknown) => caught,
+		);
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).reason).toBe("config-validation-failed");
+		expect((err as BootError).message).toContain("federation-grants.enabled");
+	});
+
+	it("installs the modules for a setting at the section's old path, which boot refuses naming the new one", () => {
+		const operator = operatorLayer("federationGrants.enabled = true\n");
+		const switches = readSwitches(
+			readOwnLayers([operator, ...ownFiles("production")], {
+				env: { ...REQUIRED_ENV, MFA_MODE: "off" },
+			}),
+		);
+		expect(switches["federation-grants"]?.enabled).toBe(true);
+		expect(
+			buildModules(switches, { environment: "production" }).map((module) => module.name),
+		).toContain("federation-grants");
+	});
+
 	it("reads the MFA switch as its own mfaMode, as the environment sets it, and no key of the MFA module's", () => {
-		expect(SWITCHES.filter((path) => path.split(".")[0] === "mfa")).toEqual([]);
 		for (const [name, env] of Object.entries(ENVIRONMENTS)) {
-			expect(readSwitches(readOwnLayers(ownFiles("production"), { env })).mfaMode, name).toBe(
-				env.MFA_MODE ?? "required",
-			);
+			const switches = readSwitches(readOwnLayers(ownFiles("production"), { env }));
+			expect(switches.mfaMode, name).toBe(env.MFA_MODE ?? "required");
+			expect(switches, name).not.toHaveProperty("mfa");
 		}
 	});
 });
@@ -176,26 +282,30 @@ describe("phase one reads its switches and nothing else", () => {
 	>;
 
 	it("accepts a section a package's reference completes, which only phase two layers", () => {
-		// The device grant's and WebAuthn's references ship `windowSeconds`;
-		// boot layers them, and accepts what the operator wrote.
-		const partial = operatorLayer(
-			"device-grant.rateLimit.limit = 10\nwebauthn.rateLimit.authenticationOptions.limit = 10\n",
-		);
+		// The device grant's reference ships `windowSeconds`; boot layers it,
+		// and accepts what the operator wrote.
+		const partial = operatorLayer("device-grant.rateLimit.limit = 10\n");
 		expect(() =>
 			readSwitches(readOwnLayers([partial, ...ownFiles("production")], { env })),
 		).not.toThrow();
 	});
 
+	it("answers the composition root's own keys and federation-grants.enabled, nothing of core's section or any other module's", () => {
+		const switches = readSwitches(readOwnLayers(ownFiles("production"), { env }));
+		expect(Object.keys(switches).sort()).toEqual(
+			[ADAPTERS_SECTION, MFA_SWITCH, "storeTransport", "federation-grants"].sort(),
+		);
+		expect(Object.keys(switches["federation-grants"] ?? {})).toEqual(["enabled"]);
+	});
+
 	it("reads, before boot, only paths among its switches", () => {
 		const { config, reads } = recording(
 			readSwitches(readOwnLayers(ownFiles("production"), { env })),
 		);
-		// What `app.mts` reads of phase one: the modules, and what the
-		// composition expects of session admission.
-		expectedSessionRequirements(config);
+		// What `app.mts` reads of phase one before boot: the modules.
 		buildModules(config, { environment: "production" });
 		const covered = (path: string) =>
-			[...SWITCHES, ADAPTERS_SECTION, MFA_SWITCH, "storeTransport"].some(
+			PHASE_ONE_PATHS.some(
 				(switchPath) =>
 					path === switchPath ||
 					path.startsWith(`${switchPath}.`) ||
@@ -205,6 +315,25 @@ describe("phase one reads its switches and nothing else", () => {
 		expect([...reads].filter((path) => !covered(path))).toEqual([]);
 	});
 
+	it("reads no federation entry: core dispatches each by its type at boot", () => {
+		const federationEnvs: readonly Readonly<Record<string, string>>[] = [
+			{},
+			{ CORE_FEDERATIONS_GOOGLE_ENABLED: "true" },
+		];
+		for (const federations of federationEnvs) {
+			const { config, reads } = recording(
+				readSwitches(readOwnLayers(ownFiles("production"), { env: { ...env, ...federations } })),
+			);
+			expect(config).not.toHaveProperty("core");
+			buildModules(config, { environment: "production" });
+			expect(
+				[...reads].filter(
+					(path) => path === "core.federations" || path.startsWith("core.federations."),
+				),
+			).toEqual([]);
+		}
+	});
+
 	it("still refuses a switch it reads that the schema refuses, naming it", () => {
 		const bad = operatorLayer('adapters.rateLimiter = "carrier-pigeon"\n');
 		expect(() => readSwitches(readOwnLayers([bad, ...ownFiles("production")], { env }))).toThrow(
@@ -228,7 +357,7 @@ describe("phase two: what createApp is handed", () => {
 		const reference = join(dir, "reference.conf");
 		writeFileSync(
 			reference,
-			'widget { size = 3 }\noauth.revocation.accessToken = "widget-revocation"\noauth.oidcMode = "widget-mode"\n',
+			'widget { size = 3 }\noauth.revocation.accessToken = "widget-revocation"\ncore.tokenBinding.dispatchPolicy = "widget-policy"\n',
 		);
 		return {
 			name: "widget",
@@ -247,7 +376,9 @@ describe("phase two: what createApp is handed", () => {
 		// The template's application.conf wins over a package's reference…
 		expect(resolved.oauth?.revocation).toEqual({ accessToken: "denylist" });
 		// …and a package's reference over core's.
-		expect(resolved.oauth?.oidcMode).toBe("widget-mode");
+		expect(
+			(resolved.core?.tokenBinding as { dispatchPolicy?: unknown } | undefined)?.dispatchPolicy,
+		).toBe("widget-policy");
 	});
 
 	it("layers no reference a loaded module does not declare", () => {
@@ -292,18 +423,29 @@ describe("phase two refuses the Redis grant store's key prefix moved while the i
 	};
 
 	/** What phase two refused with. */
-	const refusal = (...args: Parameters<typeof resolve>): RangeError => {
+	const refusal = (...args: Parameters<typeof resolve>): BootError => {
 		try {
 			resolve(...args);
 		} catch (err) {
-			if (err instanceof RangeError) return err;
+			if (err instanceof BootError) return err;
 			throw err;
 		}
 		throw new Error("phase two resolved");
 	};
 
 	it("the grant store's set and the intent store's left alone: refused, naming both keys and both variables and quoting no value", () => {
-		const { message } = refusal({ [GRANT]: "t1:fg:" });
+		const { message, reason, details } = refusal({ [GRANT]: "t1:fg:" });
+		expect(reason).toBe("config-validation-failed");
+		expect(details).toMatchObject({
+			issues: [{ code: "custom", path: ["redis-federation-grant-intent-store", "keyPrefix"] }],
+			modules: [
+				{
+					module: "redis-federation-grant-intent-store",
+					schemaPath: "redis-federation-grant-intent-store",
+				},
+			],
+		});
+		expect(JSON.stringify(details)).not.toContain("fg:");
 		expect(message).toContain(`redis-federation-grant-store.keyPrefix (${GRANT})`);
 		expect(message).toContain(`redis-federation-grant-intent-store.keyPrefix (${INTENT})`);
 		expect(message).not.toContain("fg:");
@@ -341,11 +483,23 @@ describe("phase two refuses the Redis grant store's key prefix moved while the i
 
 	it("grants kept in memory and intents on Redis: the grant store's key at its old path, which no loaded module relocates, refused naming the intent store's", () => {
 		const operator = operatorLayer('redisFederationGrantStore.keyPrefix = "t1:fg:"\n');
-		const { message } = refusal(
+		const { message, reason, details } = refusal(
 			{ [INTENT]: "t1:fgi:" },
 			[redisFederationGrantIntentStoreModule],
 			[operator, ...ownFiles("development")],
 		);
+		expect(reason).toBe("config-path-relocated");
+		expect(details).toEqual({
+			reason: "config-path-relocated",
+			relocated: [
+				{
+					module: "redis-federation-grant-intent-store",
+					from: "redisFederationGrantStore.keyPrefix",
+					to: "redis-federation-grant-intent-store.keyPrefix",
+					environmentVariable: INTENT,
+				},
+			],
+		});
 		expect(message).toContain("redisFederationGrantStore.keyPrefix");
 		expect(message).toContain(`redis-federation-grant-intent-store.keyPrefix (${INTENT})`);
 		expect(message).not.toContain("fg:");
@@ -363,25 +517,25 @@ describe("both phases read one snapshot of the composition's own layers", () =>
 
 	it("sees a file's first contents in both phases, though it is replaced between them", () => {
 		// Mounted configuration is commonly replaced atomically: read twice,
-		// boot could parse the Redis session store while phase one chose the
-		// memory one, and nothing would refuse the disagreement.
-		const operator = operatorLayer('session-store.storage.type = "redis"\n');
+		// boot could parse the federation-grants routes off while phase one
+		// installed them, and nothing would refuse the disagreement.
+		const operator = operatorLayer("federation-grants.enabled = true\n");
 		const own = readOwnLayers([operator, ...ownFiles("production")], { env });
-		writeFileSync(operator, 'session-store.storage.type = "memory"\n');
+		writeFileSync(operator, "federation-grants.enabled = false\n");
 		const switches = readSwitches(own);
 		const resolved = resolveForBoot(own, [], switches);
-		expect(valueAt(switches, "session-store.storage.type")).toBe("redis");
-		expect(valueAt(resolved, "session-store.storage.type")).toBe("redis");
+		expect(valueAt(switches, "federation-grants.enabled")).toBe(true);
+		expect(valueAt(resolved, "federation-grants.enabled")).toBe(true);
 	});
 
 	it("substitutes one snapshot of the environment in both phases", () => {
-		const changing: Record<string, string> = { ...env, SESSION_STORE_STORAGE_TYPE: "redis" };
+		const changing: Record<string, string> = { ...env, FEDERATION_GRANTS_ENABLED: "true" };
 		const own = readOwnLayers(ownFiles("production"), { env: changing });
-		changing.SESSION_STORE_STORAGE_TYPE = "memory";
+		changing.FEDERATION_GRANTS_ENABLED = "false";
 		const switches = readSwitches(own);
 		const resolved = resolveForBoot(own, [], switches);
-		expect(valueAt(switches, "session-store.storage.type")).toBe("redis");
-		expect(valueAt(resolved, "session-store.storage.type")).toBe("redis");
+		expect(valueAt(switches, "federation-grants.enabled")).toBe(true);
+		expect(valueAt(resolved, "federation-grants.enabled")).toBe("true");
 	});
 
 	it("reads the adapters from the same snapshot of the environment", () => {
@@ -401,21 +555,35 @@ describe("both phases read one snapshot of the composition's own layers", () =>
 				const own = readOwnLayers(ownFiles(environment), { env: variables });
 				const switches = readSwitches(own);
 				const modules = buildModules(switches, { environment });
+				const resolved = resolveForBoot(own, modules, switches);
 				const handle = await createApp({
-					modules: [],
+					// The oauth module's section alone, read without its factories:
+					// the template loads the module, and core refuses keys of
+					// `oauth {}` where no loaded module's section is `oauth`.
+					modules: [
+						defineModule({
+							name: oauthEndpointsModule.name,
+							...(oauthEndpointsModule.section === undefined
+								? {}
+								: { section: oauthEndpointsModule.section }),
+						}),
+					],
 					bootstrapComponents: {
-						config: resolveForBoot(own, modules, switches),
+						config: resolved,
 						pathResolver: (s: string) => s,
 						...FEDERATION_STORES,
 					} as never,
 				});
 				const parsed = handle.components.config;
 				await handle.dispose();
-				const differing = SWITCHES.filter(
-					(path) =>
-						JSON.stringify(valueAt(switches, path)) !== JSON.stringify(valueAt(parsed, path)),
+				// Unwritten, the switch reads as off, as the shipped files leave it
+				// unless FEDERATION_GRANTS_ENABLED is set.
+				expect(valueAt(switches, "federation-grants.enabled"), `${environment}, ${name}`).toBe(
+					valueAt(parsed, "federation-grants.enabled") ?? false,
+				);
+				expect(valueAt(resolved, "core.sessionRequirements"), `${environment}, ${name}`).toEqual(
+					valueAt(parsed, "core.sessionRequirements"),
 				);
-				expect(differing, `${environment}, ${name}`).toEqual([]);
 			}
 		}
 	});
@@ -429,9 +597,7 @@ describe("both phases read one snapshot of the composition's own layers", () =>
 const FEDERATION_STORES = Object.fromEntries(
 	[
 		"userSessionStore",
-		"sessionRPRegistry",
-		"sessionFamilyIndex",
-		"sessionFederationIndex",
+		"sessionLifecycle",
 		"federationTokenStore",
 		"refreshTokenFamilyRevocation",
 	].map((key) => [key, {}]),