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

package/templates/standalone/src/__tests__/google-session.fixture.mts

@@ -16,8 +16,10 @@
 
 /**
  * A browser session with Google linked, on the standalone composed as a
- * deployment does: `oauthModule`, the session module and the real Google
- * adapter, booted through `createApp` under the shipped configuration.
+ * deployment does: `oauthEndpointsModule`, the session module and the real Google
+ * adapter — the Google federation type `buildModules` lists, handed the
+ * shipped `core.federations.google` entry — booted through `createApp` under
+ * the shipped configuration.
  *
  * The two logout routes and `POST /oauth/federation/:name/token` live in
  * `@o3co/auth-provider-oauth`, which depends on no adapter; only here can a
@@ -32,7 +34,6 @@
 import { createHmac } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import {
-	AppConfigSchema,
 	createApp,
 	createKeyStoreFactory,
 	defineModule,
@@ -42,26 +43,22 @@ import {
 	InMemoryUserRepository,
 	memoryRefreshTokenFamilyStoreModule,
 	registerBuiltinKeyStores,
-	type SessionFederationIndex,
+	type SessionLifecycle,
 	type UserSessionStore,
 } from "@o3co/auth-provider-core";
-import {
-	type GoogleProviderConfig,
-	googleFederationModule,
-} from "@o3co/auth-provider-federation-google";
+import { googleFederationTypeModule } from "@o3co/auth-provider-federation-google";
 import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
 import express from "express";
 import request from "supertest";
 import { expect } from "vitest";
 import { buildModules } from "#/buildModules.mjs";
-import { resolveConfigPaths, type Switches } from "#/configPath.mjs";
+import { resolveConfigPaths } from "#/configPath.mjs";
 import { templateReference } from "../modules.mjs";
 import {
+	type BothPhases,
+	bothPhasesOf,
 	capturedRenames,
 	libraryLayers,
-	rootSectionsOf,
-	sectionsCoreDoesNotDeclare,
 } from "./library-references.fixture.mjs";
 
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
@@ -106,40 +103,50 @@ const ENV: Readonly<Record<string, string>> = {
 };
 
 /**
- * `"shipped"`: Google switched on the way an operator does, through its
- * environment variables and the template's own configuration bridge — which
- * has no setting for an end-session endpoint or a `fetch`. Otherwise the
- * adapter's configuration beyond its credentials, composed with
- * `googleFederationModule` directly.
+ * Google switched on the way an operator does, through its environment
+ * variables, and handled by the Google federation type the template lists.
+ * `"shipped"` is that alone. Otherwise, beside it: `endSessionEndpoint`, a key
+ * of the entry with no environment form, written into the entry as an
+ * operator's own layer would; and `fetch`, the one the type module is built
+ * with in place of the global one.
  */
 export type GoogleWiring =
 	| "shipped"
-	| Omit<GoogleProviderConfig, "clientId" | "clientSecret" | "callbackURL">;
+	| { readonly endSessionEndpoint?: string; readonly fetch?: typeof fetch };
+
+const GOOGLE_ENV: Readonly<Record<string, string>> = {
+	CORE_FEDERATIONS_GOOGLE_ENABLED: "true",
+	CORE_FEDERATIONS_GOOGLE_CLIENT_ID: GOOGLE_CLIENT_ID,
+	CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET: GOOGLE_CLIENT_SECRET,
+	CORE_FEDERATIONS_GOOGLE_CALLBACK_URL: GOOGLE_CALLBACK,
+};
 
-function resolveConfig(google: GoogleWiring): Switches {
-	const env: Record<string, string> =
-		google === "shipped"
-			? {
-					...ENV,
-					CORE_FEDERATIONS_GOOGLE_ENABLED: "true",
-					CORE_FEDERATIONS_GOOGLE_CLIENT_ID: GOOGLE_CLIENT_ID,
-					CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET: GOOGLE_CLIENT_SECRET,
-					CORE_FEDERATIONS_GOOGLE_CALLBACK_URL: GOOGLE_CALLBACK,
-				}
-			: { ...ENV };
+function resolveConfig(google: GoogleWiring): BothPhases {
+	const env: Record<string, string> = { ...ENV, ...GOOGLE_ENV };
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
 	const layers = parseFile(envConfPath, { env })
 		.withFallback(parseFile(applicationConfPath, { env }))
 		.withFallback(parseFile(fileURLToPath(templateReference()), { env }))
 		.withFallback(libraryLayers(env));
+	const config = bothPhasesOf(layers, env);
+	const endSessionEndpoint = google === "shipped" ? undefined : google.endSessionEndpoint;
+	const federations = config.core?.federations;
 	return {
-		...sectionsCoreDoesNotDeclare(layers),
-		...rootSectionsOf(layers, env),
-		...validate(layers, AppConfigSchema),
-		// What the resolution captured of core's renamed variables, which the
-		// schema's parse drops.
+		...config,
+		...(endSessionEndpoint === undefined
+			? {}
+			: {
+					core: {
+						...config.core,
+						federations: {
+							...federations,
+							google: { ...federations?.google, endSessionEndpoint },
+						},
+					},
+				}),
+		// What the resolution captured of the renamed variables.
 		"renamed-variables": capturedRenames(env),
-	} as Switches;
+	} as BothPhases;
 }
 
 const testRepositoriesModule = defineModule({
@@ -227,15 +234,15 @@ export interface GoogleSession {
 	/** The access token the `session` grant minted for the session; it carries `azp`. */
 	readonly accessToken: string;
 	readonly userSessionStore: UserSessionStore;
-	readonly sessionFederationIndex: SessionFederationIndex;
+	readonly sessionLifecycle: SessionLifecycle;
 	readonly federationTokenStore: FederationTokenStore;
 	readonly dispose: () => Promise<void>;
 }
 
 /**
  * Boots the deployment, signs alice in with her password, and links Google to
- * her session as a federated sign-in would: the session's federation index
- * names it and the token store holds `tokens`.
+ * her session as a federated sign-in would: the token store holds `tokens`,
+ * and Google joins the session through its lifecycle.
  */
 export async function signInLinkedToGoogle(options: {
 	readonly google: GoogleWiring;
@@ -243,38 +250,24 @@ export async function signInLinkedToGoogle(options: {
 }): Promise<GoogleSession> {
 	const { google, tokens } = options;
 	const config = resolveConfig(google);
-	const googleModules =
-		google === "shipped"
-			? []
-			: [
-					googleFederationModule,
-					defineModule({
-						name: "test:google-federation-config",
-						provides: {
-							googleFederationConfig: (): GoogleProviderConfig => ({
-								clientId: GOOGLE_CLIENT_ID,
-								clientSecret: GOOGLE_CLIENT_SECRET,
-								callbackURL: GOOGLE_CALLBACK,
-								...google,
-							}),
-						},
-					}),
-				];
+	const upstreamFetch = google === "shipped" ? undefined : google.fetch;
+	const googleType = googleFederationTypeModule().name;
 	const handle = await createApp({
-		modules: [
-			...buildModules(config, {
-				keyStoreModule: testKeyStoreModule,
-				repositoriesModule: testRepositoriesModule,
-				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
-			}),
-			...googleModules,
-		],
+		modules: buildModules(config, {
+			keyStoreModule: testKeyStoreModule,
+			repositoriesModule: testRepositoriesModule,
+			refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+		}).map((module) =>
+			module.name === googleType && upstreamFetch !== undefined
+				? googleFederationTypeModule({ fetch: upstreamFetch })
+				: module,
+		),
 		bootstrapComponents: { config, pathResolver: (s) => s },
 	});
 	try {
 		const components = handle.components as {
 			userSessionStore: UserSessionStore;
-			sessionFederationIndex: SessionFederationIndex;
+			sessionLifecycle: SessionLifecycle;
 			federationTokenStore: FederationTokenStore;
 		};
 		const app = express();
@@ -303,10 +296,10 @@ export async function signInLinkedToGoogle(options: {
 		const sid = claims.sid as string;
 		expect(typeof sid).toBe("string");
 
-		const session = await components.userSessionStore.get(sid);
-		if (session === null) throw new Error("fixture: the sign-in left no session");
-		await components.sessionFederationIndex.addFederation(sid, "google", session.expiresAt);
 		await components.federationTokenStore.attach(sid, "google", tokens);
+		expect(await components.sessionLifecycle.join(sid, { federation: "google" })).toEqual({
+			outcome: "joined",
+		});
 		return { app, sid, accessToken, ...components, dispose: () => handle.dispose() };
 	} catch (error) {
 		await handle.dispose();

package/templates/standalone/src/__tests__/library-reference-resolution.smoke.test.mts

@@ -24,6 +24,6 @@ describe("library reference.conf subpath resolution", () => {
 		const path = fileURLToPath(url);
 		expect(existsSync(path)).toBe(true);
 		const content = readFileSync(path, "utf-8");
-		expect(content).toMatch(/oauth\s*\{/); // sanity: HOCON content
+		expect(content).toMatch(/^core\s*\{/m); // sanity: HOCON content, core's own section
 	});
 });

package/templates/standalone/src/__tests__/library-references.fixture.mts

@@ -18,21 +18,22 @@
  * The libraries' layers beneath the template's own files, for a test that
  * resolves its configuration by hand: the `reference.conf` of every package
  * the template composes a module from, core's last, as `app.mts` layers them;
- * and what that resolution captures of the renamed variables.
+ * the resolution handed to both phases at once; and what that resolution
+ * captures of the renamed variables.
  */
 
 import { fileURLToPath } from "node:url";
 import {
-	AppConfigSchema,
+	type AppConfig,
 	memoryRateLimiterModule,
 	moduleReferences,
 } from "@o3co/auth-provider-core";
 import { CORE_RELOCATIONS, renamedVariableCaptures } from "@o3co/auth-provider-core/testing";
 import { federationGrantsModules } from "@o3co/auth-provider-federation-grants";
 import {
-	oauthAuthorizationModule,
-	oauthModule,
-	oauthSessionModule,
+	oauthAuthorizationGrantsModule,
+	oauthEndpointsModule,
+	oauthSessionGrantModule,
 } from "@o3co/auth-provider-oauth";
 import {
 	redisCodeRepositoryModule,
@@ -42,8 +43,8 @@ import {
 } from "@o3co/auth-provider-redis";
 import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
 import { type Config, empty, parseFile } from "@o3co/ts.hocon";
-import { ADAPTERS_SECTION, readAdapters } from "../adapters.mjs";
-import { MFA_SWITCH, readMfaSwitch } from "../mfaSwitch.mjs";
+import { readAdapters } from "../adapters.mjs";
+import { readSwitches, type Switches } from "../configPath.mjs";
 import {
 	httpModule,
 	inMemoryCodeRepositoryModule,
@@ -53,13 +54,13 @@ import {
 	standaloneRedisClientsModule,
 	templateReference,
 } from "../modules.mjs";
-import type { Adapters, MfaSwitch } from "../sections.mjs";
+import { type Adapters, isPlainSection } from "../sections.mjs";
 
-/** The oauth package's modules, whose manifests read nothing of the configuration they are handed but the grant switches. */
+/** The oauth package's modules: none reads the configuration it is handed. */
 const OAUTH_MODULES = [
-	oauthModule({ config: {} as never }),
-	oauthSessionModule({ config: {} as never }),
-	oauthAuthorizationModule({ config: {} as never }),
+	oauthEndpointsModule,
+	oauthSessionGrantModule,
+	oauthAuthorizationGrantsModule,
 ];
 
 /** The modules the template composes that declare a renamed variable. */
@@ -97,23 +98,46 @@ export function libraryLayers(env: Readonly<Record<string, string>>): Config {
 	);
 }
 
+/** Phase one's switches laid over the configuration boot parses. */
+export type BothPhases = Switches & AppConfig;
+
+/**
+ * `switches` laid over `resolved`, the configuration boot parses, as a test
+ * that hands one object to both phases does: the composition root's own keys
+ * beside the sections, and `federation-grants.enabled` written as phase one
+ * decided it into the section as resolved. Boot is so handed phase one's
+ * boolean, not the value as written, unlike `app.mts`; boot's refusal of a
+ * written value phase one installs the modules for is pinned in
+ * `two-phase-config.test.mts`.
+ */
+export function withSwitches(
+	resolved: Readonly<Record<string, unknown>>,
+	switches: Switches,
+): BothPhases {
+	const grants = resolved["federation-grants"];
+	return {
+		...resolved,
+		...switches,
+		"federation-grants": {
+			...(isPlainSection(grants) ? grants : {}),
+			...switches["federation-grants"],
+		},
+	} as unknown as BothPhases;
+}
+
 /**
- * What a test that parses `layers` with `AppConfigSchema` lays beside that
- * parse: every top-level section core's schema does not declare — the
- * template's own modules' among them — as written, which the parse drops;
- * not the composition root's `adapters`, which boot is never handed
- * (`adaptersOf`).
+ * A resolution — `layers`, the template's `config/reference.conf` among them,
+ * under `env` — as a test that resolves by hand hands it to both phases at
+ * once: the configuration as resolved and unparsed, which boot parses as
+ * `app.mts` hands it on, with what phase one reads of it (`readSwitches`)
+ * laid over it — the composition root's `adapters` and `mfaMode`, the Store
+ * transport settings, and `federation-grants.enabled` as phase one decides
+ * it.
  */
-export function sectionsCoreDoesNotDeclare(layers: Config): Record<string, unknown> {
-	const raw = layers.toObject() as Record<string, unknown>;
-	return Object.fromEntries(
-		Object.entries(raw).filter(
-			([key]) =>
-				!Object.hasOwn(AppConfigSchema.shape, key) &&
-				key !== "renamed-variables" &&
-				key !== ADAPTERS_SECTION &&
-				key !== MFA_SWITCH,
-		),
+export function bothPhasesOf(layers: Config, env: Readonly<Record<string, string>>): BothPhases {
+	return withSwitches(
+		layers.toObject() as Record<string, unknown>,
+		readSwitches({ config: layers, env }),
 	);
 }
 
@@ -126,25 +150,6 @@ export function adaptersOf(layers: Config, env: Readonly<Record<string, string>>
 	return readAdapters(layers.toObject() as Record<string, unknown>, env);
 }
 
-/**
- * What phase one reads from a resolution beside core's switches —
- * `layers`, the template's `config/reference.conf` among them, under `env` —
- * as `readSwitches` reads it: the composition root's `adapters` and
- * `mfaMode`, and the Store transport settings.
- */
-export function rootSectionsOf(
-	layers: Config,
-	env: Readonly<Record<string, string>>,
-): { readonly adapters: Adapters; readonly mfaMode: MfaSwitch; readonly storeTransport: unknown } {
-	const raw = layers.toObject() as Record<string, unknown>;
-	const repositories = raw.repositories as { user?: { http?: unknown } } | undefined;
-	return {
-		adapters: readAdapters(raw, env),
-		mfaMode: readMfaSwitch(raw, env),
-		storeTransport: repositories?.user?.http,
-	};
-}
-
 /** The adapters the template ships, as its `config/reference.conf` sets them with no environment. */
 export function shippedAdapters(): Adapters {
 	return adaptersOf(parseFile(fileURLToPath(templateReference()), { env: {} }), {});

package/templates/standalone/src/__tests__/lifecycle-pending-close.test.mts

@@ -0,0 +1,216 @@
+/*
+ * 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 template with core's session lifecycle module: a close whose
+ * relying-party notice fails stays pending, its user session still there,
+ * and from its commit no token reader treats the session as live —
+ * introspection, userinfo and the session grant all refuse it.
+ */
+
+import type { SessionLifecycle, UserSessionStore } from "@o3co/auth-provider-core";
+import request from "supertest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+	authorize,
+	basic,
+	codeFrom,
+	compose,
+	login,
+	redeem,
+	WEB,
+} from "./all-modules-composition.fixture.mjs";
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+/** A JWT's claims, unverified. */
+const claimsOf = (token: string): Record<string, unknown> =>
+	JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+
+describe("a session whose close is pending on a failed relying-party notice", () => {
+	it("is refused by introspection, userinfo and the session grant, its user session still there", async () => {
+		const { app, handle } = await compose({
+			extraClients: {
+				"rp-down": {
+					tokenEndpointAuthMethod: "client_secret_basic",
+					clientSecret: "rp-down-secret-long-enough",
+					allowedRedirectUris: ["https://rp-down.test/cb"],
+					allowedScopes: ["openid"],
+					allowedGrantTypes: ["authorization_code"],
+					backchannelLogoutUri: "https://rp-down.test/logout",
+				},
+			},
+		});
+		try {
+			const components = handle.components as Record<string, unknown>;
+			const lifecycle = components.sessionLifecycle as SessionLifecycle;
+			const sessions = components.userSessionStore as UserSessionStore;
+			const { cookies } = await login(app);
+			const sessionGrant = () =>
+				request(app)
+					.post("/oauth/token")
+					.set("Authorization", basic(WEB))
+					.set("Cookie", cookies)
+					.type("form")
+					.send({ grant_type: "session", scope: "openid profile" });
+			const issued = await sessionGrant();
+			expect(issued.status).toBe(200);
+			const accessToken = issued.body.access_token as string;
+			const sid = String(claimsOf(accessToken).sid);
+			const introspect = () =>
+				request(app)
+					.post("/oauth/introspect")
+					.set("Authorization", basic(WEB))
+					.type("form")
+					.send({ token: accessToken });
+			const userinfo = () =>
+				request(app).get("/oauth/userinfo").set("Authorization", `Bearer ${accessToken}`);
+			expect((await introspect()).body.active).toBe(true);
+			expect((await userinfo()).status).toBe(200);
+
+			// A relying party joins with its family; its back-channel endpoint is
+			// down, so the close commits with its notice pending.
+			expect(
+				await lifecycle.join(sid, {
+					rp: {
+						clientId: "rp-down",
+						backchannelLogoutUri: "https://rp-down.test/logout",
+						backchannelLogoutSessionRequired: true,
+						frontchannelLogoutUri: undefined,
+						frontchannelLogoutSessionRequired: undefined,
+						registeredAt: new Date(),
+					},
+					familyId: "family-down",
+				}),
+			).toEqual({ outcome: "joined" });
+			const posted = vi
+				.spyOn(globalThis, "fetch")
+				.mockImplementation(async () => new Response(null, { status: 503 }));
+			expect((await lifecycle.close(sid, "rp_logout")).outcome).toBe("pending");
+			expect(posted).toHaveBeenCalled();
+			expect(await sessions.get(sid)).not.toBeNull();
+
+			const afterIntrospect = await introspect();
+			expect(afterIntrospect.status).toBe(200);
+			expect(afterIntrospect.body).toEqual({ active: false });
+
+			const afterUserinfo = await userinfo();
+			expect(afterUserinfo.status).toBe(401);
+			expect(afterUserinfo.body.error_description).toBe("session_invalid");
+
+			const again = await sessionGrant();
+			expect(again.status).toBe(400);
+			expect(again.body).toMatchObject({
+				error: "invalid_grant",
+				error_description: "session_invalid",
+			});
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("an RP-initiated logout whose notice fails answers success, and its session is refused by introspection, userinfo and the session grant", async () => {
+		const { app, handle } = await compose({
+			extraClients: {
+				"rp-down": {
+					tokenEndpointAuthMethod: "client_secret_basic",
+					clientSecret: "rp-down-secret-long-enough",
+					allowedRedirectUris: ["https://rp-down.test/cb"],
+					allowedScopes: ["openid"],
+					allowedGrantTypes: ["authorization_code"],
+					backchannelLogoutUri: "https://rp-down.test/logout",
+				},
+			},
+		});
+		try {
+			const components = handle.components as Record<string, unknown>;
+			const lifecycle = components.sessionLifecycle as SessionLifecycle;
+			const sessions = components.userSessionStore as UserSessionStore;
+			const { cookies } = await login(app);
+			// The code exchange joins the session; its id_token is the logout's hint.
+			const exchanged = await redeem(app, codeFrom(await authorize(app, cookies)));
+			expect(exchanged.status).toBe(200);
+			const idToken = exchanged.body.id_token as string;
+			const sid = String(claimsOf(idToken).sid);
+			const sessionGrant = () =>
+				request(app)
+					.post("/oauth/token")
+					.set("Authorization", basic(WEB))
+					.set("Cookie", cookies)
+					.type("form")
+					.send({ grant_type: "session", scope: "openid profile" });
+			const issued = await sessionGrant();
+			expect(issued.status).toBe(200);
+			// A session-grant token carries the session and no family.
+			const accessToken = issued.body.access_token as string;
+			expect(claimsOf(accessToken)).toMatchObject({ sid });
+			expect(claimsOf(accessToken).family_id).toBeUndefined();
+
+			// A relying party whose back-channel endpoint is down joins the session.
+			expect(
+				await lifecycle.join(sid, {
+					rp: {
+						clientId: "rp-down",
+						backchannelLogoutUri: "https://rp-down.test/logout",
+						backchannelLogoutSessionRequired: true,
+						frontchannelLogoutUri: undefined,
+						frontchannelLogoutSessionRequired: undefined,
+						registeredAt: new Date(),
+					},
+				}),
+			).toEqual({ outcome: "joined" });
+			const posted = vi
+				.spyOn(globalThis, "fetch")
+				.mockImplementation(async () => new Response(null, { status: 503 }));
+
+			const logout = await request(app)
+				.post("/oauth/logout")
+				.type("form")
+				.send({ id_token_hint: idToken });
+
+			// The close committed with the notice pending: the logout succeeded.
+			expect(logout.status).toBe(200);
+			expect(logout.body).toEqual({ logged_out: true });
+			expect(posted).toHaveBeenCalled();
+			expect(await sessions.get(sid)).not.toBeNull();
+
+			const introspected = await request(app)
+				.post("/oauth/introspect")
+				.set("Authorization", basic(WEB))
+				.type("form")
+				.send({ token: accessToken });
+			expect(introspected.status).toBe(200);
+			expect(introspected.body).toEqual({ active: false });
+
+			const userinfo = await request(app)
+				.get("/oauth/userinfo")
+				.set("Authorization", `Bearer ${accessToken}`);
+			expect(userinfo.status).toBe(401);
+			expect(userinfo.body.error_description).toBe("session_invalid");
+
+			const again = await sessionGrant();
+			expect(again.status).toBe(400);
+			expect(again.body).toMatchObject({
+				error: "invalid_grant",
+				error_description: "session_invalid",
+			});
+		} finally {
+			await handle.dispose();
+		}
+	});
+});

package/templates/standalone/src/__tests__/mailpit-compose.test.mts

@@ -262,7 +262,6 @@ describe("the process each development run describes", () => {
 
 		const modules = buildModules(switches, {
 			environment: "development",
-			logger: createRecordingLogger(),
 			refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
 		});
 		const handle = await createApp({
@@ -300,7 +299,6 @@ describe("the process each development run describes", () => {
 
 		const modules = buildModules(switches, {
 			environment: configEnv,
-			logger: createRecordingLogger(),
 			refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
 		});
 		const names = modules.map((module) => module.name);