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

package/templates/standalone/src/__tests__/replica-safety.test.mts

@@ -22,8 +22,8 @@
  * - Every memory branch must be refused by name, and the all-Redis
  *   environment must boot. The replica-safety guard reads each module's
  *   manifest declaration, which covers the template's own in-memory modules
- *   and express-session's store (`buildModules` builds it from config,
- *   `sessionStoreModuleFor`).
+ *   and express-session's store (`sessionStoreModule`, which declares from
+ *   its own section).
  * - `federationTokenStore.type = "redis"` mounts
  *   `redisFederationTokenStoreModule` off the shared ioredis socket.
  * - The Redis federation store's `allow-plaintext` guard reads the
@@ -39,28 +39,28 @@
 
 import { fileURLToPath } from "node:url";
 import {
-	AppConfigSchema,
 	createApp,
 	createKeyStoreFactory,
 	defineModule,
 	InMemoryClientRepository,
 	InMemoryUserRepository,
+	type Module,
 	memoryRefreshTokenFamilyStoreModule,
 	registerBuiltinKeyStores,
 	replicaUnsafeReason,
 } from "@o3co/auth-provider-core";
+import { sessionStoreModule } from "@o3co/auth-provider-session";
 import { standardSmtpMailSenderConfigForTests } from "@o3co/auth-provider-standard/testing";
 import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
 import { afterEach, beforeEach, describe, expect, it, vi } 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";
 
 // The redis session-store builder, which the baseline selects, dynamically
@@ -152,6 +152,8 @@ const ALL_REDIS_ENV: Readonly<Record<string, string>> = {
 	REDIS_CLIENTS_URL: "redis://redis.test:6379",
 	ADAPTERS_USER_SESSION_STORES: "redis",
 	ADAPTERS_RATE_LIMITER: "redis",
+	// The login's attempt counter, shared: per process, `multi` refuses the login.
+	ADAPTERS_ATTEMPT_COUNTER: "redis",
 	ADAPTERS_CODE_REPOSITORY: "redis",
 	ADAPTERS_ACCESS_TOKEN_DENYLIST: "redis",
 	ADAPTERS_REPLAY_SEEN_SET: "redis",
@@ -162,20 +164,17 @@ const ALL_REDIS_ENV: Readonly<Record<string, string>> = {
 	ADAPTERS_CONSENT_STORE: "redis",
 };
 
-function resolveConfig(env: Record<string, string>): Switches {
+function resolveConfig(env: Record<string, string>): BothPhases {
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
 	const layers = parseFile(envConfPath, { env })
 		.withFallback(parseFile(applicationConfPath, { env }))
 		.withFallback(parseFile(fileURLToPath(templateReference()), { env }))
 		.withFallback(libraryLayers(env));
 	return {
-		...sectionsCoreDoesNotDeclare(layers),
-		...rootSectionsOf(layers, env),
-		...validate(layers, AppConfigSchema),
-		// What the resolution captured of core's renamed variables, which the
-		// schema's parse drops.
+		...bothPhasesOf(layers, env),
+		// What the resolution captured of the renamed variables.
 		"renamed-variables": capturedRenames(env),
-	} as Switches;
+	} as BothPhases;
 }
 
 /** Drops a variable, so the HOCON default takes over. */
@@ -210,14 +209,21 @@ const testKeyStoreModule = defineModule({
 	},
 });
 
-const modulesFor = (config: Switches, environment?: string) =>
+const modulesFor = (config: BothPhases, environment?: string) =>
 	buildModules(config, {
 		keyStoreModule: testKeyStoreModule,
 		repositoriesModule: testRepositoriesModule,
 		...(environment === undefined ? {} : { environment }),
 	});
 
-const boot = (config: Switches, environment?: string) =>
+/**
+ * `module`'s section in `config`, for a declaration made from it: each module
+ * here that has one sits at its name.
+ */
+const sectionOf = (config: BothPhases, module: Module): unknown =>
+	(config as unknown as Record<string, unknown>)[module.name];
+
+const boot = (config: BothPhases, environment?: string) =>
 	createApp({
 		modules: modulesFor(config, environment),
 		bootstrapComponents: { config, pathResolver: (s) => s },
@@ -242,8 +248,8 @@ describe('the standalone\'s memory modules are refused under core.deployment.mod
 		["ADAPTERS_USER_SESSION_STORES", "standalone-in-memory-session-stores"],
 		["ADAPTERS_CODE_REPOSITORY", "standalone-in-memory-code-repository"],
 		["ADAPTERS_FEDERATION_TOKEN_STORE", "standalone-in-memory-federation-token-store"],
-		// express-session's own store. Not a module of this template but
-		// built here from its config, which is what lets the manifest declare.
+		// express-session's own store. Not a module of this template: it
+		// declares from its own section, which boot parses.
 		["SESSION_STORE_STORAGE_TYPE", "session-store"],
 		// The consent store, wired only when the switch says so.
 		["ADAPTERS_CONSENT_STORE", "core-consent-store-memory"],
@@ -311,13 +317,115 @@ describe('the standalone\'s memory modules are refused under core.deployment.mod
 	it("boots the all-Redis environment, with nothing declaring replica-unsafe state", async () => {
 		const config = resolveConfig(ALL_REDIS_ENV);
 		for (const m of modulesFor(config)) {
-			expect(replicaUnsafeReason(m), m.name).toBeUndefined();
+			expect(replicaUnsafeReason(m, sectionOf(config, m)), m.name).toBeUndefined();
 		}
 		handleRef = await boot(config);
 		expect(handleRef).toBeDefined();
 	});
 });
 
+describe("express-session's store declares its replica safety from its own section", () => {
+	it("is the session package's sessionStoreModule, listed first", () => {
+		expect(modulesFor(resolveConfig(ALL_REDIS_ENV))[0]).toBe(sessionStoreModule);
+	});
+
+	/** Each way the storage type is set, laid over the all-Redis environment. */
+	const STORAGE: ReadonlyArray<readonly [string, Record<string, string>]> = [
+		[
+			"SESSION_STORE_STORAGE_TYPE=memory",
+			{ ...ALL_REDIS_ENV, SESSION_STORE_STORAGE_TYPE: "memory" },
+		],
+		["SESSION_STORE_STORAGE_TYPE=redis", ALL_REDIS_ENV],
+		[
+			"no SESSION_STORE_STORAGE_TYPE, the reference's default",
+			without(ALL_REDIS_ENV, "SESSION_STORE_STORAGE_TYPE"),
+		],
+		[
+			"the variable it was renamed from, SESSION_STORAGE_TYPE=memory",
+			{ ...without(ALL_REDIS_ENV, "SESSION_STORE_STORAGE_TYPE"), SESSION_STORAGE_TYPE: "memory" },
+		],
+	];
+	const MODES: ReadonlyArray<
+		readonly [string, (env: Record<string, string>) => Record<string, string>]
+	> = [
+		["multi", (env) => ({ ...env, CORE_DEPLOYMENT_MODE: "multi" })],
+		["single", (env) => ({ ...env, CORE_DEPLOYMENT_MODE: "single" })],
+		["unset", (env) => without(env, "CORE_DEPLOYMENT_MODE")],
+	];
+
+	/** What a boot of `modules` settles as: the refusal, or the replica-safety warnings it logged. */
+	async function outcomeOf(config: BothPhases, modules: readonly Module[]): Promise<unknown> {
+		const warn = vi.fn();
+		const logger = {
+			warn,
+			info: vi.fn(),
+			error: vi.fn(),
+			debug: vi.fn(),
+			trace: vi.fn(),
+			fatal: vi.fn(),
+			child: vi.fn(),
+		};
+		try {
+			const handle = await createApp({
+				modules: [...modules],
+				bootstrapComponents: { config, logger, pathResolver: (s: string) => s } as never,
+			});
+			await handle.dispose();
+		} catch (err) {
+			const e = err as { reason?: string; message?: string; details?: unknown };
+			return { refused: { reason: e.reason, message: e.message, details: e.details } };
+		}
+		return {
+			warned: warn.mock.calls.filter(([, event]) => event === "replica_unsafe_adapters"),
+		};
+	}
+
+	for (const [storage, env] of STORAGE) {
+		for (const [mode, withMode] of MODES) {
+			it(`${storage} under ${mode}`, async () => {
+				const config = resolveConfig(withMode(env));
+				const modules = modulesFor(config);
+				expect(modules[0]).toBe(sessionStoreModule);
+				const outcome = await outcomeOf(config, modules);
+				if (
+					storage === "SESSION_STORE_STORAGE_TYPE=redis" ||
+					storage === "no SESSION_STORE_STORAGE_TYPE, the reference's default"
+				) {
+					// A shared store: nothing is refused or warned about.
+					expect(outcome).toEqual({ warned: [] });
+				}
+				if (storage === "SESSION_STORE_STORAGE_TYPE=memory") {
+					const named = { modules: ["session-store"] };
+					expect(outcome).toEqual(
+						mode === "multi"
+							? {
+									refused: expect.objectContaining({
+										reason: "replica-unsafe-adapter",
+										message: expect.stringContaining(
+											"session-store: the express-session store forks per replica",
+										),
+										details: expect.objectContaining(named),
+									}),
+								}
+							: {
+									warned:
+										mode === "unset"
+											? [[expect.objectContaining(named), "replica_unsafe_adapters"]]
+											: [],
+								},
+					);
+				}
+				if (storage === "the variable it was renamed from, SESSION_STORAGE_TYPE=memory") {
+					// Refused as renamed before the replica-safety guard reads anything.
+					expect(outcome).toEqual({
+						refused: expect.objectContaining({ reason: "environment-variable-renamed" }),
+					});
+				}
+			});
+		}
+	}
+});
+
 describe('adapters.federationTokenStore = "redis" in the standalone', () => {
 	let handleRef: Awaited<ReturnType<typeof boot>> | undefined;
 

package/templates/standalone/src/__tests__/scaffold-assets.test.mts

@@ -24,16 +24,14 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema, coreReference } from "@o3co/auth-provider-core";
+import { BootError } from "@o3co/auth-provider-core";
 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 { readOwnLayers, readSwitches, resolveConfigPaths } from "../configPath.mjs";
 import { templateReference } from "../modules.mjs";
 import { type Adapters, repositoriesSectionSchema } from "../sections.mjs";
-import { createRecordingLogger } from "./all-modules-composition.fixture.mjs";
 
 const standaloneDir = fileURLToPath(new URL("../..", import.meta.url));
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
@@ -64,18 +62,6 @@ function composeAppEnvironment(rel: string): Map<string, string | null> {
 	return env;
 }
 
-/** Resolve the shipped config layers under a given environment, as `src/app.mts` does. */
-function resolveWith(env: Record<string, string>, configEnv = "production"): AppConfig {
-	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, configEnv);
-	return validate(
-		parseFile(envConfPath, { env })
-			.withFallback(parseFile(applicationConfPath, { env }))
-			.withFallback(parseFile(fileURLToPath(templateReference()), { env }))
-			.withFallback(parseFile(fileURLToPath(coreReference()), { env })),
-		AppConfigSchema,
-	);
-}
-
 /** The template's own layers under `env`, over its own reference, unparsed. */
 function ownResolved(
 	env: Record<string, string>,
@@ -88,6 +74,14 @@ function ownResolved(
 		.toObject() as Record<string, unknown>;
 }
 
+/** `session-store.storage.type` as the template's own layers resolve it under `env`. */
+function sessionStorageTypeWith(env: Record<string, string>): unknown {
+	const section = ownResolved(env)["session-store"] as
+		| { readonly storage?: { readonly type?: unknown } }
+		| undefined;
+	return section?.storage?.type;
+}
+
 /** The adapters phase one reads under `env`. */
 function adaptersWith(env: Record<string, string>, configEnv = "production"): Adapters {
 	return readAdapters(ownResolved(env, configEnv), env);
@@ -330,7 +324,7 @@ describe("the compose files put a store and its lifetime-sibling on the same bac
 			// Resolved through the real config layers, not read off the file:
 			// what matters is the value the process ends up with, whether the
 			// compose stated it or `config/application.conf` did.
-			expect(resolveWith(env)["session-store"]?.storage?.type).toBe("redis");
+			expect(sessionStorageTypeWith(env)).toBe("redis");
 			expect(adaptersWith(env).userSessionStores).toBe("redis");
 		});
 	}
@@ -341,7 +335,7 @@ describe("the compose files put a store and its lifetime-sibling on the same bac
 		// token store is deliberately absent: this template ships every
 		// federation disabled, so nothing writes to it, and turning it on needs
 		// an AES key the compose file must not invent.
-		expect(resolveWith(env)["session-store"]?.storage?.type).toBe("redis");
+		expect(sessionStorageTypeWith(env)).toBe("redis");
 		expect(adaptersWith(env)).toMatchObject({
 			userSessionStores: "redis",
 			codeRepository: "redis",
@@ -375,12 +369,13 @@ describe("the production compose leaves MFA on, for the deployment to decide", (
 
 		let err: unknown;
 		try {
-			buildModules(switches, { environment: configEnv, logger: createRecordingLogger() });
+			buildModules(switches, { environment: configEnv });
 		} catch (caught) {
 			err = caught;
 		}
-		expect(err).toBeInstanceOf(RangeError);
-		expect((err as RangeError).message).toContain("MFA_MODE=off");
+		expect(err).toBeInstanceOf(BootError);
+		expect((err as BootError).reason).toBe("config-validation-failed");
+		expect((err as BootError).message).toContain("MFA_MODE=off");
 	});
 });
 

package/templates/standalone/src/__tests__/session-lifecycle.test.mts

@@ -0,0 +1,215 @@
+/*
+ * 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 composes core's session lifecycle module: it serves relying
+ * parties, so boot holds it to a session-close notifier, which the oauth
+ * module contributes.
+ */
+
+import {
+	type FederationTokenStore,
+	readVersionedSessionLifecycle,
+	type SessionLifecycle,
+	type SessionLifecycleStore,
+	type SubjectSessionIndex,
+	type UserSessionStore,
+} from "@o3co/auth-provider-core";
+import request from "supertest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+	ALICE,
+	basic,
+	compose,
+	cookiesOf,
+	federatedCallback,
+	ISSUER,
+	login,
+	WEB,
+	webTokens,
+} 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("the template, which composes the session lifecycle module", () => {
+	it("boots, the oauth module's notifier contributed", async () => {
+		const { handle } = await compose();
+		try {
+			const lifecycle = handle.components.sessionLifecycle as SessionLifecycle | undefined;
+			expect(lifecycle).toBeDefined();
+			expect(handle.components.sessionCloseNotifierResolver?.get()).toBeDefined();
+			expect(await lifecycle?.close("no-such-session", "expiry")).toEqual({
+				outcome: "done",
+				rps: [],
+				federations: [],
+			});
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("tells a relying party that joined, through the oauth module's notifier, when the session closes", async () => {
+		const { handle } = await compose({
+			extraClients: {
+				"rp-bc": {
+					tokenEndpointAuthMethod: "client_secret_basic",
+					clientSecret: "rp-bc-secret-long-enough",
+					allowedRedirectUris: ["https://rp-bc.test/cb"],
+					allowedScopes: ["openid"],
+					allowedGrantTypes: ["authorization_code"],
+					backchannelLogoutUri: "https://rp-bc.test/logout",
+				},
+			},
+		});
+		try {
+			const components = handle.components as Record<string, unknown>;
+			const lifecycle = components.sessionLifecycle as SessionLifecycle;
+			const sessions = components.userSessionStore as UserSessionStore;
+			const expiresAt = new Date(Date.now() + 3_600_000);
+			await sessions.create({
+				sid: "sid-bc",
+				sub: "u-bc",
+				authTime: new Date(),
+				expiresAt,
+				claims: {},
+				amr: ["pwd"],
+				authentication: undefined,
+			});
+			expect(await lifecycle.open("sid-bc", { sub: "u-bc", expiresAt })).toEqual({
+				outcome: "opened",
+			});
+			const rp = {
+				clientId: "rp-bc",
+				backchannelLogoutUri: "https://rp-bc.test/logout",
+				backchannelLogoutSessionRequired: true,
+				frontchannelLogoutUri: undefined,
+				frontchannelLogoutSessionRequired: undefined,
+				registeredAt: new Date(),
+			};
+			expect(await lifecycle.join("sid-bc", { rp, familyId: "family-bc" })).toEqual({
+				outcome: "joined",
+			});
+			const posted = vi
+				.spyOn(globalThis, "fetch")
+				.mockImplementation(async () => new Response(null, { status: 200 }));
+			expect((await lifecycle.close("sid-bc", "rp_logout")).outcome).toBe("done");
+			expect(posted).toHaveBeenCalledTimes(1);
+			const [url, init] = posted.mock.calls[0] as [string, RequestInit];
+			expect(url).toBe("https://rp-bc.test/logout");
+			const token = new URLSearchParams(String(init.body)).get("logout_token");
+			expect(claimsOf(token ?? "")).toMatchObject({
+				iss: ISSUER,
+				aud: "rp-bc",
+				sub: "u-bc",
+				sid: "sid-bc",
+			});
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("opens a password login's session in the lifecycle, active with nothing joined yet", async () => {
+		const { app, handle } = await compose();
+		try {
+			expect((await login(app)).res.status).toBe(200);
+			const components = handle.components as Record<string, unknown>;
+			const [sid] = await (components.subjectSessionIndex as SubjectSessionIndex).listSids(
+				ALICE.sub,
+			);
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			const record = readVersionedSessionLifecycle(await store.read(String(sid)));
+			expect(record?.value).toMatchObject({ sub: ALICE.sub, state: "active", participants: [] });
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("joins a federated login's federation to the session's lifecycle record, beside its tokens, through the session module's federation routes", async () => {
+		const { app, handle, upstreams } = await compose();
+		try {
+			const callback = await (await federatedCallback(app, "oidc", upstreams.oidc))();
+			expect(callback.status).toBe(302);
+			expect(cookiesOf(callback)).not.toEqual([]);
+			const components = handle.components as Record<string, unknown>;
+			const [sid] = await (components.subjectSessionIndex as SubjectSessionIndex).listSids(
+				ALICE.sub,
+			);
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			const record = readVersionedSessionLifecycle(await store.read(String(sid)));
+			expect(record?.value).toMatchObject({ sub: ALICE.sub, state: "active" });
+			expect(record?.value.participants.map((p) => `${p.kind}:${p.id}`)).toEqual([
+				"federation:oidc",
+			]);
+			const tokens = components.federationTokenStore as FederationTokenStore;
+			expect(await tokens.get(String(sid), "oidc")).not.toBeNull();
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("joins a code exchange's relying party and family to the session's lifecycle record", async () => {
+		const { app, handle } = await compose();
+		try {
+			const tokens = await webTokens(app);
+			const claims = claimsOf(tokens.refresh_token ?? "");
+			const sid = String(claims.sid);
+			const store = (handle.components as Record<string, unknown>)
+				.sessionLifecycleStore as SessionLifecycleStore;
+			const record = readVersionedSessionLifecycle(await store.read(sid));
+			expect(record?.value.state).toBe("active");
+			expect(record?.value.participants.map((p) => `${p.kind}:${p.id}`)).toEqual([
+				`rp:${WEB.id}`,
+				`family:${String(claims.family_id)}`,
+			]);
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("closes the session through the lifecycle at /oauth/logout: the record closed, the session and its refresh token gone", async () => {
+		const { app, handle } = await compose();
+		try {
+			const tokens = await webTokens(app);
+			const sid = String(claimsOf(tokens.refresh_token ?? "").sid);
+			const components = handle.components as Record<string, unknown>;
+
+			const res = await request(app)
+				.post("/oauth/logout")
+				.type("form")
+				.send({ id_token_hint: tokens.id_token });
+
+			expect(res.status).toBe(200);
+			expect(res.body).toEqual({ logged_out: true });
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			expect(readVersionedSessionLifecycle(await store.read(sid))?.value.state).toBe("closed");
+			expect(await (components.userSessionStore as UserSessionStore).get(sid)).toBeNull();
+			const refreshed = await request(app)
+				.post("/oauth/token")
+				.set("Authorization", basic(WEB))
+				.type("form")
+				.send({ grant_type: "refresh_token", refresh_token: tokens.refresh_token });
+			expect(refreshed.status).toBe(400);
+		} finally {
+			await handle.dispose();
+		}
+	});
+});

package/templates/standalone/src/__tests__/session-logout-invalidates-token.test.mts

@@ -90,17 +90,13 @@ const config: AppConfig & Record<string, unknown> = {
 	},
 	// The session requirements this composition expects, as the shipped
 	// `application.conf` does (ADR 2026-09-28-session-admission): none.
-	...coreConfigForTests({ federations: { google: { enabled: false } } }),
+	...coreConfigForTests({ federations: { google: { enabled: false, type: "google" } } }),
 	oauth: {
 		jwt: {
 			issuer: "https://auth.test",
 		},
-		accessToken: { expiresIn: 3600 },
-		refreshToken: {
-			expiresIn: 86400,
-			unknownFamilyPolicy: "reject" as const,
-			legacyRtPolicy: "reject" as const,
-		},
+		accessToken: { defaultExpiresIn: 3600 },
+		refreshToken: { expiresIn: 86400 },
 		oidcMode: "oidc-required",
 	},
 	// The grant this whole test is about: it mints straight from an

package/templates/standalone/src/__tests__/session-logout-lifecycle.test.mts

@@ -0,0 +1,130 @@
+/*
+ * 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: `POST /session/logout`
+ * closes the session through it, so the browser's own logout revokes the
+ * session's refresh-token families and tells its relying parties, as
+ * `/oauth/logout` does.
+ */
+
+import {
+	type RefreshTokenFamilyRevocation,
+	readVersionedSessionLifecycle,
+	type SessionLifecycle,
+	type SessionLifecycleStore,
+	type UserSessionStore,
+} from "@o3co/auth-provider-core";
+import request from "supertest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { authorize, codeFrom, compose, login, redeem } 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"));
+
+/** The CSRF token a login reissued, read off its double-submit cookie. */
+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] ?? "");
+};
+
+describe("POST /session/logout with the session lifecycle module", () => {
+	it("revokes the session's families, tells its relying parties and closes its record", async () => {
+		const { app, handle } = await compose({
+			extraClients: {
+				"rp-bc": {
+					tokenEndpointAuthMethod: "client_secret_basic",
+					clientSecret: "rp-bc-secret-long-enough",
+					allowedRedirectUris: ["https://rp-bc.test/cb"],
+					allowedScopes: ["openid"],
+					allowedGrantTypes: ["authorization_code"],
+					backchannelLogoutUri: "https://rp-bc.test/logout",
+				},
+			},
+		});
+		try {
+			const components = handle.components as Record<string, unknown>;
+			const lifecycle = components.sessionLifecycle as SessionLifecycle;
+			const sessions = components.userSessionStore as UserSessionStore;
+			const families = components.refreshTokenFamilyRevocation as RefreshTokenFamilyRevocation;
+			const { cookies } = await login(app);
+			const exchanged = await redeem(app, codeFrom(await authorize(app, cookies)));
+			expect(exchanged.status).toBe(200);
+			const claims = claimsOf(exchanged.body.refresh_token as string);
+			const sid = String(claims.sid);
+			const familyId = String(claims.family_id);
+			expect(
+				await lifecycle.join(sid, {
+					rp: {
+						clientId: "rp-bc",
+						backchannelLogoutUri: "https://rp-bc.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: 200 }));
+
+			const csrfToken = csrfTokenOf(cookies);
+			const res = await request(app)
+				.post("/session/logout")
+				.set("Cookie", cookies)
+				.set("x-csrf-token", csrfToken);
+
+			expect(res.status).toBe(200);
+			expect(await families.isFamilyRevoked(familyId)).toBe(true);
+			expect(posted.mock.calls.map(([url]) => String(url))).toEqual(["https://rp-bc.test/logout"]);
+			expect(await sessions.get(sid)).toBeNull();
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			expect(readVersionedSessionLifecycle(await store.read(sid))?.value.state).toBe("closed");
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("answers 503 when the close cannot commit, and the cookie still admits the session for a retry", async () => {
+		const { app, handle } = await compose();
+		try {
+			const { cookies } = await login(app);
+			const components = handle.components as Record<string, unknown>;
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			vi.spyOn(store, "beginClose").mockRejectedValue(new Error("lifecycle store down"));
+
+			const res = await request(app)
+				.post("/session/logout")
+				.set("Cookie", cookies)
+				.set("x-csrf-token", csrfTokenOf(cookies));
+
+			expect(res.status).toBe(503);
+			expect(res.body.error).toBe("temporarily_unavailable");
+			// The session is still live and its cookie still admits it.
+			const authorized = await authorize(app, cookies);
+			expect(codeFrom(authorized)).toEqual(expect.any(String));
+		} finally {
+			await handle.dispose();
+		}
+	});
+});