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

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

@@ -15,94 +15,127 @@
  */
 
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema } 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, resolveLibraryReferenceConfPath } from "../configPath.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
-// test-only values — no real keys are embedded here. #282: SESSION_SECRET
+// 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).
 const testEnv = {
-	OAUTH_JWT_SECRET: "test-secret-three-tier.at-least-32-bytes.ok",
+	KEY_STORE_LOCAL_SECRET: "test-secret-three-tier.at-least-32-bytes.ok",
 	OAUTH_JWT_ISSUER: "https://auth.test",
-	SESSION_SECRET: "test-session-secret-three-tier.at-least-32-bytes.ok",
+	SESSION_STORE_SECRET: "test-session-secret-three-tier.at-least-32-bytes.ok",
 };
 
-function buildResolvedConfig(env: string, extraEnv: Record<string, string> = {}): AppConfig {
+/**
+ * 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> = {}): BothPhases {
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, env);
-	const libraryReferencePath = resolveLibraryReferenceConfPath();
-	const resolvedEnv = { ...testEnv, ...extraEnv };
-	return validate(
-		parseFile(envConfPath, { env: resolvedEnv })
-			.withFallback(parseFile(applicationConfPath, { env: resolvedEnv }))
-			.withFallback(parseFile(libraryReferencePath, { env: resolvedEnv })),
-		AppConfigSchema,
+	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.grants` is declared as `z.object({}).passthrough()` in the schema,
-// so the inferred TS type is `{}` per entry and accessing `.enabled` doesn't
-// compile under `tsc --strict`. Tests assert against the resolved runtime
-// shape (string from env substitution, boolean from literal), so the cast
-// is intentional and well-bounded.
+/** `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 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) =>
-	(config.oauth.grants as unknown as Record<string, GrantEntry | undefined>) ?? {};
+	((config["oauth-authorization"] as { grants?: unknown } | undefined)?.grants as
+		| 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");
-		// Template's application.conf sets authorization_code.enabled = true.
-		// This test asserts the resolved value — it remains true whether
-		// reference.conf says false (current secure-default) or true (legacy).
-		expect(grants(config).authorization_code?.enabled).toBe(true);
+		// Template's application.conf sets authorizationCode.enabled = true,
+		// so the resolved value is true whatever reference.conf says.
+		expect(grants(config).authorizationCode?.enabled).toBe(true);
 	});
 
 	it("reference.conf default reaches resolved config when template omits the key", () => {
 		const config = buildResolvedConfig("development");
-		// tokenExchange.maxActorChainDepth is library-owned in both layers
-		// (template doesn't override it). Verifies precedence falls through.
-		expect(config.oauth.tokenExchange?.maxActorChainDepth).toBe(3);
+		// nonce.maxLength is library-owned in both layers (template doesn't
+		// override it). Verifies precedence falls through.
+		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)", () => {
-		// Template enables authorization_code via application.conf. The env-override
-		// line is repeated at the template layer alongside `enabled = true`,
-		// so OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED=false reaches the resolved value.
-		// Without the repeated env line, the substitution at reference.conf is
-		// shadowed by the template's literal `true`.
-		// Note: ts.hocon substitutes env vars as strings, and `oauth.grants` is
-		// `z.object({}).passthrough()` — an open tree each grant module's own
-		// `configSchema` validates — so no shape-walking coercion reaches this
-		// leaf and the string survives to the resolved config. #288 unified the
-		// coercion for every DECLARED boolean in the schema and deliberately
-		// left this one alone: every consumer of a grant's `enabled`
-		// (`GrantRegistry.isEnabled`, `oauthAuthorization`, `oauthSession`)
-		// already reads `true` and `"true"` as enabled and everything else,
-		// `"false"` included, as not-enabled.
+		// 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
+		// until boot: the module reads the switch with its own schema, `"false"`
+		// as off.
 		const config = buildResolvedConfig("development", {
-			OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED: "false",
+			OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED: "false",
 		});
-		expect(grants(config).authorization_code?.enabled).toBe("false");
+		expect(grants(config).authorizationCode?.enabled).toBe("false");
+	});
+
+	it("reads the MFA switch, mfaMode, as required where MFA_MODE is unset, and installs no MFA module under MFA_MODE=off", () => {
+		// The template's reference.conf ships the switch required and binds MFA_MODE.
+		const mfaNames = (config: Switches) =>
+			buildModules(config)
+				.map((m) => m.name)
+				.filter((name) => /mfa/i.test(name));
+		const shipped = buildResolvedConfig("development");
+		expect(shipped.mfaMode).toBe("required");
+		expect(mfaNames(shipped)).toContain("mfa");
+		const off = buildResolvedConfig("development", { MFA_MODE: "off" });
+		expect(off.mfaMode).toBe("off");
+		expect(mfaNames(off)).toEqual([]);
+		const optional = buildResolvedConfig("development", { MFA_MODE: "optional" });
+		expect(optional.mfaMode).toBe("optional");
+		expect(mfaNames(optional)).toContain("mfa");
 	});
 
-	it("reference.conf default for rateLimit.failMode is 'closed'", () => {
+	it("core's reference.conf ships no rateLimit.failMode: it is the Redis limiter's own key", () => {
 		const config = buildResolvedConfig("development");
-		expect(config.rateLimit?.failMode).toBe("closed");
+		expect(config).not.toHaveProperty("rateLimit.failMode");
 	});
 
-	it("reference.conf default for client_credentials.enabled is false", () => {
-		// Template doesn't enable client_credentials. Reference default propagates.
+	it("template application.conf ships clientCredentials.enabled off", () => {
+		// The template writes every grant switch it reads before boot, so the
+		// value phase one reads is the one boot parses.
 		const config = buildResolvedConfig("development");
-		expect(grants(config).client_credentials?.enabled).toBe(false);
+		expect(grants(config).clientCredentials?.enabled).toBe(false);
 	});
 
 	it("reference.conf default for oauth.resourceIndicator.enabled is false", () => {
@@ -110,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", () => {
@@ -121,20 +155,17 @@ 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);
 	});
 
-	// #287 — the audit trail as the shipped artifact resolves it. The section is
-	// declared in core's schema for a load-bearing reason: `AppConfigSchema` is
-	// a plain `z.object` and strips what it does not declare, so an undeclared
-	// `audit` block would vanish between `parseFile` and `buildModules` and the
-	// sink selector would read `undefined` while the config sat in the file
-	// looking effective. These assertions run the real three-tier merge, so they
-	// fail if either layer stops carrying the key.
-	describe("#287: the audit sink as the shipped artifact resolves it", () => {
-		it("resolves audit.sink.type to the template's logger sink with nothing set", () => {
+	// The selection is the composition root's own, `adapters.auditSink`,
+	// which phase one reads over the template's own layers. These assertions
+	// run the real merge, so they fail if a layer stops carrying the key.
+	describe("the audit sink as the shipped artifact resolves it", () => {
+		it("resolves adapters.auditSink to the template's logger sink with nothing set", () => {
 			const config = buildResolvedConfig("production");
-			expect(config.audit?.sink.type).toBe("logger");
+			expect(config.adapters.auditSink).toBe("logger");
 		});
 
 		it("wires exactly one auditSink provider for that resolved config", () => {
@@ -144,41 +175,35 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		});
 
 		it("lets an operator select core's built-in console sink by env var", () => {
-			// The env-override line has to be repeated at the template layer or
-			// the literal `"logger"` shadows reference.conf's substitution — the
-			// same precedence rule the grant tests above pin.
-			const config = buildResolvedConfig("production", { AUDIT_SINK_TYPE: "console" });
-			expect(config.audit?.sink.type).toBe("console");
+			const config = buildResolvedConfig("production", { ADAPTERS_AUDIT_SINK: "console" });
+			expect(config.adapters.auditSink).toBe("console");
 		});
 
-		it("reference.conf's own default is a sink, not a drop", () => {
-			// A consumer that resolves against reference.conf alone still lands on
-			// a sink. #304's sink policy is stdout JSON, never "none", and the
-			// library layer has to hold that on its own — a composition root that
-			// forgets to override it must not thereby lose its audit trail.
-			const referenceOnly = validate(
-				parseFile(resolveLibraryReferenceConfPath(), { env: testEnv }),
-				AppConfigSchema,
+		it("the template's reference.conf alone selects a sink, not a drop", () => {
+			// A composition resolved against the template's reference alone
+			// still lands on a sink: an application.conf that forgets the
+			// selection must not thereby lose its audit trail.
+			const referenceOnly = parseFile(fileURLToPath(templateReference()), { env: {} });
+			expect(readAdapters(referenceOnly.toObject() as Record<string, unknown>, {}).auditSink).toBe(
+				"logger",
 			);
-			expect(referenceOnly.audit?.sink.type).toBe("console");
 		});
 	});
 
-	// #277 — this is the shape the umbrella E2E (o3co/auth) boots: the shipped
-	// application.conf, `DEPLOYMENT_MODE=multi`, and one shared ioredis socket.
-	// The assertions below are what keep that stack booting: a memory denylist
-	// under `multi` is refused by the replica-safety guard, and NO denylist is
-	// refused by the #277 guard, so the template has to land on "redis" without
-	// the deployment naming it.
-	describe("#277: access-token revocation as the shipped artifact resolves it", () => {
-		it("resolves accessTokenDenylist.adapter to redis with nothing set", () => {
+	// The shape the umbrella E2E (o3co/auth) boots: the shipped
+	// application.conf, `CORE_DEPLOYMENT_MODE=multi`, and one shared ioredis socket.
+	// A memory denylist under `multi` is refused by the replica-safety guard,
+	// and NO denylist by core's denylist boot guard, so the template has to
+	// land on "redis" without the deployment naming it.
+	describe("access-token revocation as the shipped artifact resolves it", () => {
+		it("resolves adapters.accessTokenDenylist to redis with nothing set", () => {
 			const config = buildResolvedConfig("production");
-			expect(config.accessTokenDenylist?.adapter).toBe("redis");
+			expect(config.adapters.accessTokenDenylist).toBe("redis");
 		});
 
 		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", () => {
@@ -189,35 +214,39 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 
 		it("leaves nothing replica-unsafe under the umbrella E2E's environment", async () => {
 			// The environment `o3co/auth`'s tests/docker-compose.yml sets. Under
-			// `DEPLOYMENT_MODE=multi` the replica-safety guard fails boot naming
-			// every in-memory shared store, so the denylist this change adds has to
-			// come out of that environment as the Redis one — from the template's
-			// own config, since the compose file names no denylist variable.
-			// Asked of each manifest, the way the guard does (#455), so a rename
-			// cannot quietly invalidate it and the template's own memory modules
-			// — which no name list in core covers — count too.
+			// `CORE_DEPLOYMENT_MODE=multi` the replica-safety guard fails boot naming
+			// every in-memory shared store, so the denylist has to come out as
+			// the Redis one from the template's own config: the compose file
+			// names no denylist variable. Asked of each manifest, as the guard
+			// does, so a rename cannot quietly invalidate it and the template's
+			// own memory modules count too.
 			const { replicaUnsafeReason } = await import("@o3co/auth-provider-core");
 			const config = buildResolvedConfig("production", {
-				USER_SESSION_STORES_ADAPTER: "redis",
-				RATE_LIMITER_ADAPTER: "redis",
-				OAUTH_CODE_ADAPTER: "redis",
-				// #456: the federation token store defaults to memory, and the
-				// memory module declares itself replica-unsafe (#455).
-				FEDERATION_TOKEN_STORE_TYPE: "redis",
+				ADAPTERS_USER_SESSION_STORES: "redis",
+				ADAPTERS_RATE_LIMITER: "redis",
+				ADAPTERS_CODE_REPOSITORY: "redis",
+				// The federation token store defaults to memory, and the memory
+				// module declares itself replica-unsafe.
+				ADAPTERS_FEDERATION_TOKEN_STORE: "redis",
 				REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
+				// The umbrella sets MFA off.
+				MFA_MODE: "off",
 			});
 			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();
 			}
 		});
 
 		it("lets a single-instance deployment opt down to memory by env var", () => {
 			const config = buildResolvedConfig("production", {
-				ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+				ADAPTERS_ACCESS_TOKEN_DENYLIST: "memory",
 			});
-			expect(config.accessTokenDenylist?.adapter).toBe("memory");
+			expect(config.adapters.accessTokenDenylist).toBe("memory");
 			const names = buildModules(config).map((m) => m.name);
 			expect(names).toContain("core-access-token-denylist-memory");
 		});
@@ -226,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");
 		});
 	});
 });