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

package/templates/standalone/src/__tests__/all-modules-composition.test.mts

@@ -16,31 +16,25 @@
 
 /**
  * Every module this template can turn on, booted together on one replica
- * through the real composition — the shipped HOCON, `buildModules`, core's
- * `createApp`, mounted as `app.mts` mounts it — and held to the contracts that
- * exist only when the modules meet: one discovery document that tells the
- * truth about every grant and endpoint, every module's route answering in the
- * same app, each module's body rules surviving its neighbours in either mount
- * order, and a store outage answered 503 and logged once.
- *
- * Each package's own suite boots that package alone or against stand-ins, and
- * the defects this file exists for were invisible there: a discovery document
- * made invalid by a neighbour's contribution, a disabled grant still
- * advertised, one module's prefix parser setting another's body limit, a
- * content-type rule that held in one mount order only. See
- * `all-modules-composition.fixture.mts` for what is real and what is
- * substituted, and `all-modules-composition.multi.test.mts` for the same
- * composition on Redis under `deployment.mode = "multi"`.
+ * through the real composition (the shipped HOCON, `buildModules`, core's
+ * `createApp`, mounted as `app.mts` mounts it), and held to the contracts that
+ * exist only when the modules meet, which no package's own suite can see: one
+ * discovery document that tells the truth about every grant and endpoint,
+ * every module's route answering in the same app, each module's body rules
+ * surviving its neighbours in either mount order, and a store outage answered
+ * 503 and logged once. The fixture file says what is real and what is
+ * substituted; `all-modules-composition.multi.test.mts` boots the same
+ * composition on Redis under `core.deployment.mode = "multi"`.
  *
  * `knownDefect` marks a contract the composition breaks today; its comment
  * names the defect. In the monorepo it is `it.fails`: the fix that mends the
  * defect turns the case red, and turns it into a plain `it`. An outage case
- * pins only the part of the #685 rule that is broken, and asserts the rest
+ * pins only the part of the outage rule that is broken, and asserts the rest
  * (`describeOutages` in the fixture).
  */
 
 import { readdirSync, readFileSync } from "node:fs";
-import type { AppConfig } from "@o3co/auth-provider-core";
+import { type AppConfig, federationsOf } from "@o3co/auth-provider-core";
 import type express from "express";
 import request from "supertest";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
@@ -112,31 +106,39 @@ async function boot(options: Parameters<typeof compose>[0] = {}): Promise<Compos
 const TEMPLATE_PACKAGES: Readonly<Record<string, string>> = {
 	"@o3co/auth-provider-core":
 		"jwksModule, the memory stores, the refresh-token family rotation and revocation",
-	"@o3co/auth-provider-federation-google": "googleFederationModule",
+	"@o3co/auth-provider-federation-google": "googleFederationTypeModule, the google type",
 	"@o3co/auth-provider-federation-grants": "federationGrantsModules",
-	"@o3co/auth-provider-federation-oidc": "oidcFederationModule, one per `oidc` section",
-	"@o3co/auth-provider-foundation": "the HTTP user repository adapter (no module)",
+	"@o3co/auth-provider-federation-oidc": "oidcFederationTypeModule, the oidc type",
+	"@o3co/auth-provider-foundation":
+		"the HTTP user repository adapter; foundationMfaFactorStoreModule under MFA_MODE with adapters.mfaFactorStore = store (tools/composition boots it)",
+	"@o3co/auth-provider-mfa":
+		"mfaModules (mfaTotpFactorModule, mfaRecoveryCodeFactorModule, mfaEmailFactorModule, mfaModule) and mfaResetModule, under MFA_MODE (mfa-switch.test.mts)",
 	"@o3co/auth-provider-oauth":
-		"oauthModule, oauthSessionModule, oauthAuthorizationModule, subjectRevocationServiceModule",
+		"oauthEndpointsModule, oauthSessionGrantModule, oauthAuthorizationGrantsModule, subjectRevocationServiceModule",
 	"@o3co/auth-provider-redis": "the Redis stores (all-modules-composition.multi.test.mts)",
-	"@o3co/auth-provider-session": "sessionModule, sessionStoreModuleFor",
+	"@o3co/auth-provider-session": "sessionModule, sessionStoreModule",
+	"@o3co/auth-provider-standard":
+		"standardSmtpMailSenderModule; standardDevelopmentMailSenderModule in development",
 };
 
 /**
  * Workspace packages the template does not depend on, so nothing here can
- * boot them. Each is a module a deployment adds to this manifest by hand —
+ * boot them. Each but the test kit, which has no module, is a module a
+ * deployment adds to this manifest by hand —
  * `modules.mts` provides the Redis clients their stores need for that reason
  * — and `tools/composition` in the monorepo boots each beside every module
  * here, through this file's fixture.
  */
 const NOT_IN_TEMPLATE: Readonly<Record<string, string>> = {
-	"@o3co/auth-provider-device-grant": "deviceGrantModule",
+	"@o3co/auth-provider-device-grant": "deviceAuthorizationGrantModule",
 	"@o3co/auth-provider-dpop": "dpopModule",
-	"@o3co/auth-provider-federation-apple": "appleFederationModule",
-	"@o3co/auth-provider-federation-github": "githubFederationModule",
+	"@o3co/auth-provider-federation-apple": "appleFederationTypeModule",
+	"@o3co/auth-provider-federation-github": "githubFederationTypeModule",
 	"@o3co/auth-provider-mtls": "mtlsModule",
 	"@o3co/auth-provider-oauth-token-exchange": "tokenExchangeModule",
-	"@o3co/auth-provider-webauthn": "webauthnModule",
+	"@o3co/auth-provider-test-kit": "no module: contract suites and fakes, for tests",
+	"@o3co/auth-provider-webauthn":
+		"webauthnModule, webauthnSessionSubjectModule, webauthnMfaFactorModule",
 };
 
 describe("what the all-modules composition covers", () => {
@@ -173,7 +175,7 @@ describe("what the all-modules composition covers", () => {
 
 /** What `buildModules` lists with every switch on, one replica, memory stores. */
 const ALL_ON_MODULES = [
-	"sessionStoreModule",
+	"session-store",
 	"federation-grant-background",
 	"federation-grants",
 	"oauth",
@@ -181,19 +183,21 @@ const ALL_ON_MODULES = [
 	"oauth-authorization",
 	"jwks",
 	"session",
-	"federation:google",
-	"standalone:google-federation-config",
-	"standalone:oidc-federation-config",
-	"federation:oidc:oidc",
-	"standalone:key-store",
+	"federation-google-type",
+	"federation-oidc",
+	"logging",
+	"http",
+	"key-store",
 	"test:repositories",
-	"standalone:audit-sink",
-	"standalone:in-memory-federation-token-store",
+	"audit-sink",
+	"standard-smtp-mail-sender",
+	"standalone-in-memory-federation-token-store",
 	"core-federation-grant-store-memory",
 	"core-federation-grant-intent-store-memory",
-	"standalone:in-memory-session-stores",
+	"standalone-in-memory-session-stores",
+	"core-session-lifecycle",
 	"core-rate-limiter-memory",
-	"standalone:in-memory-code-repository",
+	"standalone-in-memory-code-repository",
 	"core-access-token-denylist-memory",
 	"core-replay-seen-set-memory",
 	"core-consent-store-memory",
@@ -231,23 +235,28 @@ describe("every module the template can turn on boots together", () => {
 		);
 	});
 
-	it("registers every federation and every grant a module contributes", async () => {
+	it("registers a federation for every enabled entry of a type a module contributes, and every grant", async () => {
 		const { modules, handle, app } = await boot();
-		const federations = modules.flatMap((m) => contributionNames(m, "federations")).sort();
-		expect(federations).toEqual(["google", "oidc"]);
-		expect([...(handle.components.federationProviders?.keys() ?? [])].sort()).toEqual(federations);
-
-		const grants = modules.flatMap((m) => contributionNames(m, "grants")).sort();
+		const types = modules.flatMap((m) => contributionNames(m, "federationTypes")).sort();
+		expect(types).toEqual(["google", "oidc"]);
+		// The shipped entries are named after their types.
+		expect([...(handle.components.federationProviders?.keys() ?? [])].sort()).toEqual(types);
+
+		// What boot registered: a module's grant switched off by its section
+		// answers `null` and registers nothing.
+		const grants = [...(handle.components.grantHandlerResolver?.entries() ?? [])]
+			.map(([grantType]) => grantType)
+			.sort();
 		expect(grants).toEqual(ENABLED_GRANTS);
 		const discovery = await request(app).get("/.well-known/openid-configuration");
 		expect([...discovery.body.grant_types_supported].sort()).toEqual(grants);
 	});
 
 	it("hands the deployment's logger to every module that answers a request", async () => {
-		// `app.mts` fills the `logger` slot so that `LOG_LEVEL` and the JSON
+		// `app.mts` fills the `logger` slot so that `LOGGING_LEVEL` and the JSON
 		// envelope reach every module; boot hands a module only the slots its
 		// manifest names, so a route or grant module without `logger` writes
-		// its outage lines to nobody (the session grant did, answering 503).
+		// its outage lines to nobody.
 		const { modules } = await boot();
 		const answering = modules.filter(
 			(m) => contributionNames(m, "routes").length + contributionNames(m, "grants").length > 0,
@@ -325,10 +334,10 @@ describe("discovery", () => {
 	 * is gone from the document and from the app, and nothing else moves.
 	 */
 	const GRANT_SWITCHES: ReadonlyArray<readonly [grant: string, variable: string]> = [
-		["session", "OAUTH_GRANTS_SESSION_ENABLED"],
-		["authorization_code", "OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED"],
-		["refresh_token", "OAUTH_GRANTS_REFRESH_TOKEN_ENABLED"],
-		["client_credentials", "OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED"],
+		["session", "OAUTH_SESSION_ENABLED"],
+		["authorization_code", "OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED"],
+		["refresh_token", "OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED"],
+		["client_credentials", "OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED"],
 	];
 
 	it.each(GRANT_SWITCHES)(
@@ -336,7 +345,7 @@ describe("discovery", () => {
 		async (grant, variable) => {
 			const { app } = await boot({ env: { ...SINGLE_ENV, [variable]: "false" } });
 			const doc = (await request(app).get(DISCOVERY_PATHS[0])).body;
-			expectValidMetadata(doc);
+			expectValidMetadata(doc, { authorizationCode: grant !== "authorization_code" });
 			expect([...doc.grant_types_supported].sort()).toEqual(
 				ENABLED_GRANTS.filter((g) => g !== grant),
 			);
@@ -347,11 +356,17 @@ describe("discovery", () => {
 				.send({ grant_type: grant });
 			expect(res.status).toBe(400);
 			expect(res.body.error).toBe("unsupported_grant_type");
+			if (grant === "authorization_code") {
+				// No grant redeems a code, so none is issued: none is served.
+				expect((await request(app).get("/oauth/authorize")).status).toBe(404);
+			}
 		},
 	);
 
 	it("Client ID Metadata Documents off: the flag is gone and nothing else moves", async () => {
-		const { app } = await boot({ env: { ...SINGLE_ENV, OAUTH_CIMD_ENABLED: "false" } });
+		const { app } = await boot({
+			env: { ...SINGLE_ENV, OAUTH_CLIENT_ID_METADATA_DOCUMENTS_ENABLED: "false" },
+		});
 		const doc = (await request(app).get(DISCOVERY_PATHS[0])).body;
 		expectValidMetadata(doc);
 		expect(doc.client_id_metadata_document_supported).toBeUndefined();
@@ -367,7 +382,7 @@ describe("discovery", () => {
 		await on.handle.dispose();
 		current = undefined;
 
-		const { app } = await boot({ env: { ...SINGLE_ENV, CONSENT_STORE_ADAPTER: "none" } });
+		const { app } = await boot({ env: { ...SINGLE_ENV, ADAPTERS_CONSENT_STORE: "none" } });
 		const doc = (await request(app).get(DISCOVERY_PATHS[0])).body;
 		expectValidMetadata(doc);
 		expect(doc.client_id_metadata_document_supported).toBeUndefined();
@@ -376,7 +391,13 @@ describe("discovery", () => {
 
 	/** The grant connections dropped: they name the OIDC federation. */
 	const withoutConnections = (config: AppConfig): AppConfig =>
-		({ ...config, federationGrants: { ...config.federationGrants, connections: {} } }) as AppConfig;
+		({
+			...config,
+			"federation-grants": {
+				...(config["federation-grants"] as Record<string, unknown>),
+				connections: {},
+			},
+		}) as AppConfig;
 
 	const FEATURE_SWITCHES: ReadonlyArray<
 		readonly [
@@ -389,13 +410,13 @@ describe("discovery", () => {
 		["federation grants", "FEDERATION_GRANTS_ENABLED", "/oauth/federation-grants", undefined],
 		[
 			"the Google federation",
-			"FEDERATIONS_GOOGLE_ENABLED",
+			"CORE_FEDERATIONS_GOOGLE_ENABLED",
 			"/session/oauth/federation/google",
 			undefined,
 		],
 		[
 			"the OIDC federation",
-			"FEDERATIONS_OIDC_ENABLED",
+			"CORE_FEDERATIONS_OIDC_ENABLED",
 			"/session/oauth/federation/oidc",
 			withoutConnections,
 		],
@@ -421,7 +442,7 @@ describe("discovery", () => {
 
 	it("the OIDC federation off while a grant connection names it is refused at boot, naming both", async () => {
 		await expect(
-			compose({ env: { ...SINGLE_ENV, FEDERATIONS_OIDC_ENABLED: "false" } }),
+			compose({ env: { ...SINGLE_ENV, CORE_FEDERATIONS_OIDC_ENABLED: "false" } }),
 		).rejects.toSatisfy((err: unknown) => {
 			const e = err as { name?: string; cause?: { message?: string } };
 			return (
@@ -554,7 +575,7 @@ describe("every module's primary route answers in the one app", () => {
 
 	// KNOWN DEFECT (the template's federation config, with the session
 	// package's redirect policy): a federation enabled the way the template
-	// README documents — its `FEDERATIONS_OIDC_*` variables — boots, and every
+	// README documents — its `CORE_FEDERATIONS_OIDC_*` variables — boots, and every
 	// login through it then ends at the callback in `500 misconfiguration`
 	// "client URL not configured", after the user has signed in upstream.
 	// `clientUrl` has no environment form (`application.conf` ships it
@@ -565,9 +586,12 @@ describe("every module's primary route answers in the one app", () => {
 		"a federation enabled from the documented variables alone either refuses to boot or completes a login",
 		async () => {
 			const withoutLanding = (config: AppConfig): AppConfig => {
-				const federations = config.federations as Record<string, Record<string, unknown>>;
+				const federations = federationsOf(config) as Record<string, Record<string, unknown>>;
 				const { clientUrl: _dropped, ...oidc } = federations.oidc ?? {};
-				return { ...config, federations: { ...federations, oidc } } as unknown as AppConfig;
+				return {
+					...config,
+					core: { ...config.core, federations: { ...federations, oidc } },
+				} as unknown as AppConfig;
 			};
 			let composed: Composition;
 			try {
@@ -591,7 +615,7 @@ describe("every module's primary route answers in the one app", () => {
 		},
 	);
 
-	it("a federation grant is lodged, beside oauthModule under /oauth", async () => {
+	it("a federation grant is lodged, beside oauthEndpointsModule under /oauth", async () => {
 		const { app } = await boot();
 		const res = await lodgeGrant(app);
 		expect(res.status).toBe(201);
@@ -633,7 +657,7 @@ describe.each([AS_LISTED, REVERSED] satisfies ModuleOrder[])(
 		});
 
 		it.each(TRANSFERS)(
-			"federation grants keep their 16 KiB bound beneath oauthModule's /oauth, a body sent %s",
+			"federation grants keep their 16 KiB bound beneath oauthEndpointsModule's /oauth, a body sent %s",
 			async (_transfer, send) => {
 				for (const type of [JSON_TYPE, FORM_TYPE]) {
 					const body =
@@ -746,9 +770,10 @@ describe.each([AS_LISTED, REVERSED] satisfies ModuleOrder[])(
 );
 
 describe("a request body the OAuth endpoints do not parse", () => {
-	// KNOWN DEFECT (packages/oauth, `createOAuthRouter` in routes.mts): the
-	// token and introspection handlers read `req.body` without checking that a
-	// parser ran. A body that is neither a form nor JSON — or none at all —
+	// KNOWN DEFECT (packages/oauth, `routes/token.mts`,
+	// `routes/introspectCaller.mts` and `routes.mts`): the token and
+	// introspection handlers read `req.body` without checking that a parser
+	// ran. A body that is neither a form nor JSON — or none at all —
 	// leaves it undefined, the handler throws, and the terminal handler answers
 	// `500 server_error` and logs `unhandled_request_error` for the client's
 	// own mistake. `/oauth/revoke` checks, and answers 400.
@@ -804,6 +829,16 @@ const oidcCallback = async (app: express.Express, outage: Outage, c: Composition
 const VERIFIER_WARN =
 	"core's verifier (`verifyJwt`, `packages/core/src/jwt/verify.mts`) writes its own `jwt_verify_rejected` warn (`reason: \"revocation_unavailable\"`) beside the route's error line: two lines for one outage (the runbook's outage table documents both)";
 
+/** The CSRF token the session middleware set in `cookies`, for a request that mutates. */
+const csrfTokenOf = (cookies: readonly string[]): string => {
+	const cookie = cookies.find((c) => /^[^=]*\.csrf=/.test(c));
+	if (cookie === undefined) throw new Error("the login reissued no CSRF cookie");
+	return decodeURIComponent(cookie.slice(cookie.indexOf("=") + 1).split(";")[0] ?? "");
+};
+
+const ROLLBACK_CLOSE_LOGS =
+	"a login that fails after its record's open closes that record (`packages/session/src/establish-session.mts`), and the close's own work meets the same outage: core's session lifecycle (`packages/core/src/session-lifecycle/service.mts`) warns `session_close_item_failed` for the item and keeps the close pending for its sweep, a second line for one outage";
+
 const OUTAGES: readonly OutageCase[] = [
 	{
 		module: "oauth-authorization",
@@ -813,22 +848,6 @@ const OUTAGES: readonly OutageCase[] = [
 		answer: { status: 503, error: "temporarily_unavailable" },
 		event: "authorization_grant_store_unavailable",
 	},
-	{
-		module: "oauth-authorization",
-		slot: "sessionFamilyIndex",
-		surface: "the code exchange",
-		run: codeExchange,
-		answer: { status: 503, error: "temporarily_unavailable" },
-		event: "authorization_grant_store_unavailable",
-	},
-	{
-		module: "oauth-authorization",
-		slot: "sessionRPRegistry",
-		surface: "the code exchange",
-		run: codeExchange,
-		answer: { status: 503, error: "temporarily_unavailable" },
-		event: "authorization_grant_store_unavailable",
-	},
 	{
 		module: "oauth",
 		slot: "codeRepository",
@@ -906,6 +925,47 @@ const OUTAGES: readonly OutageCase[] = [
 		event: "userinfo_store_unavailable",
 		unrelatedWarns: ["jwt_verify_aud_skipped"],
 	},
+	{
+		module: "oauth",
+		slot: "sessionLifecycleStore",
+		surface: "/oauth/userinfo",
+		run: async (app, outage) => {
+			const { access_token } = await webTokens(app);
+			outage.down = true;
+			return request(app).get("/oauth/userinfo").set("Authorization", `Bearer ${access_token}`);
+		},
+		answer: { status: 503, error: "temporarily_unavailable" },
+		event: "userinfo_store_unavailable",
+		unrelatedWarns: ["jwt_verify_aud_skipped"],
+	},
+	{
+		module: "oauth",
+		slot: "sessionLifecycleStore",
+		surface: "POST /oauth/logout",
+		run: async (app, outage) => {
+			const { id_token } = await webTokens(app);
+			outage.down = true;
+			return request(app).post("/oauth/logout").type("form").send({ id_token_hint: id_token });
+		},
+		answer: { status: 503, error: "temporarily_unavailable" },
+		event: "logout_store_unavailable",
+		unrelatedWarns: ["jwt_verify_aud_skipped"],
+	},
+	{
+		module: "session",
+		slot: "sessionLifecycleStore",
+		surface: "POST /session/logout",
+		run: async (app, outage) => {
+			const { cookies } = await login(app);
+			outage.down = true;
+			return request(app)
+				.post("/session/logout")
+				.set("Cookie", cookies)
+				.set("x-csrf-token", csrfTokenOf(cookies));
+		},
+		answer: { status: 503, error: "temporarily_unavailable" },
+		event: "session_logout_store_unavailable",
+	},
 	{
 		module: "oauth-session",
 		slot: "userSessionStore",
@@ -918,7 +978,7 @@ const OUTAGES: readonly OutageCase[] = [
 				.send({ grant_type: "session", scope: "openid" });
 		},
 		answer: { status: 503, error: "temporarily_unavailable" },
-		event: "session_grant_store_unavailable",
+		event: "session_admission_unavailable",
 	},
 	{
 		module: "oauth (consent step)",
@@ -933,7 +993,7 @@ const OUTAGES: readonly OutageCase[] = [
 		event: "authorize_consent_store_unavailable",
 		defects: {
 			"store-field":
-				"packages/oauth `routes/authorize.mts`: `authorize_consent_store_unavailable` carries `clientId` and `err` but no `store` / `step` / `site` field",
+				"packages/oauth `routes/authorizeConsent.mts`: `authorize_consent_store_unavailable` carries `clientId` and `err` but no `store` / `step` / `site` field",
 		},
 	},
 	{
@@ -949,7 +1009,7 @@ const OUTAGES: readonly OutageCase[] = [
 		event: "authorize_pending_consent_store_unavailable",
 		defects: {
 			"store-field":
-				"packages/oauth `routes/authorize.mts`: `authorize_pending_consent_store_unavailable` carries `clientId` and `err` but no `store` / `step` / `site` field",
+				"packages/oauth `routes/authorizeConsent.mts`: `authorize_pending_consent_store_unavailable` carries `clientId` and `err` but no `store` / `step` / `site` field",
 		},
 	},
 	{
@@ -962,6 +1022,7 @@ const OUTAGES: readonly OutageCase[] = [
 		},
 		answer: { status: 503, error: "temporarily_unavailable" },
 		event: "login_store_unavailable",
+		defects: { "no-warn": ROLLBACK_CLOSE_LOGS },
 	},
 	{
 		module: "session",
@@ -1006,7 +1067,7 @@ const OUTAGES: readonly OutageCase[] = [
 			outage.down = true;
 			return (await login(app)).res;
 		},
-		// Intended (#296): the login is not denied for a best-effort index write,
+		// Intended: the login is not denied for a best-effort index write,
 		// and the missed write is logged at error because a token minted from
 		// this session keeps introspecting active after a credential change —
 		// the runbook pages on it.
@@ -1022,19 +1083,12 @@ const OUTAGES: readonly OutageCase[] = [
 		run: oidcCallback,
 		answer: { status: 503, error: "temporarily_unavailable" },
 		event: "federation_callback_store_unavailable",
-	},
-	{
-		module: "session",
-		slot: "sessionFederationIndex",
-		surface: "the OIDC federation callback",
-		run: oidcCallback,
-		answer: { status: 503, error: "temporarily_unavailable" },
-		event: "federation_callback_store_unavailable",
+		defects: { "no-warn": ROLLBACK_CLOSE_LOGS },
 	},
 	{
 		module: "core (rate-limit guard)",
 		slot: "rateLimiter",
-		surface: "/oauth/token (rateLimit.failMode = closed)",
+		surface: "/oauth/token (redis-rate-limiter.failMode = closed)",
 		run: async (app, outage) => {
 			outage.down = true;
 			return tokenRequest(app, M2M).send({ grant_type: "client_credentials", scope: "api.read" });
@@ -1094,7 +1148,7 @@ const OUTAGES: readonly OutageCase[] = [
 ];
 
 describeOutages(
-	"a store or repository outage answers 503 and is logged once, at error (#685)",
+	"a store or repository outage gets the answer its case pins, and is logged once, at error",
 	OUTAGES,
 	(outage) => compose({ outage }),
 );