@o3co/create-auth-provider 0.15.0 → 0.16.0

package/templates/standalone/src/__tests__/store-credential.test.mts

@@ -0,0 +1,276 @@
+/*
+ * 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 credential auth.provider presents to the Store, through the shipped
+ * composition: `CLIENT_USER_BEARER_TOKEN` in the environment → the HOCON
+ * layers → `AppConfigSchema` → the production `repositoriesModule` → the
+ * `"http"` user adapter → the `Authorization` header a real `node:http` Store
+ * receives. Unset, the Store receives no `Authorization` header; set blank —
+ * an exported-but-empty variable — the user repository is refused.
+ *
+ * And what a mismatch looks like from outside, with the app booted from the
+ * shipped config through `createApp`: a Store that refuses the token with a
+ * `401` and a `Bearer` challenge turns `POST /session/login` into a `503`
+ * whose log line names the refused credential and never the token; a `401`
+ * without the challenge is still a wrong password.
+ */
+
+import { createServer, type OutgoingHttpHeaders, type Server } from "node:http";
+import { fileURLToPath } from "node:url";
+import { inspect } from "node:util";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	type Logger,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+	type UserRepository,
+} from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+import { repositoriesModule } from "../modules.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/** 32 bytes of key material — what `openssl rand -hex 32` prints. */
+const TOKEN = "7d1f0c3b9a5e2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f";
+
+let servers: Server[] = [];
+afterEach(async () => {
+	await Promise.all(
+		servers.map((server) => {
+			server.closeAllConnections();
+			return new Promise<void>((resolve) => server.close(() => resolve()));
+		}),
+	);
+	servers = [];
+});
+
+/** How the Store answers every request. */
+interface StoreAnswer {
+	readonly status: number;
+	readonly headers?: OutgoingHttpHeaders;
+	readonly body: unknown;
+}
+
+const USER: StoreAnswer = { status: 200, body: { id: "user-1", username: "alice" } };
+
+/** A Store on its own loopback port that records each request's Authorization header. */
+const recordingStore = async (
+	answer: StoreAnswer = USER,
+): Promise<{ origin: string; heard: (string | undefined)[] }> => {
+	const heard: (string | undefined)[] = [];
+	const server = createServer((req, res) => {
+		req.resume();
+		req.on("end", () => {
+			heard.push(req.headers.authorization);
+			res.writeHead(answer.status, { "Content-Type": "application/json", ...answer.headers });
+			res.end(JSON.stringify(answer.body));
+		});
+	});
+	servers.push(server);
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const { port } = server.address() as { port: number };
+	return { origin: `http://127.0.0.1:${port}`, heard };
+};
+
+/** The shipped config for the production overlay, resolved against `env`. */
+const resolve = (env: Record<string, string>): AppConfig => {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	return validate(
+		parseFile(envConfPath, { env })
+			.withFallback(parseFile(applicationConfPath, { env }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env })),
+		AppConfigSchema,
+	);
+};
+
+/** The user repository the production `repositoriesModule` builds from `config`. */
+const userRepositoryFrom = (config: AppConfig): Promise<UserRepository> =>
+	Promise.resolve(
+		repositoriesModule.provides?.userRepository?.({ config } as never) as
+			| UserRepository
+			| Promise<UserRepository>,
+	);
+
+const envFor = (origin: string): Record<string, string> => ({
+	OAUTH_JWT_ALGORITHM: "HS256",
+	OAUTH_JWT_SECRET: "store-credential-composition.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_SECRET: "store-credential-composition-session.at-least-32-bytes.ok",
+	CLIENT_USER_TYPE: "http",
+	CLIENT_USER_AUTHENTICATE_URL: `${origin}/authenticate`,
+	CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL: `${origin}/authenticate-by-token`,
+});
+
+describe("CLIENT_USER_BEARER_TOKEN reaches the Store through the shipped composition", () => {
+	it("sends Authorization: Bearer <token> on every Store call when the variable is set", async () => {
+		const { origin, heard } = await recordingStore();
+		const repo = await userRepositoryFrom(
+			resolve({ ...envFor(origin), CLIENT_USER_BEARER_TOKEN: TOKEN }),
+		);
+
+		await repo.authenticate("alice", "pass");
+		await repo.authenticateByToken("apple:a1");
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`, `Bearer ${TOKEN}`]);
+	});
+
+	it("sends no Authorization header when the variable is unset", async () => {
+		const { origin, heard } = await recordingStore();
+		const repo = await userRepositoryFrom(resolve(envFor(origin)));
+
+		await repo.authenticate("alice", "pass");
+
+		expect(heard).toEqual([undefined]);
+	});
+
+	it("refuses the user repository when the variable is exported but empty", async () => {
+		const { origin, heard } = await recordingStore();
+		const config = resolve({ ...envFor(origin), CLIENT_USER_BEARER_TOKEN: "" });
+
+		await expect(userRepositoryFrom(config)).rejects.toThrow(/"bearerToken" must not be empty/);
+		expect(heard).toEqual([]);
+	});
+});
+
+describe("a token the Store refuses, seen from outside the booted app", () => {
+	/** Every store on memory, so the boot opens no socket but the Store's. */
+	const MEMORY_ENV: Readonly<Record<string, string>> = {
+		SESSION_SECURE: "false",
+		SESSION_NAME: "auth.session",
+		SESSION_STORAGE_TYPE: "memory",
+		USER_SESSION_STORES_ADAPTER: "memory",
+		RATE_LIMITER_ADAPTER: "memory",
+		OAUTH_CODE_ADAPTER: "memory",
+		ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+		REPLAY_SEEN_SET_ADAPTER: "memory",
+		FEDERATION_TOKEN_STORE_TYPE: "memory",
+		CONSENT_STORE_ADAPTER: "none",
+		FEDERATION_GRANT_STORE_ADAPTER: "memory",
+		FEDERATION_GRANT_INTENT_STORE_ADAPTER: "memory",
+	};
+
+	const testKeyStoreModule = defineModule({
+		name: "test:key-store",
+		requires: ["config"] as const,
+		provides: {
+			keyStore: async ({ config: c }) => {
+				const factory = createKeyStoreFactory();
+				registerBuiltinKeyStores(factory);
+				return factory.create({
+					type: "local",
+					...((c as AppConfig).oauth.jwt.signingKey.local ?? {}),
+				});
+			},
+		},
+	});
+
+	/** Every log call, as the arguments it was made with. */
+	const capturingLogger = (): { logger: Logger; lines: { level: string; args: unknown[] }[] } => {
+		const lines: { level: string; args: unknown[] }[] = [];
+		const at =
+			(level: string) =>
+			(...args: unknown[]): void => {
+				lines.push({ level, args });
+			};
+		const logger = {
+			trace: at("trace"),
+			debug: at("debug"),
+			info: at("info"),
+			warn: at("warn"),
+			error: at("error"),
+			fatal: at("fatal"),
+			child: () => logger,
+		} as Logger;
+		return { logger, lines };
+	};
+
+	let handleRef: Awaited<ReturnType<typeof createApp>> | undefined;
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	/**
+	 * The shipped config against a Store answering `answer`, booted with the
+	 * production repositories module; then a real browser login — a CSRF pair,
+	 * then the form post.
+	 */
+	const logInAgainst = async (answer: StoreAnswer) => {
+		const { origin, heard } = await recordingStore(answer);
+		const config = resolve({ ...envFor(origin), ...MEMORY_ENV, CLIENT_USER_BEARER_TOKEN: TOKEN });
+		const { logger, lines } = capturingLogger();
+		handleRef = await createApp({
+			modules: buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			bootstrapComponents: { config, pathResolver: (s: string) => s, logger },
+		});
+		const app = express().use(handleRef.router);
+
+		const csrf = await request(app).get("/session/csrf");
+		expect(csrf.status).toBe(200);
+		const login = await request(app)
+			.post("/session/login")
+			.set("Cookie", csrf.headers["set-cookie"] as unknown as string[])
+			.set(csrf.body.header_name as string, csrf.body.csrf_token as string)
+			.type("form")
+			.send({ username: "alice", password: "correct-horse-battery-staple" });
+		const logged = lines.map((line) =>
+			inspect(line, { depth: Number.POSITIVE_INFINITY, showHidden: true }),
+		);
+		return { login, heard, logged };
+	};
+
+	it("answers the login 503 and logs the refused credential by name, never the token", async () => {
+		const { login, heard, logged } = await logInAgainst({
+			status: 401,
+			headers: { "WWW-Authenticate": 'Bearer error="invalid_token"' },
+			body: { error: "invalid_token" },
+		});
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`]);
+		expect(login.status).toBe(503);
+		expect(login.body.error).toBe("temporarily_unavailable");
+		expect(logged.filter((line) => /refused this deployment's credential/.test(line))).toHaveLength(
+			1,
+		);
+		expect(logged.filter((line) => line.includes(TOKEN))).toEqual([]);
+	});
+
+	it("still answers a 401 without the challenge as a wrong password", async () => {
+		const { login, heard, logged } = await logInAgainst({
+			status: 401,
+			body: { error: "invalid_credentials" },
+		});
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`]);
+		expect(login.status).toBe(401);
+		expect(login.body.error).toBe("invalid_credentials");
+		expect(logged.filter((line) => /refused this deployment's credential/.test(line))).toEqual([]);
+	});
+});

package/templates/standalone/src/app.mts

@@ -14,23 +14,18 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import {
-	type AppConfig,
-	AppConfigSchema,
-	createApp,
-	createHealthcheckRouter,
-	createReadinessRouter,
-} from "@o3co/auth-provider-core";
+import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import express from "express";
 import helmet from "helmet";
 import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
+import { listen } from "./listen.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
+import { mountRoutes } from "./routes.mjs";
 import { cleanupAllowanceFor, installGracefulShutdown } from "./shutdown.mjs";
-import { createTerminalErrorHandler } from "./terminalError.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
 // ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
@@ -103,8 +98,10 @@ await (async (): Promise<void> => {
 	// `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.
+	// `logger` is where the composition's own notices go (a deprecated config
+	// key), the same logger every module gets through the slot below.
 	const handle = await createApp({
-		modules: buildModules(config, { environment: env }),
+		modules: buildModules(config, { environment: env, logger }),
 		bootstrapComponents: {
 			config,
 			pathResolver: import.meta.resolve,
@@ -112,48 +109,22 @@ await (async (): Promise<void> => {
 		},
 	});
 
-	// Step 4: Wire host-level routes before the auth router so they remain
-	// reachable even when the auth pipeline is degraded — which is exactly when
-	// an operator needs an answer from them.
-	//
-	// Liveness: the process is up and its event loop is turning. Deliberately
-	// static — restarting the process would not bring Redis back, so a Redis
-	// outage must not read as "this container is broken, kill it".
-	app.use(createHealthcheckRouter(express));
-
-	// Readiness: can this replica serve right now? Redis backs sessions,
-	// authorization codes and refresh-token families in the deployable
-	// defaults, so a replica that has lost it answers 503 here and should be
-	// taken out of rotation. Probes are contributed by the builders that own
-	// each connection; a memory-only deployment registers none and is always
-	// ready.
-	app.use(
-		createReadinessRouter(express, {
-			probes: handle.readinessProbes,
-			timeoutMs: config.http.readinessTimeoutMs,
-			logger,
-		}),
-	);
-
-	// Prometheus scrape endpoint. Same reasoning as the probes above: it has to
-	// keep answering while the auth pipeline is degraded, because that is when
-	// the series matter.
-	app.use(
-		metrics.route(express, {
-			probes: handle.readinessProbes,
-			probeTimeoutMs: config.http.readinessTimeoutMs,
-		}),
-	);
-
-	// Step 5: Mount the composed auth router and start the HTTP server.
-	app.use(handle.router);
-	// Terminal error handler LAST (#293 item 8): Express routes an error only
-	// to handlers registered after the route that threw it. See
-	// `terminalError.mts` for what it catches and why.
-	app.use(createTerminalErrorHandler(logger));
-	const server = app.listen(config.http.port, (): void => {
-		logger.info(`Server is running on http://localhost:${config.http.port}`);
+	// Step 4: the host-level routes (liveness, readiness, metrics) ahead of the
+	// auth router so they remain reachable even when the auth pipeline is
+	// degraded — which is exactly when an operator needs an answer from them —
+	// then the composed auth router, then the terminal error handler. See
+	// `routes.mts` for what each is and why the order is what it is.
+	mountRoutes(app, {
+		router: handle.router,
+		probes: handle.readinessProbes,
+		readinessTimeoutMs: config.http.readinessTimeoutMs,
+		metrics,
+		logger,
 	});
+	// Step 5: start the HTTP server.
+	// Resolves once the socket is bound (`server_listening`); a port that
+	// cannot be bound rejects, and boot fails with that error (`listen.mts`).
+	const server = await listen(app, config.http.port, logger);
 
 	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
 	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain

package/templates/standalone/src/buildModules.mts

@@ -15,9 +15,11 @@
  */
 import {
 	type AppConfig,
+	consoleLogger,
 	defaultRefreshTokenFamilyRevocationModule,
 	defaultRefreshTokenFamilyRotationModule,
 	jwksModule,
+	type Logger,
 	type Module,
 	memoryAccessTokenDenylistModule,
 	memoryConsentStoreModule,
@@ -65,10 +67,10 @@ import {
 } from "./modules.mjs";
 
 /**
- * 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.
+ * Overrides for the composition. All but `environment` and `logger` 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 {
 	/**
@@ -80,6 +82,12 @@ export interface BuildModulesOverrides {
 	 * off the config either way).
 	 */
 	readonly environment?: string;
+	/**
+	 * Where the composition's own notices go — a deprecated config key, one
+	 * `config_key_deprecated` line (warn) each. `app.mts` passes the logger it
+	 * hands every module; omitted, `consoleLogger`.
+	 */
+	readonly logger?: Logger;
 	readonly keyStoreModule?: Module;
 	readonly repositoriesModule?: Module;
 	readonly storesModule?: Module;
@@ -147,6 +155,7 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	const googleEnabled =
 		extractFederationSection(config.federations ?? {}, "google")?.type === "google";
 	const oidcFederations = oidcFederationNames(config.federations ?? {});
+	const logger = overrides.logger ?? consoleLogger;
 
 	// 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
@@ -208,9 +217,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	if (oauthCodeAdapter !== undefined) {
 		codeRepositoryAdapter = oauthCodeAdapter;
 	} else if (legacyCodeType === "redis") {
-		console.warn(
-			'[buildModules] `repositories.code.type = "redis"` is deprecated; use ' +
-				'`oauth.code.adapter = "redis"` instead — see CHANGELOG for the removal version.',
+		logger.warn(
+			{
+				key: "repositories.code.type",
+				env: "CLIENT_CODE_TYPE",
+				replacement: "oauth.code.adapter",
+				replacementEnv: "OAUTH_CODE_ADAPTER",
+			},
+			"config_key_deprecated",
 		);
 		codeRepositoryAdapter = "redis";
 	} else {
@@ -230,10 +244,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		accessToken.defaultExpiresIn === undefined &&
 		accessToken.expiresIn !== SHIPPED_ACCESS_TOKEN_EXPIRES_IN
 	) {
-		console.warn(
-			"[buildModules] `oauth.accessToken.expiresIn` (OAUTH_ACCESS_TOKEN_EXPIRES_IN) is " +
-				"deprecated; use `oauth.accessToken.defaultExpiresIn` " +
-				"(OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN) instead — see CHANGELOG for the removal version.",
+		logger.warn(
+			{
+				key: "oauth.accessToken.expiresIn",
+				env: "OAUTH_ACCESS_TOKEN_EXPIRES_IN",
+				replacement: "oauth.accessToken.defaultExpiresIn",
+				replacementEnv: "OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN",
+			},
+			"config_key_deprecated",
 		);
 	}
 
@@ -359,11 +377,10 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// `session.storage.type = "memory"` declares itself replica-unsafe and
 		// `deployment.mode = "multi"` refuses it by name like the other stores.
 		sessionStoreModuleFor(config),
-		// #593 slice 7: before `oauthModule`, whose router mounts under the same
-		// `/oauth` prefix with body parsers of its own — mounted after it, a
-		// malformed body would be refused by the OAuth router's parser without
-		// this package's request id, `Cache-Control: no-store` or throttle (the
-		// package README's mounting-order rule). The browser half sits after the
+		// #593 slice 7: the grants routes mount under `/oauth` beside
+		// `oauthModule`'s router, which parses the bodies of its own routes
+		// only, so each parses its own requests and their place relative to
+		// `oauthModule` does not matter. The browser half sits after the
 		// session middleware by its own `after`, wherever it is listed.
 		...(federationGrantsEnabled ? federationGrantsModules : []),
 		oauthModule({ config }),

package/templates/standalone/src/listen.mts

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { type Logger, loggableError } from "@o3co/auth-provider-core";
+import type { Express } from "express";
+
+/**
+ * Start the HTTP listener, and say so once it is bound.
+ *
+ * Resolves with the server once its socket is bound, after logging
+ * `server_listening` (info) with the port the socket holds — the configured
+ * one, or the one the OS picked for `0`. Rejects with the server's error when
+ * the socket cannot be bound (`EADDRINUSE`, `EACCES`), and logs nothing: the
+ * composition root awaits this, so the error ends boot the way any other boot
+ * failure does.
+ *
+ * The server is built here (`http.createServer(app)`, as `app.listen` itself
+ * does) and its events are wired here, so none of this rests on how a given
+ * Express version wires them. Until the socket is bound, one `error` listener
+ * turns a bind failure into the rejection. Once it is bound, that listener is
+ * removed and the server gets the one it keeps: a later `error` — an `accept`
+ * that fails with EMFILE — is logged as `server_error` (error, `err`: core's
+ * `loggableError` projection) and the process keeps running, the server
+ * accepting what it can. Without a listener of its own, such an error would be
+ * thrown out of the process.
+ *
+ * The standalone used to call `app.listen` with a callback that ignored its
+ * argument: Express 5 hands that callback the bind error too, so it announced
+ * a server on a port another process held and swallowed the error that should
+ * have ended the process.
+ */
+export function listen(app: Express, port: number, logger: Logger): Promise<Server> {
+	const server = createServer(app);
+	return new Promise((resolve, reject) => {
+		const refuse = (err: Error): void => {
+			server.off("listening", bound);
+			reject(err);
+		};
+		const bound = (): void => {
+			server.off("error", refuse);
+			server.on("error", (serverErr: Error) => {
+				logger.error({ err: loggableError(serverErr) }, "server_error");
+			});
+			const address = server.address() as AddressInfo | null;
+			logger.info({ port: address?.port ?? port }, "server_listening");
+			resolve(server);
+		};
+		server.once("error", refuse);
+		server.once("listening", bound);
+		server.listen(port);
+	});
+}

package/templates/standalone/src/logger.mts

@@ -44,10 +44,13 @@ export function createAppLogger(config: AppConfig): Logger {
 	return pino({
 		name: "provider",
 		level: config.logging.level,
-		// `err` is pino's conventional key for an Error, and every structured
-		// event in this stack uses it — `logger.error({ err }, "…_error")`.
-		// Without the serialiser an Error stringifies to `{}` and the stack is
-		// lost exactly where it is needed.
+		// `err` is pino's conventional key for an error, and every structured
+		// event in this stack uses it — `logger.error({ err: loggableError(err) },
+		// "…_error")`. Core's projection is plain data with no `message`, so
+		// this serialiser hands it through as it is, every cause's fields
+		// included. It is here for an Error handed to it as it is, which would
+		// otherwise stringify to `{}`, the stack lost exactly where it is
+		// needed.
 		serializers: { err: stdSerializers.err },
 	});
 }

package/templates/standalone/src/modules.mts

@@ -30,6 +30,7 @@ import {
 	defineModule,
 	type LifecycleRegistrar,
 	type Logger,
+	loggableError,
 	type Module,
 	type ReadinessRegistrar,
 	registerBuiltinAuditSinks,
@@ -370,7 +371,11 @@ export const storesModule: Module = defineModule({
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
  * subject-level revocation index + watermark + rate limiter + code
  * repository + access-token denylist + replay seen-set + federation token
- * store + device-code store + the consent stores).
+ * store + device-code store + WebAuthn challenge store + the consent stores),
+ * and the two federation-grant stores' clients from their own factories.
+ * Every store module `@o3co/auth-provider-redis` ships finds its client
+ * slot here, including the ones this template does not select — pinned by
+ * `all-modules-composition.multi.test.mts`.
  *
  * Per F4 PR1 (D-2 v2) + Wave 5d unification: the previous design opened a
  * separate ioredis socket per Redis-backed module (3+ sockets per replica).
@@ -396,11 +401,12 @@ export const storesModule: Module = defineModule({
  * the single connection cleanly.
  *
  * Conditional inclusion: `buildModules` only adds this module to the
- * manifest when at least one Redis-backed adapter is selected
- * (`userSessionStores.adapter = "redis"` OR `rateLimiter.adapter = "redis"`
- * — refresh-token-family is always Redis-backed in production). Adding the
- * module unconditionally would open an ioredis socket for memory-only
- * deployments.
+ * manifest when at least one composed module needs a Redis client
+ * (`usingRedisAnywhere` there): an adapter switch set to `"redis"` — the two
+ * federation-grant store switches only while `federationGrants.enabled` —
+ * and the refresh-token family store, which is Redis-backed unless a test
+ * override replaces it. Adding the module unconditionally would open an
+ * ioredis socket for memory-only compositions.
  */
 export const standaloneRedisClientsModule: Module = defineModule({
 	name: "standalone:redis-clients",
@@ -531,6 +537,15 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.deviceCodeStoreClient;
 		},
+		// The WebAuthn challenge store's client, off the same shared socket, for
+		// the reason the device-code slot above is here: this template does not
+		// mount WebAuthn, and a deployment that adds `webauthnModule` with
+		// `redisChallengeStoreModule` would otherwise be refused at boot for a
+		// `challengeStoreClient` nothing provided.
+		challengeStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.challengeStoreClient;
+		},
 		// #561: the consent stores' clients, off the same shared socket.
 		// `redisConsentStoreModule` requires both — it provides the consent
 		// records and the parked requests together — and `buildModules` selects
@@ -695,9 +710,11 @@ function getOrCreateClients(
 
 	// Attach an error handler so unhandled "error" events do not crash the
 	// process. Initial connection failures surface here; downstream adapter
-	// operations then fail visibly.
+	// operations then fail visibly. It logs the projection: ioredis puts the
+	// command a reply answered on the error, and for a refused handshake that
+	// is `AUTH` with the configured password.
 	io.on("error", (err: unknown) => {
-		logger.error({ err }, "standalone_redis_clients_error");
+		logger.error({ err: loggableError(err) }, "standalone_redis_clients_error");
 	});
 
 	lifecycleRegistrar?.register(async () => {
@@ -773,6 +790,20 @@ function optionalBoolean(
 	);
 }
 
+/**
+ * `accessType` from the `federations.google` slice: `"offline"` or `"online"`,
+ * exactly, or absent. `federation-google` refuses any other value too; this
+ * refuses it first, naming the key, as the fields above do.
+ */
+function optionalAccessType(
+	slice: Record<string, unknown>,
+): { accessType: "offline" | "online" } | Record<string, never> {
+	const value = slice.accessType;
+	if (value === undefined || value === null) return {};
+	if (value === "offline" || value === "online") return { accessType: value };
+	throw new Error('federations.google.accessType must be "offline" or "online" when present');
+}
+
 /**
  * Google federation config bridge — supplies the typed `googleFederationConfig`
  * ComponentMap slot from the `config.federations.google` slice.
@@ -841,6 +872,9 @@ export const googleFederationConfigModule: Module = defineModule({
 				...optionalString(slice, "clientUrl"),
 				// #597: absent means the provider's default, which is to require it.
 				...optionalBoolean(slice, "requireAuthorizationResponseIss"),
+				// Absent means the provider's default, "offline": consent on every
+				// sign-in, and a refresh token for every session.
+				...optionalAccessType(slice),
 			};
 		},
 	},