@o3co/create-auth-provider 0.10.0 → 0.12.0

package/templates/standalone/src/__tests__/shutdown.test.mts

@@ -0,0 +1,324 @@
+/*
+ * 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.
+ */
+
+/**
+ * Issue #290 — shutdown was delegated to `@o3co/auth.utils@0.0.4`, whose
+ * guarantees were not pinned by any contract this repository could check.
+ *
+ * Reading the 22 lines answered the question the issue asked, and the answer
+ * was worth knowing: **there was no force-close deadline**. `server.close()`
+ * waits for in-flight requests indefinitely, so one stuck request meant the
+ * process never exited on its own and the orchestrator's SIGKILL took it down
+ * mid-flight — the opposite of a graceful shutdown, and invisible until it
+ * happened. The cleanup-failure path also wrote to `console.error`, a bare
+ * line in a service whose every other line is NDJSON.
+ *
+ * So the behaviour lives here now, with a deadline and the app's own logger,
+ * and these tests are the contract the issue said was missing.
+ */
+
+import type { Server } from "node:http";
+import type { Logger } from "@o3co/auth-provider-core";
+import { describe, expect, it, vi } from "vitest";
+import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
+
+/** A `Server` double whose `close` callback fires only when we say so. */
+function makeServer() {
+	let closeCallback: ((err?: Error) => void) | undefined;
+	const server = {
+		close: vi.fn((cb?: (err?: Error) => void) => {
+			closeCallback = cb;
+			return server;
+		}),
+		closeIdleConnections: vi.fn(),
+		closeAllConnections: vi.fn(),
+	};
+	return {
+		server: server as unknown as Server,
+		spies: server,
+		/** Simulate the last in-flight request finishing. */
+		finishDraining: () => closeCallback?.(),
+		/** Simulate `close` reporting a failure through its callback. */
+		failClose: (err: Error) => closeCallback?.(err),
+		get drained() {
+			return closeCallback !== undefined;
+		},
+	};
+}
+
+/**
+ * A `Logger`-shaped spy. Typed rather than cast: `as never` would hide a real
+ * mismatch the day the port gains a method, which is the whole reason the
+ * shutdown path logs through the app logger instead of `console`.
+ */
+const makeLogger = () => {
+	const spy = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		// `child` returns a Logger; returning this one keeps a child's calls
+		// visible on the same spies, which is what a test wants.
+		child: vi.fn(() => spy as unknown as Logger),
+	};
+	return spy satisfies Logger;
+};
+
+/** Drive one shutdown without touching the real `process` or exiting. */
+function install(opts: { cleanup?: () => void | Promise<void>; drainTimeoutMs?: number } = {}) {
+	const { server, spies, finishDraining, failClose } = makeServer();
+	const logger = makeLogger();
+	const exit = vi.fn();
+	const signals = new Map<string, () => void>();
+
+	installGracefulShutdown(server, {
+		logger,
+		cleanup: opts.cleanup ?? (() => {}),
+		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
+		exit,
+		onSignal: (name, handler) => signals.set(name, handler),
+		offSignal: (name) => signals.delete(name),
+	});
+
+	return { spies, logger, exit, signals, finishDraining, failClose };
+}
+
+describe("installGracefulShutdown (#290)", () => {
+	it("listens for both SIGTERM and SIGINT", async () => {
+		const { signals } = install();
+		expect([...signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
+	});
+
+	it("stops accepting connections and releases idle keep-alive sockets", async () => {
+		const { spies, signals } = install();
+		signals.get("SIGTERM")?.();
+		expect(spies.close).toHaveBeenCalled();
+		// Idle keep-alive sockets hold the server open with no request behind
+		// them; releasing them is what lets a quiet server exit promptly.
+		expect(spies.closeIdleConnections).toHaveBeenCalled();
+	});
+
+	it("runs cleanup once draining completes, then exits zero", async () => {
+		const cleanup = vi.fn();
+		const { exit, signals, finishDraining } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		expect(cleanup).not.toHaveBeenCalled();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	it("ignores a second signal instead of running cleanup twice", async () => {
+		// An operator pressing ^C twice, or a SIGINT arriving after SIGTERM,
+		// must not start a second dispose over the first one's stores.
+		const cleanup = vi.fn();
+		const { signals, finishDraining, exit } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		signals.get("SIGINT")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	// The gap the audit was pointing at.
+	it("forces the remaining connections closed when draining outruns the deadline", async () => {
+		vi.useFakeTimers();
+		try {
+			const { spies, signals, exit } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(spies.closeAllConnections).toHaveBeenCalled();
+			expect(exit).toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("exits non-zero on a forced close, so the drain outcome is visible", async () => {
+		// An orchestrator that only ever sees exit 0 cannot tell a clean drain
+		// from one that ran out of time and cut requests off.
+		vi.useFakeTimers();
+		try {
+			const { signals, exit, logger } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(exit).toHaveBeenCalledWith(1);
+			expect(logger.error).toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not force-close a drain that finished in time", async () => {
+		vi.useFakeTimers();
+		try {
+			const { spies, signals, finishDraining, exit } = install({ drainTimeoutMs: 5_000 });
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
+			await vi.advanceTimersByTimeAsync(10_000);
+			expect(spies.closeAllConnections).not.toHaveBeenCalled();
+			expect(exit).toHaveBeenCalledTimes(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("reports a cleanup failure through the app logger, not console", async () => {
+		// Every other line this service emits is NDJSON through pino; a bare
+		// console.error on the shutdown path is the one a log pipeline drops.
+		const { logger, exit, signals, finishDraining } = install({
+			cleanup: () => {
+				throw new Error("redis quit failed");
+			},
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(logger.error).toHaveBeenCalledWith(
+			expect.objectContaining({ err: expect.any(Error) }),
+			expect.stringContaining("cleanup"),
+		);
+	});
+
+	it("still exits when cleanup throws — a failed dispose must not wedge the process", async () => {
+		const { exit, signals, finishDraining } = install({
+			cleanup: async () => {
+				throw new Error("dispose failed");
+			},
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+	});
+
+	it("does not report a failed close as a clean drain", async () => {
+		// `server.close` reports through its callback -- "Server is not running"
+		// is the common one, but any listener teardown failure lands there.
+		// Exiting 0 on it would tell an orchestrator the listener came down
+		// when it did not.
+		const { exit, logger, signals, failClose } = install();
+		signals.get("SIGTERM")?.();
+		failClose(new Error("Server is not running"));
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+		expect(logger.error).toHaveBeenCalledWith(
+			expect.objectContaining({ err: expect.any(Error) }),
+			expect.stringContaining("close"),
+		);
+	});
+
+	it("still runs cleanup when close reports a failure", async () => {
+		// The listener failing to come down is no reason to leak the Redis
+		// connections behind it.
+		const cleanup = vi.fn();
+		const { exit, signals, failClose } = install({ cleanup });
+		signals.get("SIGTERM")?.();
+		failClose(new Error("teardown failed"));
+		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
+		expect(cleanup).toHaveBeenCalledTimes(1);
+	});
+
+	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
+		// The guarantees above say cleanup "never wedges the process", but `finish`
+		// awaited it with no deadline — and the drain deadline is already cleared
+		// by then, so a dispose that never settles meant `exit` was never reached.
+		// The same defect was found in auth.proxy#81 and auth.policy-verifier#210,
+		// both of which took this file as their starting point.
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(logger.error).toHaveBeenCalledWith(
+				expect.objectContaining({ cleanupTimeoutMs: 5_000 }),
+				expect.stringContaining("cleanup timed out"),
+			);
+			expect(exit).toHaveBeenCalledWith(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not penalise a cleanup that finishes inside its budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => Promise.resolve(),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(10_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("defers the real exit a turn so a buffered log destination can flush", async () => {
+		// The scaffolded app logs NDJSON through pino, whose default destination is
+		// not synchronous: exiting in the same tick as the last `logger.error` can
+		// drop exactly the `cleanup failed` line an operator would look for.
+		const exitProcess = vi.fn();
+		deferExit(3, exitProcess);
+		expect(exitProcess).not.toHaveBeenCalled();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(exitProcess).toHaveBeenCalledWith(3);
+	});
+
+	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
+		// `exitCode` became 1 while `reason` still said "drained", so the one line
+		// an operator alerts on contradicted itself. The drain outcome is still
+		// carried, under its own key, so neither fact is lost.
+		const { signals, finishDraining, logger, exit } = install({
+			cleanup: () => Promise.reject(new Error("teardown failed")),
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
+			"graceful shutdown: complete",
+		);
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("keeps reason and drain identical when cleanup succeeds", async () => {
+		const { signals, finishDraining, logger } = install({ cleanup: () => Promise.resolve() });
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "drained", drain: "drained", exitCode: 0 },
+			"graceful shutdown: complete",
+		);
+	});
+
+	it("removes its own signal listeners once shutting down", async () => {
+		// Otherwise a repeated signal keeps re-entering a handler that has
+		// already handed the process over to `close`.
+		const { signals } = install();
+		signals.get("SIGTERM")?.();
+		expect(signals.size).toBe(0);
+	});
+});

package/templates/standalone/src/__tests__/smoke.test.mts

@@ -469,6 +469,42 @@ describe("standalone smoke test", () => {
 			expect(names).not.toContain("standalone:stores");
 			expect(names).toContain("standalone:redis-clients");
 		});
+
+		// #321's `redisSessionStoresModule` requires the two subject-level client
+		// slots (`subjectSessionIndexClient`, `subjectRevocationClient`) its
+		// adapters consume, and the scaffold's shared ioredis module did not
+		// provide them — so `userSessionStores.adapter = "redis"`, the
+		// template's own multi-replica path, failed stage-1 boot with
+		// `missing-required-component`. Nothing here booted that branch: the
+		// tests above check which modules are selected, not whether the
+		// selection is satisfiable. This pins the invariant the shared clients
+		// module exists for: every `*Client` slot any selected module requires
+		// is one it provides.
+		it("standalone:redis-clients provides every *Client slot the Redis branches require", () => {
+			const allRedisConfig = {
+				...config,
+				userSessionStores: { adapter: "redis" as const },
+				rateLimiter: { adapter: "redis" as const },
+				accessTokenDenylist: { adapter: "redis" as const },
+				oauth: { ...config.oauth, code: { adapter: "redis" as const } },
+			};
+			// No `refreshTokenFamilyModules` override: the default is the Redis
+			// RT-family store, so `refreshTokenFamilyClient` is part of what the
+			// invariant covers. Still hermetic — buildModules opens no socket.
+			const modules = buildModules(allRedisConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+			});
+			const clients = modules.find((m) => m.name === "standalone:redis-clients");
+			expect(clients).toBeDefined();
+			const provided = new Set(Object.keys(clients?.provides ?? {}));
+			const requiredClientSlots = new Set(
+				modules.flatMap((m) => [...(m.requires ?? [])]).filter((key) => key.endsWith("Client")),
+			);
+			expect(requiredClientSlots.size).toBeGreaterThan(0);
+			const missing = [...requiredClientSlots].filter((key) => !provided.has(key));
+			expect(missing).toEqual([]);
+		});
 	});
 
 	// #277: the scaffold used to wire NO access-token denylist, so the

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

@@ -193,18 +193,23 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 			// every in-memory shared store, so the denylist this change adds has to
 			// come out of that environment as the Redis one — from the template's
 			// own config, since the compose file names no denylist variable.
-			// Asserted against the guard's own list rather than a module name, so a
-			// rename cannot quietly invalidate it.
-			const { REPLICA_UNSAFE_MODULES } = await import("@o3co/auth-provider-core");
+			// Asked of each manifest, the way the guard does (#455), so a rename
+			// cannot quietly invalidate it and the template's own memory modules
+			// — which no name list in core covers — count too.
+			const { replicaUnsafeReason } = await import("@o3co/auth-provider-core");
 			const config = buildResolvedConfig("production", {
 				USER_SESSION_STORES_ADAPTER: "redis",
 				RATE_LIMITER_ADAPTER: "redis",
 				OAUTH_CODE_ADAPTER: "redis",
+				// #456: the federation token store defaults to memory, and the
+				// memory module declares itself replica-unsafe (#455).
+				FEDERATION_TOKEN_STORE_TYPE: "redis",
+				REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
 			});
-			const names = buildModules(config).map((m) => m.name);
-			expect(names).toContain("redis-access-token-denylist");
-			for (const name of names) {
-				expect(REPLICA_UNSAFE_MODULES).not.toContain(name);
+			const modules = buildModules(config);
+			expect(modules.map((m) => m.name)).toContain("redis-access-token-denylist");
+			for (const module of modules) {
+				expect(replicaUnsafeReason(module), module.name).toBeUndefined();
 			}
 		});
 

package/templates/standalone/src/app.mts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import { gracefulShutdown } from "@o3co/auth.utils";
 import {
 	type AppConfig,
 	AppConfigSchema,
@@ -30,6 +29,7 @@ import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
+import { installGracefulShutdown } from "./shutdown.mjs";
 import { createTerminalErrorHandler } from "./terminalError.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
@@ -99,8 +99,12 @@ await (async (): Promise<void> => {
 	// `buildModules` is the single source of truth for the module list — it
 	// gates federation modules on `config.federations.<name>.enabled`, which
 	// the standalone scaffold defaults to false.
+	//
+	// `environment` is the name the config above was selected by (#473): the
+	// Redis federation-token store's plaintext guard reads it in addition to
+	// NODE_ENV, so `CONFIG_ENV=production` is production to the guard too.
 	const handle = await createApp({
-		modules: buildModules(config),
+		modules: buildModules(config, { environment: env }),
 		bootstrapComponents: {
 			config,
 			pathResolver: import.meta.resolve,
@@ -154,5 +158,14 @@ await (async (): Promise<void> => {
 	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
 	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain
 	// (Redis clients, interval timers).
-	gracefulShutdown(server, () => handle.dispose());
+	//
+	// #290: in the template rather than a dependency, because "does SIGTERM
+	// wait for in-flight requests, and for how long?" has to be answerable
+	// from the code you deploy. See `shutdown.mts` for the stated guarantees
+	// and for the deadline the previous implementation did not have. Size
+	// `drainTimeoutMs` below your orchestrator's kill grace period.
+	installGracefulShutdown(server, {
+		logger,
+		cleanup: () => handle.dispose(),
+	});
 })();

package/templates/standalone/src/buildModules.mts

@@ -31,16 +31,17 @@ import {
 import {
 	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
+	redisFederationTokenStoreModuleFor,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
 	redisSessionStoresModule,
 } from "@o3co/auth-provider-redis";
-import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
+import { sessionModule, sessionStoreModuleFor } from "@o3co/auth-provider-session";
 import {
 	auditSinkModule,
-	federationTokenStoreModule,
 	googleFederationConfigModule,
 	inMemoryCodeRepositoryModule,
+	inMemoryFederationTokenStoreModule,
 	inMemorySessionStoresModule,
 	keyStoreModule,
 	repositoriesModule,
@@ -48,11 +49,21 @@ import {
 } from "./modules.mjs";
 
 /**
- * Test-only overrides allowing the smoke test to substitute in-memory
- * implementations of the file-system-backed modules. Production callers
- * should not pass overrides; the defaults match the standalone scaffold.
+ * Overrides for the composition. All but `environment` are test-only: they let
+ * the smoke test substitute in-memory implementations of the file-system-backed
+ * modules, and production callers should not pass them — the defaults match the
+ * standalone scaffold.
  */
 export interface BuildModulesOverrides {
+	/**
+	 * #473: the name this deployment selected its configuration by —
+	 * `CONFIG_ENV || NODE_ENV`, computed once in `app.mts` and passed here so
+	 * the Redis federation-token store's `allow-plaintext` guard reads the
+	 * environment the config actually came from, not `NODE_ENV` alone. Omitted,
+	 * the guard falls back to `NODE_ENV` (and `deployment.mode`, which it reads
+	 * off the config either way).
+	 */
+	readonly environment?: string;
 	readonly keyStoreModule?: Module;
 	readonly repositoriesModule?: Module;
 	readonly storesModule?: Module;
@@ -117,6 +128,12 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// endpoint would answer 200 while the token kept working. The switch here is
 	// only over WHICH denylist.
 	const accessTokenDenylistAdapter = config.accessTokenDenylist?.adapter ?? "memory";
+	// #456: adapter switch for the federation token store. `"memory"` by
+	// default, the template's local-dev shape; `"redis"` mounts
+	// `redisFederationTokenStoreModule` off the shared socket — what the README
+	// promised and what the previous factory-based module never delivered: it
+	// built the Redis store without a client and failed at boot.
+	const federationTokenStoreAdapter = config.federationTokenStore?.type ?? "memory";
 
 	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
 	// authoritative switch; the legacy `repositories.code.type = "redis"`
@@ -154,12 +171,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		rateLimiterAdapter === "redis" ||
 		userSessionStoresAdapter === "redis" ||
 		codeRepositoryAdapter === "redis" ||
-		accessTokenDenylistAdapter === "redis";
+		accessTokenDenylistAdapter === "redis" ||
+		federationTokenStoreAdapter === "redis";
 
-	// Federation-token store is always wired; only the 4 user-session
-	// stores switch on the adapter. Pre-Wave-5d the redis branch dropped
-	// the federation-token-store provider entirely (Copilot review on
-	// PR #121); splitting `storesModule` fixes that boot failure.
+	// The four user-session stores switch on `userSessionStores.adapter`; the
+	// federation-token store is always wired and switches on its own key
+	// below (#456). Pre-Wave-5d the redis branch dropped the
+	// federation-token-store provider entirely (Copilot review on PR #121);
+	// splitting `storesModule` fixed that boot failure.
 	const sessionStoresModules: Module[] =
 		userSessionStoresAdapter === "redis"
 			? [redisSessionStoresModule]
@@ -188,13 +207,32 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 			? [redisAccessTokenDenylistModule]
 			: [memoryAccessTokenDenylistModule];
 
+	// #455 / #456: mutually-exclusive federation-token-store pair, the same
+	// shape as the session stores. One module per adapter, so the memory one
+	// can declare `replicaSafety` on its manifest and the Redis one can
+	// `require` its client slot. The previous single module chose the adapter
+	// at runtime under one name — the replica guard could not tell the two
+	// apart, and the Redis branch had no client to hand the builder.
+	//
+	// #473: the Redis module is built for this composition root so its
+	// plaintext guard knows which environment selected the config; it reads
+	// `deployment.mode` off the config itself.
+	const federationTokenStoreModules: Module[] =
+		federationTokenStoreAdapter === "redis"
+			? [redisFederationTokenStoreModuleFor({ environment: overrides.environment })]
+			: [inMemoryFederationTokenStoreModule];
+
 	return [
 		// D-5: sessionStoreModule wires the express-session middleware into the
 		// boot-planner-managed lifecycle. **Mount order is enforced by this
 		// list position (declarationIndex tie-breaking)** — the module
 		// intentionally has no `before`/`after` clause, so it MUST be listed
 		// ahead of every session-consuming module here. Do not reorder.
-		sessionStoreModule,
+		//
+		// #474: built from `config` rather than the static manifest, so that
+		// `session.storage.type = "memory"` declares itself replica-unsafe and
+		// `deployment.mode = "multi"` refuses it by name like the other stores.
+		sessionStoreModuleFor(config),
 		oauthModule({ config }),
 		oauthSessionModule({ config }),
 		oauthAuthorizationModule({ config }),
@@ -220,11 +258,11 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// actually needs Redis. Memory-only deployments skip this so they
 		// don't open an unused socket.
 		...(usingRedisAnywhere ? [standaloneRedisClientsModule] : []),
-		// Federation-token store — always wired; independent of the
-		// `userSessionStores.adapter` switch. Was bundled into `storesModule`
-		// pre-Wave-5d; split so the redis session-stores branch doesn't
-		// drop the provider.
-		federationTokenStoreModule,
+		// Federation-token store: redis (multi-replica) or memory (dev). Always
+		// wired, independent of the `userSessionStores.adapter` switch — it was
+		// bundled into `storesModule` pre-Wave-5d, and the redis session-stores
+		// branch dropped the provider.
+		...federationTokenStoreModules,
 		// User-session-store family: redis (multi-replica) or memory (dev).
 		...sessionStoresModules,
 		// OAuth-endpoint rate limiter: redis (shared counters) or memory.