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

package/templates/standalone/src/__tests__/mfa-routes-budget.test.mts

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The MFA routes' budget the template ships: every `/session/mfa` POST is
+ * limited under the prefix `mfa` by the wired limiter alone, and the
+ * template's own `reference.conf` gives both limiters `limits.mfa`, 60
+ * requests per 300 s. Followed through both configuration phases and
+ * `createApp` to the limiter each module builds, in every environment the
+ * template ships a file for.
+ */
+
+import { fileURLToPath } from "node:url";
+import {
+	createApp,
+	defineModule,
+	memoryRateLimiterModule,
+	type RateLimiter,
+} from "@o3co/auth-provider-core";
+import { redisRateLimiterModule } from "@o3co/auth-provider-redis";
+import { afterEach, describe, expect, it } from "vitest";
+import { readOwnLayers, readSwitches, resolveConfigPaths, resolveForBoot } from "../configPath.mjs";
+import { loggingModule } from "../modules.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/** The secrets `application.conf` substitutes: test-only values past the entropy floor. */
+const SECRETS = {
+	KEY_STORE_LOCAL_SECRET: "test-secret-mfa-routes-budget.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_STORE_SECRET: "test-session-secret-mfa-routes-budget.at-least-32-bytes.ok",
+	MFA_MODE: "off",
+};
+
+/** The windows, in seconds, the Redis limiter asked its client to count over. */
+const windows: number[] = [];
+
+/** The limiter a consumer of the slot is handed, as the MFA routes are. */
+let consumed: RateLimiter | undefined;
+const consumerModule = defineModule({
+	name: "test:rate-limiter-consumer",
+	requires: ["rateLimiter"] as const,
+	contributes: {
+		grantMiddleware: [
+			({ rateLimiter }) => {
+				consumed = rateLimiter;
+				return null;
+			},
+		],
+	},
+});
+
+const handles: { dispose(): Promise<void> }[] = [];
+afterEach(async () => {
+	await Promise.all(handles.splice(0).map((handle) => handle.dispose()));
+	consumed = undefined;
+	windows.splice(0);
+});
+
+/** The shipped configuration for `environment`, booted with the limiter `adapter` selects. */
+async function shippedLimiter(
+	environment: string,
+	adapter: "memory" | "redis",
+): Promise<RateLimiter> {
+	const env = { ...SECRETS, ADAPTERS_RATE_LIMITER: adapter };
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, environment);
+	const own = readOwnLayers([envConfPath, applicationConfPath], { env });
+	const switches = readSwitches(own);
+	expect(switches.adapters.rateLimiter).toBe(adapter);
+	const limiterModule = adapter === "redis" ? redisRateLimiterModule : memoryRateLimiterModule;
+	const modules = [limiterModule, consumerModule];
+	const handle = await createApp({
+		modules,
+		bootstrapComponents: {
+			config: resolveForBoot(own, [...modules, loggingModule], switches),
+			pathResolver: (s: string) => s,
+			// Counts one request per key, the way an untouched Redis counter would.
+			rateLimiterClient: {
+				incrementWithTtl: async (_key: string, windowSeconds: number) => {
+					windows.push(windowSeconds);
+					return 1;
+				},
+			} as never,
+		},
+	});
+	handles.push(handle);
+	if (consumed === undefined) throw new Error("the boot handed no consumer the limiter");
+	return consumed;
+}
+
+describe("the MFA routes' budget the template ships", () => {
+	it.each([
+		["development", "memory"],
+		["development", "redis"],
+		["production", "memory"],
+		["production", "redis"],
+	] as const)("is 60 per 300 s under %s on the %s limiter", async (environment, adapter) => {
+		const limiter = await shippedLimiter(environment, adapter);
+		const before = Date.now();
+		const decision = await limiter.check("mfa:ip:203.0.113.7", { ip: "203.0.113.7" });
+		expect(decision.allowed).toBe(true);
+		expect(decision.limit).toBe(60);
+		const windowSeconds =
+			adapter === "redis"
+				? windows[0]
+				: Math.round(((decision.resetAt?.getTime() ?? 0) - before) / 1000);
+		expect(windowSeconds).toBe(300);
+	});
+});

package/templates/standalone/src/__tests__/mfa-switch.test.mts

@@ -46,7 +46,13 @@ import { loginCompletionModule } from "@o3co/auth-provider-session";
 import request from "supertest";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildModules } from "#/buildModules.mjs";
-import { readOwnLayers, readSwitches, resolveConfigPaths, resolveForBoot } from "#/configPath.mjs";
+import {
+	configDefaultsFor,
+	readOwnLayers,
+	readSwitches,
+	resolveConfigPaths,
+	resolveForBoot,
+} from "#/configPath.mjs";
 import {
 	ALICE,
 	authorize,
@@ -143,13 +149,20 @@ describe("the switch is the template's own key, mfaMode, bound to MFA_MODE", ()
 		}
 	});
 
-	it("refuses an MFA_MODE that is none of the three before boot, a RangeError naming mfaMode and MFA_MODE that quotes nothing of it", async () => {
+	it("refuses an MFA_MODE that is none of the three before boot, a config-validation-failed BootError naming mfaMode and MFA_MODE that quotes nothing of it", async () => {
 		const err = await refusal(boot({ env: on("required", { MFA_MODE: "sentinel-mode" }) }));
-		expect(err).toBeInstanceOf(RangeError);
-		expect(err).not.toBeInstanceOf(BootError);
-		expect((err as RangeError).message).toContain("mfaMode");
-		expect((err as RangeError).message).toContain("MFA_MODE");
-		expect((err as RangeError).message).not.toContain("sentinel-mode");
+		expect(err).toBeInstanceOf(BootError);
+		expect(err).toMatchObject({
+			reason: "config-validation-failed",
+			details: {
+				issues: [{ path: ["mfaMode"] }],
+				modules: [{ module: "mfaMode", schemaPath: "mfaMode" }],
+			},
+		});
+		expect((err as BootError).message).toContain("mfaMode");
+		expect((err as BootError).message).toContain("MFA_MODE");
+		expect((err as BootError).message).not.toContain("sentinel-mode");
+		expect(JSON.stringify((err as BootError).details)).not.toContain("sentinel-mode");
 	});
 
 	it.each([
@@ -165,12 +178,16 @@ describe("the switch is the template's own key, mfaMode, bound to MFA_MODE", ()
 					operatorHocon: `mfaMode = "${written}"\n`,
 				}),
 			);
-			expect(err).toBeInstanceOf(RangeError);
-			expect(err).not.toBeInstanceOf(BootError);
-			const message = (err as RangeError).message;
+			expect(err).toBeInstanceOf(BootError);
+			expect(err).toMatchObject({
+				reason: "config-validation-failed",
+				details: { issues: [{ code: "custom", path: ["mfaMode"] }] },
+			});
+			const message = (err as BootError).message;
 			expect(message).toContain("mfaMode");
 			expect(message).toContain("MFA_MODE");
 			expect(message).not.toMatch(/"(?:off|optional|required)"/);
+			expect(JSON.stringify((err as BootError).details)).not.toMatch(/(?:off|optional|required)"/);
 		},
 	);
 
@@ -332,8 +349,18 @@ describe("the MFA stores in memory: development and test alone", () => {
 
 	it("refuses both, before boot, under the name production: the shipped selection, naming each setting and its variable", async () => {
 		const err = await refusal(compose({ env: on("required"), environment: "production" }));
-		expect(err).toBeInstanceOf(RangeError);
-		const message = (err as RangeError).message;
+		expect(err).toBeInstanceOf(BootError);
+		expect(err).toMatchObject({
+			reason: "config-validation-failed",
+			details: {
+				issues: [
+					{ code: "custom", path: ["adapters", "mfaFactorStore"] },
+					{ code: "custom", path: ["adapters", "mfaTransactionStore"] },
+				],
+				modules: [{ module: "adapters", schemaPath: "adapters" }],
+			},
+		});
+		const message = (err as BootError).message;
 		for (const named of [
 			"adapters.mfaFactorStore",
 			"ADAPTERS_MFA_FACTOR_STORE",
@@ -351,9 +378,12 @@ describe("the MFA stores in memory: development and test alone", () => {
 				environment: "production",
 			}),
 		);
-		expect(err).toBeInstanceOf(RangeError);
-		expect((err as RangeError).message).toContain("ADAPTERS_MFA_TRANSACTION_STORE");
-		expect((err as RangeError).message).not.toContain("ADAPTERS_MFA_FACTOR_STORE");
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).details).toMatchObject({
+			issues: [{ path: ["adapters", "mfaTransactionStore"] }],
+		});
+		expect((err as BootError).message).toContain("ADAPTERS_MFA_TRANSACTION_STORE");
+		expect((err as BootError).message).not.toContain("ADAPTERS_MFA_FACTOR_STORE");
 	});
 
 	it.each(["CONFIG_ENV", "NODE_ENV"])(
@@ -361,14 +391,15 @@ describe("the MFA stores in memory: development and test alone", () => {
 		async (variable) => {
 			vi.stubEnv(variable, "production");
 			const err = await refusal(boot({ env: on("required") }));
-			expect(err).toBeInstanceOf(RangeError);
-			expect((err as RangeError).message).toContain("ADAPTERS_MFA_FACTOR_STORE");
+			expect(err).toBeInstanceOf(BootError);
+			expect((err as BootError).message).toContain("ADAPTERS_MFA_FACTOR_STORE");
 		},
 	);
 
 	it("refuses them under a name that is neither development nor test", async () => {
 		const err = await refusal(compose({ env: on("required"), environment: "staging-eu" }));
-		expect(err).toBeInstanceOf(RangeError);
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).reason).toBe("config-validation-failed");
 	});
 
 	it.each(["development", "test"])("lets them in under %s", async (environment) => {
@@ -533,8 +564,15 @@ describe("mfa.storeTimeoutMs", () => {
 		const err = await refusal(
 			boot({ env: on("optional", { ...IN_THE_STORE, REPOSITORIES_USER_HTTP_TIMEOUT: "8000" }) }),
 		);
-		expect(err).toBeInstanceOf(RangeError);
-		const message = (err as RangeError).message;
+		expect(err).toBeInstanceOf(BootError);
+		expect(err).toMatchObject({
+			reason: "config-validation-failed",
+			details: {
+				issues: [{ code: "custom", path: ["mfa", "storeTimeoutMs"] }],
+				modules: [{ module: "mfa", schemaPath: "mfa" }],
+			},
+		});
+		const message = (err as BootError).message;
 		for (const named of [
 			"mfa.storeTimeoutMs",
 			"MFA_STORE_TIMEOUT_MS",
@@ -619,7 +657,6 @@ async function bootShipped(
 	const modules = adjustModules(
 		buildModules(switches, {
 			environment,
-			logger,
 			refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
 		}),
 	);
@@ -627,6 +664,7 @@ async function bootShipped(
 		modules,
 		bootstrapComponents: {
 			config: resolveForBoot(own, modules, switches),
+			configDefaults: configDefaultsFor(modules),
 			pathResolver: (s: string) => s,
 			logger,
 		},
@@ -713,8 +751,8 @@ describe("the shipped configuration with nothing set about MFA", () => {
 		await bootShipped(unset(SHIPPED_ENV), "production").catch((caught: unknown) => {
 			err = caught;
 		});
-		expect(err).toBeInstanceOf(RangeError);
-		const message = (err as RangeError).message;
+		expect(err).toBeInstanceOf(BootError);
+		const message = (err as BootError).message;
 		for (const named of [
 			"ADAPTERS_MFA_FACTOR_STORE",
 			"ADAPTERS_MFA_TRANSACTION_STORE",
@@ -750,8 +788,15 @@ describe("under CONFIG_ENV=development", () => {
 				err = caught;
 			},
 		);
-		expect(err).toBeInstanceOf(RangeError);
-		const message = (err as RangeError).message;
+		expect(err).toBeInstanceOf(BootError);
+		expect(err).toMatchObject({
+			reason: "config-validation-failed",
+			details: { issues: [{ code: "custom", path: ["mfa", "encryptionKeys"] }] },
+		});
+		const details = JSON.stringify((err as BootError).details);
+		expect(details).not.toContain(MFA_KEY);
+		expect(details).not.toContain(MFA_DEVELOPMENT_SAMPLE_KEY);
+		const message = (err as BootError).message;
 		expect(message).toContain("MFA_ENCRYPTION_KEY");
 		expect(message).toContain("mfa.encryptionKeys");
 		expect(message).not.toContain(MFA_KEY);

package/templates/standalone/src/__tests__/own-modules.test.mts

@@ -61,7 +61,6 @@ import {
 	readSwitches,
 	resolveConfigPaths,
 	resolveForBoot,
-	SWITCHES,
 } from "../configPath.mjs";
 import { createAppLogger } from "../logger.mjs";
 import { MFA_SWITCH } from "../mfaSwitch.mjs";
@@ -215,19 +214,26 @@ const REFERENCED_MODULES = [
 	auditSinkModuleFor("logger"),
 ];
 
+/** The rate limiters' sections, in which the template's reference gives the MFA routes' budget. */
+const LIMITER_SECTIONS = ["core-rate-limiter-memory", "redis-rate-limiter"] as const;
+
 describe("the template's config/reference.conf", () => {
-	it("holds only its own modules' sections and the composition root's adapters and mfaMode, each module's parsing its part without losing a path", () => {
+	it("holds only its own modules' sections, the composition root's adapters and mfaMode, and the limiters' MFA budget, each module's parsing its part without losing a path", () => {
 		expect(
 			packageReferenceProblems({
 				reference: TEMPLATE_REFERENCE,
 				modules: REFERENCED_MODULES,
 				// `adapters` and `mfaMode` are the composition root's own,
 				// which phase one reads with its own schema
-				// (`adapters.test.mts`, `mfa-switch.test.mts`).
+				// (`adapters.test.mts`, `mfa-switch.test.mts`); the limiters'
+				// sections hold the MFA budget alone (below), each parsed by its
+				// own module where it is loaded (`mfa-routes-budget.test.mts`).
 				read: (path, env) => {
 					const {
 						[ADAPTERS_SECTION]: _adapters,
 						[MFA_SWITCH]: _mfaMode,
+						[LIMITER_SECTIONS[0]]: _memoryLimiter,
+						[LIMITER_SECTIONS[1]]: _redisLimiter,
 						...tree
 					} = parseFile(path, {
 						env: { ...env },
@@ -238,6 +244,14 @@ describe("the template's config/reference.conf", () => {
 		).toEqual([]);
 	});
 
+	it.each(LIMITER_SECTIONS)("gives %s the MFA routes' budget, and nothing else", (section) => {
+		const tree = parseFile(fileURLToPath(TEMPLATE_REFERENCE), { env: {} }).toObject() as Record<
+			string,
+			unknown
+		>;
+		expect(tree[section]).toEqual({ limits: { mfa: { limit: 60, windowSeconds: 300 } } });
+	});
+
 	it.each(REFERENCED_MODULES)("is among the references $name alone brings", (module) => {
 		expect(moduleReferences([module]).map((url) => url.href)).toContain(TEMPLATE_REFERENCE.href);
 	});
@@ -246,7 +260,7 @@ describe("the template's config/reference.conf", () => {
 describe("logging", () => {
 	it("owns logging, and requires nothing", () => {
 		expect(loggingModule.name).toBe("logging");
-		expect(loggingModule.section?.at).toBeUndefined();
+		expect(loggingModule.section).not.toHaveProperty("at");
 		expect(loggingModule.section?.reference?.href).toBe(TEMPLATE_REFERENCE.href);
 		expect(loggingModule.requires ?? []).toEqual([]);
 		expect(loggingModule.optional ?? []).toEqual([]);
@@ -265,8 +279,9 @@ describe("logging", () => {
 		});
 	});
 
-	it("is not among SWITCHES", () => {
-		expect(SWITCHES).not.toContain("logging");
+	it("is not among what phase one reads", () => {
+		const own = readOwnLayers(ownFiles(), { env: BASE_ENV });
+		expect(Object.keys(readSwitches(own))).not.toContain("logging");
 	});
 
 	it.each([
@@ -284,6 +299,20 @@ describe("logging", () => {
 	it("refuses a level it does not know before boot, naming logging.level", () => {
 		const own = readOwnLayers(ownFiles(), { env: { ...BASE_ENV, LOGGING_LEVEL: "verbose" } });
 		expect(() => readLogging(own)).toThrow(/logging\.level/);
+		expect(() => readLogging(own)).toThrow(BootError);
+		let err: unknown;
+		try {
+			readLogging(own);
+		} catch (caught) {
+			err = caught;
+		}
+		expect(err).toMatchObject({
+			reason: "config-validation-failed",
+			details: {
+				issues: [{ path: ["logging", "level"] }],
+				modules: [{ module: "logging", schemaPath: "logging" }],
+			},
+		});
 	});
 
 	it("has boot refuse LOG_LEVEL set alone, naming LOGGING_LEVEL and logging.level", async () => {
@@ -338,7 +367,7 @@ const preflight = (app: express.Express, origin: string) =>
 describe("http", () => {
 	it("owns http, the CORS list included, and requires nothing", () => {
 		expect(httpModule.name).toBe("http");
-		expect(httpModule.section?.at).toBeUndefined();
+		expect(httpModule.section).not.toHaveProperty("at");
 		expect(httpModule.section?.reference?.href).toBe(TEMPLATE_REFERENCE.href);
 		expect(httpModule.requires ?? []).toEqual([]);
 		expect(httpModule.optional ?? []).toEqual([]);
@@ -753,7 +782,7 @@ describe("an environment variable takes effect though application.conf does not
 describe("key-store", () => {
 	it("owns key-store, and reads it as its section rather than the configuration", () => {
 		expect(keyStoreModule.name).toBe("key-store");
-		expect(keyStoreModule.section?.at).toBeUndefined();
+		expect(keyStoreModule.section).not.toHaveProperty("at");
 		expect(keyStoreModule.section?.reference?.href).toBe(TEMPLATE_REFERENCE.href);
 		expect(keyStoreModule.requires ?? []).not.toContain("config");
 		expect(keyStoreModule.optional ?? []).not.toContain("config");
@@ -970,7 +999,7 @@ async function listeningRedis(): Promise<{
 describe("redis-clients", () => {
 	it("owns redis-clients, and reads it as its section rather than the configuration", () => {
 		expect(standaloneRedisClientsModule.name).toBe("redis-clients");
-		expect(standaloneRedisClientsModule.section?.at).toBeUndefined();
+		expect(standaloneRedisClientsModule.section).not.toHaveProperty("at");
 		expect(standaloneRedisClientsModule.section?.reference?.href).toBe(TEMPLATE_REFERENCE.href);
 		expect(standaloneRedisClientsModule.requires ?? []).not.toContain("config");
 		expect(standaloneRedisClientsModule.optional ?? []).not.toContain("config");
@@ -1141,7 +1170,7 @@ describe("repositories", () => {
 		const own = readOwnLayers(ownFiles(), { env: BASE_ENV });
 		const modules = buildModules(readSwitches(own), { environment: "development" });
 		const repositories = named(modules, "repositories");
-		expect(repositories.section?.at).toBeUndefined();
+		expect(repositories.section).not.toHaveProperty("at");
 		expect(repositories.section?.reference?.href).toBe(TEMPLATE_REFERENCE.href);
 		expect(repositories.requires ?? []).not.toContain("config");
 		expect(repositories.optional ?? []).not.toContain("config");
@@ -1434,7 +1463,7 @@ describe("audit-sink", () => {
 			buildModules(readSwitches(own), { environment: "development" }),
 			"audit-sink",
 		);
-		expect(sink.section?.at).toBeUndefined();
+		expect(sink.section).not.toHaveProperty("at");
 		expect(sink.requires ?? []).not.toContain("config");
 	});
 

package/templates/standalone/src/__tests__/post-logout-redirect.test.mts

@@ -149,15 +149,15 @@ describe("a logout's post_logout_redirect_uri reaches the upstream only once it
 
 	describe("POST /oauth/federation/google/logout", () => {
 		it("does not send the browser to an unregistered post_logout_redirect_uri", async () => {
-			const { app, sid, accessToken, sessionFederationIndex } = await signedInWithGoogle("shipped");
+			const { app, sid, accessToken, federationTokenStore } = await signedInWithGoogle("shipped");
 
 			const res = await federationLogout(app, accessToken, UNREGISTERED);
 
 			expect(res.status).toBe(303);
 			expect(new URL(res.headers.location as string).origin).not.toBe("https://evil.example");
 			expect(res.headers.location).toBe(`${GOOGLE_LOGOUT}?state=s-1`);
-			// The federation was disconnected all the same.
-			expect(await sessionFederationIndex.listFederations(sid)).not.toContain("google");
+			// The federation was disconnected all the same: its tokens are gone.
+			expect(await federationTokenStore.get(sid, "google")).toBeNull();
 		});
 
 		it("still returns the browser to one registered for the token's client", async () => {

package/templates/standalone/src/__tests__/redis-rate-limiter-config-survives.test.mts

@@ -156,15 +156,21 @@ describe("the shipped configuration reaches the Redis rate limiter", () => {
 		expect(booted.switches.adapters.rateLimiter).toBe("redis");
 	});
 
-	it("carries the operator's per-endpoint budgets through boot's parse", () => {
+	it("carries the operator's per-endpoint budgets through boot's parse, merged with the template's", () => {
 		expect(
 			(config as unknown as Record<string, { limits?: unknown }>)["redis-rate-limiter"]?.limits,
 		).toEqual({
 			token: { limit: 120, windowSeconds: 60 },
 			authorize: { limit: 30, windowSeconds: 60 },
+			mfa: { limit: 60, windowSeconds: 300 },
 		});
 	});
 
+	it("keeps the MFA routes' budget the template ships beside the operator's", async () => {
+		const decision = await limiter.check("mfa:ip:203.0.113.5", { ip: "203.0.113.5" });
+		expect(decision.limit).toBe(60);
+	});
+
 	it("applies the declared budget at /token", async () => {
 		const decision = await limiter.check("token:ip:203.0.113.5", { ip: "203.0.113.5" });
 		expect(decision.limit).toBe(120);
@@ -183,9 +189,7 @@ describe("the shipped configuration reaches the Redis rate limiter", () => {
 		expect(decision.limit).toBe(60);
 	});
 
-	it("applies no login budget without the session module: session.rateLimit.login is that module's to contribute", async () => {
-		// This boot loads the limiter alone. With the session module, the
-		// limiter applies the budget it contributes from session.rateLimit.login.
+	it("applies no login budget: session.rateLimit.login is the session module's own attempt limit, which no limiter applies", async () => {
 		expect(config.session).toMatchObject({ rateLimit: { login: { limit: 20 } } });
 		const decision = await limiter.check("login:ip:203.0.113.5", { ip: "203.0.113.5" });
 		expect(decision.limit).toBe(60);