@o3co/create-auth-provider 0.5.1 → 0.5.3

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

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { readFileSync } from "node:fs";
 import {
 	type AppConfig,
 	createApp,
@@ -21,15 +22,17 @@ import {
 	defineModule,
 	generateToken,
 	InMemoryClientRepository,
-	InMemoryCodeRepository,
 	InMemoryUserRepository,
+	memoryRefreshTokenFamilyStoreModule,
 	registerBuiltinKeyStores,
 } from "@o3co/auth-provider-core";
 import express from "express";
 import request from "supertest";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildModules } from "../buildModules.mjs";
 
+const dockerfile = readFileSync(new URL("../../Dockerfile", import.meta.url), "utf8");
+
 const config: AppConfig = {
 	http: { port: 0, trustProxy: false },
 	oauth: {
@@ -40,16 +43,27 @@ const config: AppConfig = {
 					algorithm: "HS256",
 					secret: "test-secret-for-smoke-test",
 					kid: "v0",
-					previousKeys: [],
+					previousSecrets: [],
 				},
 			},
 		},
 		accessToken: { expiresIn: 3600 },
-		refreshToken: { expiresIn: 86400 },
+		refreshToken: {
+			expiresIn: 86400,
+			unknownFamilyPolicy: "reject" as const,
+			legacyRtPolicy: "reject" as const,
+		},
 		grants: {},
+		oidcMode: "oidc-required",
+		// OR-9: explicit memory adapter for the smoke test. The legacy
+		// `repositories.code.type` fallback would also pick memory here,
+		// but the explicit setting documents the intent and avoids
+		// console.warn deprecation noise in the test output.
+		code: { adapter: "memory" as const },
 	},
 	session: {
 		secret: "test-session-secret",
+		name: "auth.sid",
 		maxAge: 3600000,
 		secure: false,
 		sameSite: "lax",
@@ -58,6 +72,7 @@ const config: AppConfig = {
 	},
 	rateLimit: {
 		login: { windowMs: 60000, limit: 10 },
+		failMode: "open",
 	},
 	federations: {
 		google: { enabled: false },
@@ -69,8 +84,6 @@ const config: AppConfig = {
 	},
 	endpoints: {
 		login: { url: "/login" },
-		client: { url: undefined },
-		authCallback: { url: undefined },
 	},
 	cors: { allowedOrigins: [] },
 };
@@ -79,13 +92,50 @@ const config: AppConfig = {
  * Test-only repository module — bypasses the file-system-backed repositories
  * that `repositoriesModule` provides in production. Smoke tests use in-memory
  * empty repositories to verify the boot pipeline shape, not the data layer.
+ *
+ * Post-OR-9 (Wave 5d): `codeRepository` is no longer provided here — it is
+ * wired by `inMemoryCodeRepositoryModule` (or `redisCodeRepositoryModule`)
+ * via the `oauth.code.adapter` switch in `buildModules`. The smoke test
+ * config sets `oauth.code.adapter = "memory"`, so `inMemoryCodeRepositoryModule`
+ * is added automatically and provides the slot.
+ *
+ * D-6 (v0.5.1): a single confidential client is registered so the
+ * `clientAuthMw` middleware in front of `/oauth/token` has a record to
+ * authenticate against. Smoke tests that hit `/oauth/token` send
+ * `Authorization: ${SMOKE_BASIC_AUTH}`.
  */
+const SMOKE_CLIENT_ID = "smoke-client";
+const SMOKE_CLIENT_SECRET = "smoke-secret";
+const SMOKE_BASIC_AUTH = `Basic ${Buffer.from(`${SMOKE_CLIENT_ID}:${SMOKE_CLIENT_SECRET}`).toString("base64")}`;
+
 const testRepositoriesModule = defineModule({
 	name: "test:repositories",
 	provides: {
-		clientRepository: () => new InMemoryClientRepository(new Map()),
+		// `InMemoryClientRepository` constructor parameter `Map<string, ClientEntry>`
+		// uses `ClientEntry = z.infer<typeof ClientEntrySchema>` (the schema's
+		// OUTPUT type) — fields with `.default(...)` are non-optional in the
+		// output even though they are optional on input. The fixture supplies
+		// every field explicitly so the literal satisfies the output shape
+		// without requiring a cast.
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						SMOKE_CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: SMOKE_CLIENT_SECRET,
+							allowedRedirectUris: [],
+							allowedScopes: [],
+							allowedAudiences: [],
+							backchannelLogoutSessionRequired: true,
+							frontchannelLogoutSessionRequired: true,
+							allowedAzpForFederationToken: false,
+						},
+					],
+				]),
+			),
 		userRepository: () => new InMemoryUserRepository(new Map()),
-		codeRepository: () => new InMemoryCodeRepository(),
 	},
 });
 
@@ -112,6 +162,12 @@ describe("standalone smoke test", () => {
 			modules: buildModules(config, {
 				keyStoreModule: testKeyStoreModule,
 				repositoriesModule: testRepositoriesModule,
+				// D-2 v2: smoke tests stay in-memory for the RT family store.
+				// Production composition root pairs `refreshTokenFamilyClientModule`
+				// with `redisRefreshTokenFamilyStoreModule`; this override replaces
+				// the pair entirely with a single memory-backed store module so no
+				// real ioredis connection is opened during CI unit tests.
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
 			}),
 			bootstrapComponents: { config, pathResolver: (s) => s },
 		});
@@ -129,6 +185,36 @@ describe("standalone smoke test", () => {
 		handleRef = undefined;
 	});
 
+	it("Dockerfile declares runtime metadata and runs install/build steps as node", () => {
+		// Default port is 3000 but the HEALTHCHECK and EXPOSE must read it
+		// from ${HTTP_PORT} so an operator overriding the env var keeps the
+		// app, EXPOSE metadata, and healthcheck in sync. Assert the ENV /
+		// EXPOSE / HEALTHCHECK structure rather than the literal port so the
+		// test is not brittle when operators or downstream forks change the
+		// default.
+		// The literal `${HTTP_PORT}` token from the Dockerfile is split across
+		// concatenations to sidestep biome's `noTemplateCurlyInString` rule
+		// (it cannot statically tell that this string is intentionally NOT
+		// a JS template placeholder — it is a Dockerfile env-substitution).
+		const HTTP_PORT_VAR = `$${"{"}HTTP_PORT}`;
+		expect(dockerfile).toContain("ENV HTTP_PORT=3000");
+		expect(dockerfile).toContain(`EXPOSE ${HTTP_PORT_VAR}`);
+		expect(dockerfile).toMatch(
+			/HEALTHCHECK\s+--interval=30s\s+--timeout=3s\s+--start-period=10s\s+--retries=3/,
+		);
+		// Match the literal `${HTTP_PORT}` token inside the HEALTHCHECK CMD.
+		// `[$]` (character class) sidesteps biome's `noTemplateCurlyInString`
+		// false-positive without changing what we actually accept.
+		expect(dockerfile).toMatch(
+			/CMD\s+wget\s+-q\s+-O\s+\/dev\/null\s+"http:\/\/localhost:[$]\{HTTP_PORT\}\/_healthcheck"\s+\|\|\s+exit\s+1/,
+		);
+		expect(dockerfile).toMatch(/FROM node-base AS deps[\s\S]*USER node[\s\S]*RUN pnpm install/);
+		expect(dockerfile).toMatch(/FROM deps AS builder[\s\S]*USER node[\s\S]*RUN pnpm run build/);
+		expect(dockerfile).toMatch(
+			/FROM node-base AS runtime[\s\S]*USER node[\s\S]*RUN pnpm install --prod/,
+		);
+	});
+
 	it("GET /_healthcheck returns 200", async () => {
 		const { app, handle } = await buildApp();
 		handleRef = handle;
@@ -141,6 +227,7 @@ describe("standalone smoke test", () => {
 		handleRef = handle;
 		const res = await request(app)
 			.post("/oauth/token")
+			.set("Authorization", SMOKE_BASIC_AUTH)
 			.type("form")
 			.send({ grant_type: "unsupported" });
 		expect(res.status).toBe(400);
@@ -151,6 +238,7 @@ describe("standalone smoke test", () => {
 		handleRef = handle;
 		const res = await request(app)
 			.post("/oauth/token")
+			.set("Authorization", SMOKE_BASIC_AUTH)
 			.type("form")
 			.send({ grant_type: "unsupported" });
 		expect(res.status).toBe(400);
@@ -173,6 +261,7 @@ describe("standalone smoke test", () => {
 		const modules = buildModules(config, {
 			keyStoreModule: testKeyStoreModule,
 			repositoriesModule: testRepositoriesModule,
+			refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
 		});
 		const moduleNames = modules.map((m) => m.name);
 		expect(moduleNames).not.toContain("federation:google");
@@ -186,6 +275,161 @@ describe("standalone smoke test", () => {
 		expect(handle).toBeDefined();
 	});
 
+	// D-2 v2 / OR-1 closure: the standalone composition root must default to the
+	// Redis-backed RT family store + ioredis client module pair, NOT the
+	// in-memory store. Multi-replica deployments lose RT family persistence
+	// when each replica holds families in-process; this test guards the
+	// production default. The override path is exercised by the smoke tests
+	// above (which substitute the memory store for CI).
+	describe("D-2 v2 + Wave 5d: redis-clients + adapter wiring", () => {
+		it("buildModules includes the shared redis-clients module + redis store by default", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+			});
+			const names = modules.map((m) => m.name);
+			// Wave 5d: single shared ioredis client module (was per-purpose
+			// `standalone:refresh-token-family-client` in PR1).
+			expect(names).toContain("standalone:redis-clients");
+			expect(names).toContain("redis-refresh-token-family-store");
+			expect(names).not.toContain("core-refresh-token-family-store-memory");
+		});
+
+		it("buildModules drops the shared redis-clients module when override forces memory-only", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("core-refresh-token-family-store-memory");
+			expect(names).not.toContain("standalone:redis-clients");
+			expect(names).not.toContain("redis-refresh-token-family-store");
+		});
+
+		it("buildModules wires memoryRateLimiterModule by default (closes IH-14)", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("core-rate-limiter-memory");
+			expect(names).not.toContain("redis-rate-limiter");
+		});
+
+		it("buildModules switches to redisRateLimiterModule when rateLimiter.adapter = 'redis'", () => {
+			const redisRlConfig = {
+				...config,
+				rateLimiter: { adapter: "redis" as const },
+			};
+			const modules = buildModules(redisRlConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redis-rate-limiter");
+			expect(names).not.toContain("core-rate-limiter-memory");
+			// Adapter = redis pulls in the shared redis-clients module too.
+			expect(names).toContain("standalone:redis-clients");
+		});
+
+		it("buildModules switches to redisSessionStoresModule when userSessionStores.adapter = 'redis'", () => {
+			const redisSessConfig = {
+				...config,
+				userSessionStores: { adapter: "redis" as const },
+			};
+			const modules = buildModules(redisSessConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redisSessionStores");
+			expect(names).not.toContain("standalone:stores");
+			expect(names).toContain("standalone:redis-clients");
+		});
+	});
+
+	// OR-9 (Wave 5d): adapter switch for the OAuth code repository. Closes
+	// the deferred Phase 10 module-pattern wrapper for `codeRepository`. The
+	// memory branch wires `inMemoryCodeRepositoryModule`; the redis branch
+	// wires `redisCodeRepositoryModule` against the shared ioredis socket
+	// (same `standaloneRedisClientsModule` as the RT family / rate limiter).
+	describe("OR-9: code-repository adapter wiring", () => {
+		it("buildModules wires inMemoryCodeRepositoryModule by default (oauth.code.adapter = 'memory')", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("standalone:in-memory-code-repository");
+			expect(names).not.toContain("redis-code-repository");
+		});
+
+		it("buildModules switches to redisCodeRepositoryModule when oauth.code.adapter = 'redis'", () => {
+			const redisCodeConfig = {
+				...config,
+				oauth: { ...config.oauth, code: { adapter: "redis" as const } },
+			};
+			const modules = buildModules(redisCodeConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redis-code-repository");
+			expect(names).not.toContain("standalone:in-memory-code-repository");
+			// adapter = "redis" pulls in the shared ioredis socket so the
+			// `codeRepositoryClient` slot is satisfied.
+			expect(names).toContain("standalone:redis-clients");
+		});
+
+		it("buildModules honors legacy repositories.code.type='redis' with deprecation warn when oauth.code.adapter is absent", () => {
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+			try {
+				const legacyConfig = {
+					...config,
+					oauth: { ...config.oauth, code: undefined },
+					repositories: {
+						...config.repositories,
+						code: { type: "redis" as const, defaultExpiresIn: 600 },
+					},
+				};
+				const modules = buildModules(legacyConfig, {
+					keyStoreModule: testKeyStoreModule,
+					repositoriesModule: testRepositoriesModule,
+					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+				});
+				const names = modules.map((m) => m.name);
+				expect(names).toContain("redis-code-repository");
+				expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("repositories.code.type"));
+			} finally {
+				warnSpy.mockRestore();
+			}
+		});
+
+		it("buildModules has only ONE codeRepository provider in the manifest (no slot collision)", () => {
+			// Regression guard: `repositoriesModule` must NOT provide
+			// `codeRepository` post-OR-9 — the slot is owned by
+			// `inMemoryCodeRepositoryModule` or `redisCodeRepositoryModule`
+			// exclusively, selected via `oauth.code.adapter`.
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				// Use the production repositoriesModule (not the test override)
+				// so we exercise its post-OR-9 provides-shape.
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const codeRepoProviders = modules.filter((m) =>
+				Object.keys(m.provides ?? {}).includes("codeRepository"),
+			);
+			expect(codeRepoProviders).toHaveLength(1);
+			expect(codeRepoProviders[0]?.name).toBe("standalone:in-memory-code-repository");
+		});
+	});
+
 	it("POST /oauth/introspect returns iat in active token response", async () => {
 		const { app, handle } = await buildApp();
 		handleRef = handle;

package/templates/standalone/src/app.mts

@@ -16,14 +16,9 @@
 import { fileURLToPath } from "node:url";
 import { gracefulShutdown } from "@o3co/auth.utils";
 import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
-import {
-	createSessionStoreFactory,
-	registerBuiltinSessionStores,
-} from "@o3co/auth-provider-session";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import express from "express";
-import session from "express-session";
 import helmet from "helmet";
 
 import logger from "#/logger.mjs";
@@ -56,36 +51,14 @@ await (async (): Promise<void> => {
 		}),
 	);
 
-	// Step 3: Build the Express session store and mount express-session.
-	// (express-session is host-environment middleware, not part of the auth
-	// boot pipeline — wired before createApp so it sits ahead of the router.)
-	const sessionStoreFactory = createSessionStoreFactory();
-	registerBuiltinSessionStores(sessionStoreFactory);
-	const sessionStorageSlice = config.session.storage as {
-		type: string;
-	} & Record<string, unknown>;
-	const sessionStore = await sessionStoreFactory.create({
-		type: sessionStorageSlice.type,
-		...((sessionStorageSlice[sessionStorageSlice.type] ?? {}) as Record<string, unknown>),
-	});
-	app.use(
-		session({
-			secret: config.session.secret,
-			resave: false,
-			saveUninitialized: false,
-			store: sessionStore,
-			cookie: {
-				path: "/",
-				httpOnly: true,
-				secure: config.session.secure,
-				maxAge: config.session.maxAge,
-				sameSite: config.session.sameSite,
-				domain: config.session.domain || undefined,
-			},
-		}),
-	);
-
-	// Step 4: Boot the auth pipeline. bootstrapComponents carries only host-
+	// Step 3: Boot the auth pipeline.
+	// D-5: express-session middleware is now wired by `sessionStoreModule`
+	// inside the boot planner. Mount order is enforced by declarationIndex
+	// tie-breaking — sessionStoreModule MUST come first in `buildModules(...)`
+	// so the middleware initialises `req.session` for every downstream route.
+	// The connect-redis client's lifetime is owned by the planner via
+	// `BuilderContext.lifecycle` and drained on `handle.dispose()`.
+	// bootstrapComponents carries only host-
 	// environment values (config + pathResolver per A2-γ §4 worked example);
 	// every other component flows through composition-root-local modules.
 	// `buildModules` is the single source of truth for the module list — it
@@ -99,20 +72,20 @@ await (async (): Promise<void> => {
 		},
 	});
 
-	// Step 5: Wire host-level routes (healthcheck) before the auth router so
+	// Step 4: Wire host-level routes (healthcheck) before the auth router so
 	// they remain reachable even when the auth pipeline is degraded.
 	app.get("/_healthcheck", (_req, res) => {
 		res.status(200).json({ status: "ok" });
 	});
 
-	// Step 6: Mount the composed auth router and start the HTTP server.
+	// Step 5: Mount the composed auth router and start the HTTP server.
 	app.use(handle.router);
 	const server = app.listen(config.http.port, (): void => {
 		logger.info(`Server is running on http://localhost:${config.http.port}`);
 	});
 
-	// Step 7: Graceful shutdown — handle.dispose() runs reverse-topological
-	// per-component cleanup (per A2-β §8.1). Replaces the v0.4.x
-	// grantRegistry.cleanup() bridge.
+	// 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());
 })();

package/templates/standalone/src/buildModules.mts

@@ -18,7 +18,7 @@ import {
 	defaultRefreshTokenFamilyRevocationModule,
 	defaultRefreshTokenFamilyRotationModule,
 	type Module,
-	memoryRefreshTokenFamilyStoreModule,
+	memoryRateLimiterModule,
 } from "@o3co/auth-provider-core";
 import { googleFederationModule } from "@o3co/auth-provider-federation-google";
 import {
@@ -26,12 +26,21 @@ import {
 	oauthModule,
 	oauthSessionModule,
 } from "@o3co/auth-provider-oauth";
-import { sessionModule } from "@o3co/auth-provider-session";
 import {
+	redisCodeRepositoryModule,
+	redisRateLimiterModule,
+	redisRefreshTokenFamilyStoreModule,
+	redisSessionStoresModule,
+} from "@o3co/auth-provider-redis";
+import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
+import {
+	federationTokenStoreModule,
 	googleFederationConfigModule,
+	inMemoryCodeRepositoryModule,
+	inMemorySessionStoresModule,
 	keyStoreModule,
 	repositoriesModule,
-	storesModule,
+	standaloneRedisClientsModule,
 } from "./modules.mjs";
 
 /**
@@ -43,6 +52,18 @@ export interface BuildModulesOverrides {
 	readonly keyStoreModule?: Module;
 	readonly repositoriesModule?: Module;
 	readonly storesModule?: Module;
+	/**
+	 * D-2 v2 / Wave 5d: override the RT family store module + (when adapter
+	 * is `"redis"`) the bundled redis-clients + redis-store pair. Default
+	 * production manifest is `[standaloneRedisClientsModule, redisRefreshTokenFamilyStoreModule]`
+	 * (single shared ioredis socket per replica via the F4 PR2 unification).
+	 *
+	 * Smoke tests / unit tests that don't want to open an ioredis connection
+	 * pass `[memoryRefreshTokenFamilyStoreModule]` here. The override REPLACES
+	 * the entire group — when the override is provided, `standaloneRedisClientsModule`
+	 * is dropped from the manifest unless the override list includes it.
+	 */
+	readonly refreshTokenFamilyModules?: readonly Module[];
 }
 
 /**
@@ -62,7 +83,85 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	const googleEnabled =
 		(config.federations?.google as { enabled?: boolean } | undefined)?.enabled === true;
 
+	// Wave 5d (IH-14 + OR-M1 + OR-4) + OR-9: adapter-driven branching for
+	// the OAuth-endpoint rate limiter, the user-session-store family, AND
+	// the OAuth code repository. The RT family store always uses Redis in
+	// the production manifest (D-2 v2 / OR-1) unless
+	// `overrides.refreshTokenFamilyModules` swaps it out. When ANY consumer
+	// adapter is `"redis"` (or the RT family override includes a
+	// Redis-backed store module), the shared `standaloneRedisClientsModule`
+	// is added once and provides every per-purpose ComponentMap slot from a
+	// single ioredis socket per replica. Memory-only deployments skip it.
+	const rateLimiterAdapter = config.rateLimiter?.adapter ?? "memory";
+	const userSessionStoresAdapter = config.userSessionStores?.adapter ?? "memory";
+
+	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
+	// authoritative switch; the legacy `repositories.code.type = "redis"`
+	// path is honored for one release with a deprecation warn so existing
+	// operators relying on `CLIENT_CODE_TYPE=redis` env-var overrides keep
+	// working until they migrate. Removed in v0.6.
+	const oauthCodeAdapter = config.oauth?.code?.adapter;
+	const legacyCodeType = (config.repositories?.code as { type?: string } | undefined)?.type;
+	let codeRepositoryAdapter: "memory" | "redis";
+	if (oauthCodeAdapter !== undefined) {
+		codeRepositoryAdapter = oauthCodeAdapter;
+	} else if (legacyCodeType === "redis") {
+		console.warn(
+			'[buildModules] `repositories.code.type = "redis"` is deprecated; use ' +
+				'`oauth.code.adapter = "redis"` instead (will be removed in v0.6).',
+		);
+		codeRepositoryAdapter = "redis";
+	} else {
+		codeRepositoryAdapter = "memory";
+	}
+
+	const refreshTokenFamilyModules: readonly Module[] = overrides.refreshTokenFamilyModules ?? [
+		redisRefreshTokenFamilyStoreModule,
+	];
+	// Detect whether the RT-family override (if any) keeps the Redis-backed
+	// store. Default (no override) uses Redis. An override that includes the
+	// Redis store module without also wiring `standaloneRedisClientsModule`
+	// would otherwise boot-fail on the missing `refreshTokenFamilyClient`
+	// component (Copilot review on PR #121).
+	const refreshTokenFamilyUsesRedis = refreshTokenFamilyModules.some(
+		(m) => m.name === "redis-refresh-token-family-store",
+	);
+	const usingRedisAnywhere =
+		refreshTokenFamilyUsesRedis ||
+		rateLimiterAdapter === "redis" ||
+		userSessionStoresAdapter === "redis" ||
+		codeRepositoryAdapter === "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.
+	const sessionStoresModules: Module[] =
+		userSessionStoresAdapter === "redis"
+			? [redisSessionStoresModule]
+			: overrides.storesModule
+				? [overrides.storesModule]
+				: [inMemorySessionStoresModule];
+
+	const rateLimiterModules: Module[] =
+		rateLimiterAdapter === "redis" ? [redisRateLimiterModule] : [memoryRateLimiterModule];
+
+	// OR-9: code-repository module — mutually exclusive memory/redis pair.
+	// Same pattern as sessionStoresModules + rateLimiterModules. The two
+	// modules provide the same `codeRepository` slot; including both would
+	// be a boot-time slot collision.
+	const codeRepositoryModules: Module[] =
+		codeRepositoryAdapter === "redis"
+			? [redisCodeRepositoryModule]
+			: [inMemoryCodeRepositoryModule];
+
 	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,
 		oauthModule({ config }),
 		oauthSessionModule({ config }),
 		oauthAuthorizationModule({ config }),
@@ -70,8 +169,24 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
 		overrides.keyStoreModule ?? keyStoreModule,
 		overrides.repositoriesModule ?? repositoriesModule,
-		overrides.storesModule ?? storesModule,
-		memoryRefreshTokenFamilyStoreModule,
+		// Shared ioredis clients — only when at least one consumer adapter
+		// 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,
+		// User-session-store family: redis (multi-replica) or memory (dev).
+		...sessionStoresModules,
+		// OAuth-endpoint rate limiter: redis (shared counters) or memory.
+		...rateLimiterModules,
+		// OAuth code repository: redis (multi-replica) or memory (single-instance).
+		...codeRepositoryModules,
+		// RT family store: redis by default (closes OR-1); override path
+		// swaps to `[memoryRefreshTokenFamilyStoreModule]` for unit tests.
+		...refreshTokenFamilyModules,
 		defaultRefreshTokenFamilyRotationModule,
 		defaultRefreshTokenFamilyRevocationModule,
 	];