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

package/templates/standalone/src/modules.mts

@@ -15,7 +15,6 @@
  */
 import path from "node:path";
 import {
-	type AppConfig,
 	consoleLogger,
 	createAuditSinkFactory,
 	createFederationTokenStoreFactory,
@@ -28,6 +27,7 @@ import {
 	createKeyStoreFactory,
 	createRepositoryFactories,
 	defineModule,
+	federationsOf,
 	type LifecycleRegistrar,
 	type Logger,
 	loggableError,
@@ -46,25 +46,29 @@ import {
 	makeIoredisFederationGrantStoreClient,
 } from "@o3co/auth-provider-redis/ioredis";
 import { extractFederationSection } from "@o3co/auth-provider-session";
-// Named import is required here, not default. ioredis is CJS and its entry
-// does `module.exports = Redis` with the class re-exported as both `default`
-// and `Redis`; under `module: "nodenext"` with esModuleInterop the default
-// import therefore resolves to the module-exports namespace object rather
-// than the class, and `new Redis(...)` raises TS2351 "not constructable".
-// Still true on ioredis 6 — verified against 6.0.0, not inherited from the
-// ioredis 5 era this note was first written in.
-// The 11 default-import sites elsewhere in the repo all live under
-// `packages/redis/__tests__/` which `packages/redis/tsconfig.json`
-// explicitly excludes from strict tsc build (vitest's vue-tsc is more
-// permissive about CJS interop). Standalone production source is built
-// with strict nodenext, so the named import is the right shape here.
+// Named import, not default: ioredis is CJS (`module.exports = Redis`, the
+// class re-exported as both `default` and `Redis`), so under `module:
+// "nodenext"` with esModuleInterop the default import resolves to the
+// module-exports namespace object and `new Redis(...)` raises TS2351 "not
+// constructable". Verified against ioredis 6.0.0. The repo's default-import
+// sites live under `packages/redis/__tests__/`, which the strict tsc build
+// excludes.
 import { Redis } from "ioredis";
 import { createAuditLogger, createLoggerAuditSink } from "./logger.mjs";
+import {
+	type Adapters,
+	auditSinkSectionSchema,
+	httpSectionSchema,
+	inMemoryCodeRepositorySectionSchema,
+	keyStoreSectionSchema,
+	loggingSectionSchema,
+	redisClientsSectionSchema,
+	repositoriesSectionSchemaFor,
+} from "./sections.mjs";
 
 /**
- * Helper: turn a v0.4.x { type, [type]: {...} } adapter-config slice into the
- * flat `{ type, ...rest }` shape consumed by AdapterFactory<T>.create().
- *
+ * Turn a `{ type, [type]: {...} }` adapter-config slice into the flat
+ * `{ type, ...rest }` shape `AdapterFactory<T>.create()` consumes.
  * Composition-root concern; not a library export.
  */
 function flattenAdapterConfig(
@@ -85,188 +89,266 @@ function flattenAdapterConfig(
 }
 
 /**
- * KeyStore module — provides the JWT signing KeyStore from config.
- *
- * Per A2-γ §4 worked example. Composition-root-local: the standalone template
- * uses the built-in local/jwks adapters; alternative deployments wire their
- * own KeyStore via a different module of the same shape.
+ * The template's `config/reference.conf`, resolved from this file, which sits
+ * one directory under the template's root in `src/` and in `dist/` alike.
+ */
+const TEMPLATE_REFERENCE_HREF: string = new URL("../config/reference.conf", import.meta.url).href;
+
+/**
+ * The template's `config/reference.conf`, which every module here that owns a
+ * section declares. A new `URL` per call: a shared one could be changed in place.
+ */
+export function templateReference(): URL {
+	return new URL(TEMPLATE_REFERENCE_HREF);
+}
+
+/**
+ * Logging module: owns `logging {}`. It provides nothing: the logger is built
+ * before boot from this section (`readLogging`) and handed in as a bootstrap
+ * component, since the template logs while it chooses its modules.
+ * `LOG_LEVEL` is renamed after the path, `LOGGING_LEVEL`.
+ */
+export const loggingModule = defineModule({
+	name: "logging",
+	section: {
+		schema: loggingSectionSchema,
+		reference: templateReference(),
+		renamedVariables: { LOG_LEVEL: "logging.level" },
+	},
+});
+
+/** What the host process reads of `http {}`, beside what the `httpSettings` slot carries. */
+export interface HttpHostSettings {
+	/** The port the server listens on; `0` lets the OS pick one. */
+	readonly port: number;
+	/** The per-probe deadline of `/readyz` and the metrics scrape, in milliseconds. */
+	readonly readinessTimeoutMs: number;
+}
+
+declare module "@o3co/auth-provider-core" {
+	interface ComponentMap {
+		/** What the host process reads of `http {}`: provided by the `http` module. */
+		readonly httpHostSettings?: HttpHostSettings;
+	}
+}
+
+/**
+ * HTTP module: owns `http {}`, its CORS list (`http.cors`) included, and
+ * provides core's `httpSettings`, authoritative, and the host's
+ * `httpHostSettings`, both eager: only `app.mts` reads the host's, and no
+ * module requires it. The list moved from `cors`, and `CORS_ALLOWED_ORIGINS`
+ * with it.
+ */
+export const httpModule = defineModule({
+	name: "http",
+	section: {
+		schema: httpSectionSchema,
+		reference: templateReference(),
+		relocatedFrom: { cors: "cors" },
+		renamedVariables: { CORS_ALLOWED_ORIGINS: "cors.allowedOrigins" },
+	},
+	provides: {
+		httpSettings: ({ section }) =>
+			Object.freeze({
+				trustProxy: section.trustProxy,
+				cors: Object.freeze({ allowedOrigins: Object.freeze([...section.cors.allowedOrigins]) }),
+			}),
+		httpHostSettings: ({ section }): HttpHostSettings =>
+			Object.freeze({ port: section.port, readinessTimeoutMs: section.readinessTimeoutMs }),
+	},
+	authoritative: ["httpSettings"],
+	lifecycle: { httpSettings: { eager: true }, httpHostSettings: { eager: true } },
+});
+
+/**
+ * KeyStore module: owns `key-store {}` and provides the JWT signing KeyStore
+ * from it through the built-in local adapter. The section moved from
+ * `oauth.jwt.signingKey`, and the variables bound to it are renamed after
+ * their paths (`KEY_STORE_*`). Other deployments wire their own KeyStore
+ * through a module of the same shape.
  */
 export const keyStoreModule: Module = defineModule({
-	name: "standalone:key-store",
-	requires: ["config"] as const,
+	name: "key-store",
+	section: {
+		schema: keyStoreSectionSchema,
+		reference: templateReference(),
+		relocatedFrom: { "oauth.jwt.signingKey": "" },
+		renamedVariables: {
+			OAUTH_JWT_SIGNING_KEY_PROVIDER: "oauth.jwt.signingKey.provider",
+			OAUTH_JWT_ALGORITHM: "oauth.jwt.signingKey.local.algorithm",
+			OAUTH_JWT_KID: "oauth.jwt.signingKey.local.kid",
+			OAUTH_JWT_SECRET: "oauth.jwt.signingKey.local.secret",
+			OAUTH_JWT_PRIVATE_KEY_PATH: "oauth.jwt.signingKey.local.privateKeyPath",
+			OAUTH_JWT_PUBLIC_KEY_PATH: "oauth.jwt.signingKey.local.publicKeyPath",
+			OAUTH_JWT_PRIVATE_KEY: "oauth.jwt.signingKey.local.privateKey",
+			OAUTH_JWT_PUBLIC_KEY: "oauth.jwt.signingKey.local.publicKey",
+		},
+	},
 	provides: {
-		keyStore: async ({ config }) => {
+		keyStore: async ({ section }) => {
 			const factory = createKeyStoreFactory();
 			registerBuiltinKeyStores(factory);
-			return factory.create(flattenAdapterConfig((config as AppConfig).oauth.jwt.signingKey));
+			return factory.create(flattenAdapterConfig(section));
 		},
 	},
 });
 
+/** Which adapter fills each repository slot the `repositories` module provides. */
+export interface RepositorySelection {
+	readonly client: Adapters["clientRepository"];
+	readonly user: Adapters["userRepository"];
+}
+
 /**
- * Repositories module — provides client / user repositories from
- * `config.repositories.*` slices using the built-in adapter factories.
- *
- * Pre-OR-9 this module also provided `codeRepository` — split out into
- * `inMemoryCodeRepositoryModule` (memory branch) / `redisCodeRepositoryModule`
- * (redis branch, from `@o3co/auth-provider-redis`) so the
- * `oauth.code.adapter` switch can wire mutually-exclusive providers without
- * a slot collision. Same pattern as the Wave-5d userSessionStores split.
+ * `block`, the settings `repositories.<repository>.<adapter>` holds. The
+ * section's schema (`repositoriesSectionSchemaFor`) has refused a selected
+ * `static` without its block, so an absent one is a composition that built
+ * the section otherwise: an `Error` naming its path.
  */
-export const repositoriesModule: Module = defineModule({
-	name: "standalone:repositories",
-	requires: ["config"] as const,
-	// D-5 / OR-2 / IH-11: forward `lifecycleRegistrar` into the repository
-	// factories so client/user adapters can register disposal callbacks
-	// (e.g. file-watch closers). Without this, builders' `ctx.lifecycle?.register`
-	// is a no-op and the leaks remain.
-	optional: ["lifecycleRegistrar"] as const,
-	provides: {
-		clientRepository: async ({ config, lifecycleRegistrar }) => {
-			const ctx = { lifecycle: lifecycleRegistrar };
-			const { clientFactory, userFactory } = createRepositoryFactories(ctx);
-			registerBuiltinAdapters({ userFactory });
-			const slice = flattenAdapterConfig(
-				(config as AppConfig).repositories.client as { type: string } & Record<string, unknown>,
-			);
-			if (typeof slice.path === "string") {
-				slice.path = path.resolve(process.cwd(), slice.path);
-			}
-			return clientFactory.create(slice);
+function requiredBlock<B>(block: B | undefined, repository: string, adapter: string): B {
+	if (block === undefined) {
+		throw new Error(
+			`repositories.${repository}.${adapter}.path must be set when adapters.${repository}Repository is "${adapter}"`,
+		);
+	}
+	return block;
+}
+
+/**
+ * Repositories module: owns `repositories {}` and provides the client and
+ * user repositories the composition root's `adapters` select, through the
+ * built-in adapter factories: the YAML client registry, and the YAML or the
+ * Store's HTTP user repository (`@o3co/auth-provider-foundation`); core's
+ * `static`, an alias of `yaml`, reads a block of its own. The
+ * variables bound to its keys are renamed after their paths
+ * (`REPOSITORIES_*`). `codeRepository` comes from the in-process or the Redis
+ * code repository module instead.
+ */
+export function repositoriesModuleFor(selection: RepositorySelection): Module {
+	return defineModule({
+		name: "repositories",
+		section: {
+			schema: repositoriesSectionSchemaFor(selection),
+			reference: templateReference(),
+			renamedVariables: {
+				CLIENT_PATH: "repositories.client.yaml.path",
+				CLIENT_USER_PATH: "repositories.user.yaml.path",
+				CLIENT_USER_AUTHENTICATE_URL: "repositories.user.http.authenticateUrl",
+				CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL: "repositories.user.http.authenticateByTokenUrl",
+				CLIENT_USER_LINK_FEDERATED_IDENTITY_URL: "repositories.user.http.linkFederatedIdentityUrl",
+				CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL:
+					"repositories.user.http.findSubjectByFederatedIdentityUrl",
+				CLIENT_USER_BEARER_TOKEN: "repositories.user.http.bearerToken",
+				CLIENT_USER_TIMEOUT: "repositories.user.http.timeout",
+				CLIENT_USER_MAX_RESPONSE_BYTES: "repositories.user.http.maxResponseBytes",
+			},
 		},
-		userRepository: async ({ config, lifecycleRegistrar }) => {
-			const ctx = { lifecycle: lifecycleRegistrar };
-			const { userFactory } = createRepositoryFactories(ctx);
-			registerBuiltinAdapters({ userFactory });
-			return userFactory.create(
-				flattenAdapterConfig(
-					(config as AppConfig).repositories.user as { type: string } & Record<string, unknown>,
-				),
-			);
+		// Forwarded into the repository factories so client/user adapters can
+		// register disposal callbacks (file-watch closers, say). Without it, a
+		// builder's `ctx.lifecycle?.register` is a no-op and those resources leak.
+		optional: ["lifecycleRegistrar"] as const,
+		provides: {
+			clientRepository: async ({ section, lifecycleRegistrar }) => {
+				const { clientFactory } = createRepositoryFactories({ lifecycle: lifecycleRegistrar });
+				const file = requiredBlock(section.client[selection.client], "client", selection.client);
+				return clientFactory.create({
+					type: selection.client,
+					path: path.resolve(process.cwd(), file.path),
+				});
+			},
+			userRepository: async ({ section, lifecycleRegistrar }) => {
+				const { userFactory } = createRepositoryFactories({ lifecycle: lifecycleRegistrar });
+				registerBuiltinAdapters({ userFactory });
+				return userFactory.create(
+					flattenAdapterConfig({
+						type: selection.user,
+						[selection.user]: section.user[selection.user],
+					}),
+				);
+			},
 		},
-	},
-});
+	});
+}
 
 /**
- * In-memory CodeRepository module — wired by `buildModules` only when
- * `oauth.code.adapter = "memory"`. The redis branch swaps in
+ * In-memory CodeRepository module, wired by `buildModules` only when
+ * `adapters.codeRepository = "memory"`; the Redis choice swaps in
  * `redisCodeRepositoryModule` from `@o3co/auth-provider-redis` (mutually
- * exclusive — both modules provide the same `codeRepository` slot).
- *
- * Per OR-9 (Wave 5d) split: pre-OR-9 the codeRepository slot was provided
- * inside `repositoriesModule` via the AdapterFactory pattern; that path
- * coupled the slot to `repositories.code.type` which is now superseded by
- * `oauth.code.adapter`.
+ * exclusive: both provide the `codeRepository` slot). It reads its own
+ * section, which moved from `repositories.code.memory`; the
+ * `repositories.code.redis` block is removed.
  */
 export const inMemoryCodeRepositoryModule: Module = defineModule({
-	name: "standalone:in-memory-code-repository",
-	// #455: the replica-safety guard reads this off the manifest. Before it
-	// did, this module booted under `deployment.mode = "multi"` — the guard
-	// keyed on core's module names and had never heard of this one.
+	name: "standalone-in-memory-code-repository",
+	section: {
+		schema: inMemoryCodeRepositorySectionSchema,
+		reference: templateReference(),
+		relocatedFrom: { "repositories.code.memory": "", "repositories.code.redis": null },
+		renamedVariables: {
+			CLIENT_CODE_DEFAULT_EXPIRES_IN: "repositories.code.memory.defaultExpiresIn",
+			CLIENT_CODE_ENDPOINT_URI: "repositories.code.redis.endpointUri",
+			CLIENT_CODE_PASSWORD: "repositories.code.redis.password",
+		},
+	},
+	// The replica-safety guard reads this off the manifest, not by module name.
 	replicaSafety: {
 		unsafe: true,
 		reason:
 			"authorization codes fork per replica — a code issued by the replica that served /authorize is unknown to the replica that receives the token request, so the exchange fails with invalid_grant everywhere but one replica, and a code redeemed on one replica can be redeemed again on another",
 	},
-	requires: ["config"] as const,
 	optional: ["lifecycleRegistrar"] as const,
 	provides: {
-		codeRepository: async ({ config, lifecycleRegistrar }) => {
-			const ctx = { lifecycle: lifecycleRegistrar };
-			const { codeFactory } = createRepositoryFactories(ctx);
-			// `codeFactory.register("memory", ...)` is wired automatically by
-			// `createRepositoryFactories` itself (see core/repositories/RepositoryFactory.mts).
-			// `registerBuiltinAdapters` from `@o3co/auth-provider-foundation` only
-			// registers the HTTP user adapter on `userFactory`; it does NOT touch
-			// `codeFactory`, so calling it here would be misleading and unnecessary.
-			//
-			// The flattened slice MAY still have `type = "redis"` when only the
-			// legacy `repositories.code.type` is set — `buildModules`' adapter
-			// resolution already chose memory by the time we get here, so
-			// override the type explicitly to keep this module robust against
-			// legacy HOCON shapes.
-			const slice = flattenAdapterConfig(
-				(config as AppConfig).repositories.code as { type: string } & Record<string, unknown>,
-			);
-			return codeFactory.create({ ...slice, type: "memory" });
+		codeRepository: async ({ section, lifecycleRegistrar }) => {
+			const { codeFactory } = createRepositoryFactories({ lifecycle: lifecycleRegistrar });
+			return codeFactory.create({ type: "memory", defaultExpiresIn: section.defaultExpiresIn });
 		},
 	},
 });
 
 /**
- * In-memory user-session stores module — provides the four-store
- * user-session split (userSessionStore, sessionRPRegistry,
- * sessionFamilyIndex, sessionFederationIndex). This module is wired by
- * `buildModules` only when `userSessionStores.adapter = "memory"`. The
- * Redis branch swaps in `redisSessionStoresModule` from
- * `@o3co/auth-provider-redis`.
- *
- * Pre-Wave-5d this module also provided `federationTokenStore` (now
- * extracted into a separate always-wired module so the redis session
- * branch doesn't drop the federation-token-store provider — Copilot
- * review on PR #121).
+ * In-memory user-session stores module: the four-store user-session split
+ * (userSessionStore, sessionRPRegistry, sessionFamilyIndex,
+ * sessionFederationIndex) and the subject-level revocation pair. Wired by
+ * `buildModules` only when `adapters.userSessionStores = "memory"`; the Redis
+ * branch swaps in `redisSessionStoresModule` from `@o3co/auth-provider-redis`.
  */
 export const inMemorySessionStoresModule: Module = defineModule({
-	name: "standalone:in-memory-session-stores",
-	// #455: the replica-safety guard reads this off the manifest. Before it
-	// did, `DEPLOYMENT_MODE=multi` with `USER_SESSION_STORES_ADAPTER=memory`
-	// booted — the guard keyed on core's `memorySessionStores`, and this
-	// module provides the same six slots under a name it had never heard of.
+	name: "standalone-in-memory-session-stores",
 	replicaSafety: {
 		unsafe: true,
 		reason:
-			"user sessions, RP registrations, family indexes and the subject-level revocation pair fork per replica — back-channel logout reaches only the replica that received it, so a logged-out session stays valid on the others, and a credential change enumerates and watermarks only the replica that handled it (#321)",
+			"user sessions, RP registrations, family indexes and the subject-level revocation pair fork per replica — back-channel logout reaches only the replica that received it, so a logged-out session stays valid on the others, and a credential change enumerates and watermarks only the replica that handled it",
 	},
 	provides: {
 		userSessionStore: () => createInMemoryUserSessionStore(),
 		sessionRPRegistry: () => createInMemorySessionRPRegistry(),
 		sessionFamilyIndex: () => createInMemorySessionFamilyIndex(),
 		sessionFederationIndex: () => createInMemorySessionFederationIndex(),
-		// #406: the two subject-level revocation slots. They were missing here
-		// on both branches, so a scaffolded deployment got
-		// `subjectRevocation: undefined` — `verifyJwt` skipped the watermark,
-		// the #376 refresh gate was inert, and `revokeAllForSubject` reported
-		// `unavailable`. Nothing failed and nothing warned, which is what #406
-		// is about; the boot guard now refuses that state, and the scaffold's
-		// answer is to wire them rather than to declare the capability absent.
-		//
-		// Single-process only, like every other store on this branch. The
-		// redis branch swaps in `redisSessionStoresModule`, which has provided
-		// both since #321 — before that there was no distributed adapter to
-		// point at, which is why this gap outlived #296.
+		// The subject-level revocation slots. Without them `subjectRevocation`
+		// is undefined: `verifyJwt` skips the watermark, the refresh gate is
+		// inert and `revokeAllForSubject` reports `unavailable`, all silently.
+		// The boot guard refuses that state; the scaffold wires them rather than
+		// declaring the capability absent. Single-process only, like every
+		// other store on this branch.
 		subjectSessionIndex: () => createInMemorySubjectSessionIndex(),
 		subjectRevocation: () => createInMemorySubjectRevocation(),
 	},
 });
 
 /**
- * In-memory federation token store module — wired by `buildModules` only
- * when `federationTokenStore.type = "memory"` (the default). The redis
- * branch swaps in `redisFederationTokenStoreModule` from
- * `@o3co/auth-provider-redis` (mutually exclusive — both provide the same
- * `federationTokenStore` slot), off the shared ioredis socket.
+ * In-memory federation token store module, wired by `buildModules` only when
+ * `adapters.federationTokenStore = "memory"` (the default). The redis branch
+ * swaps in `redisFederationTokenStoreModule` off the shared ioredis socket
+ * (mutually exclusive: both provide the `federationTokenStore` slot). One
+ * module per adapter, so the replica-safety guard can tell them apart and the
+ * Redis one can require its client. The slot is always wired, independent of
+ * the `adapters.userSessionStores` selection.
  *
- * Until #455 / #456 this was one module for both adapters
- * (`standalone:federation-token-store`), choosing at runtime through the
- * adapter factory. That shape failed twice over: the replica-safety guard
- * could not tell the memory store from the Redis one by name, so
- * `deployment.mode = "multi"` booted with the memory store; and the Redis
- * branch handed the builder no client, so `federationTokenStore.type =
- * "redis"` — documented in the README — was a boot failure rather than a
- * Redis-backed store. One module per adapter, like the session stores.
- *
- * The slot is always wired, independent of the `userSessionStores.adapter`
- * switch: pre-Wave-5d it was bundled into the larger `storesModule`, and the
- * redis session-stores branch dropped the provider entirely (Copilot review
- * on PR #121).
- *
- * The memory adapter still comes through core's factory, unchanged: that is
- * where its "dev/test only" boot warning lives.
+ * The memory adapter comes through core's factory: that is where its
+ * "dev/test only" boot warning lives.
  */
 export const inMemoryFederationTokenStoreModule: Module = defineModule({
-	name: "standalone:in-memory-federation-token-store",
-	// #455: read by the replica-safety guard. Before the split this module
-	// carried one name for both adapters, so no name could have carried it.
+	name: "standalone-in-memory-federation-token-store",
 	replicaSafety: {
 		unsafe: true,
 		reason:
@@ -282,75 +364,52 @@ export const inMemoryFederationTokenStoreModule: Module = defineModule({
 });
 
 /**
- * Audit-sink module — fills the `auditSink` slot every route that emits a
- * security event reads (#287).
- *
- * The slot is `optional` on `oauthModule`, `sessionModule` and `webauthnModule`,
- * and `emitAuditEvent` is a no-op when it is empty. That combination is why the
- * gap was invisible: the scaffold wired no sink, so `token.issued.failure`,
- * `authorize.rejected` / `authorize.granted`, `logout.cascade_failed` and the
- * shared rate-limit guard's `rate_limit.unavailable` were all discarded by the
- * deployable artifact, with nothing failing and nothing warning. This module is
- * always in the manifest for that reason — there is no "no audit sink" branch,
- * the way there is a memory/redis branch for the state stores.
- *
- * Two sink kinds are registered:
- *
- * - `"logger"` (the template's default) — one NDJSON line per event on stdout,
- *   in the same pino envelope as every other line this template emits, on a
- *   stream named `audit` whose level is fixed. See `createAuditLogger`.
- * - `"console"` — core's built-in, from `registerBuiltinAuditSinks`: the bare
- *   event as one JSON object per line on stdout, with no log envelope. For a
- *   pipeline that wants the event and nothing else.
- *
- * A deployment with a real sink (SIEM, log pipeline, message bus) registers its
- * builder here and names it in `audit.sink.type`; its options ride along in the
- * same config block (`flattenAdapterConfig` unwraps `sink { type = "x", x { … } }`).
+ * Audit-sink module: owns `audit-sink {}` and fills the `auditSink` slot every
+ * route that emits a security event reads, with the sink the composition
+ * root's `adapters.auditSink` names: the template's `"logger"` (its default)
+ * or one of core's built-ins, with that sink's options from
+ * `audit-sink.<name>`. The slot is `optional` on `oauthModule`,
+ * `sessionModule` and `webauthnModule`, and `emitAuditEvent` is a no-op when
+ * it is empty, so this module is always in the manifest; a name no builder is
+ * registered under refuses boot. The sink's options moved from `audit.sink`.
  *
- * One thing to know before writing such a builder: `createAuditSinkFactory()`
- * takes no `BuilderContext`, so a sink builder receives `{}` and the
- * `ctx.lifecycle?.register(…)` / `ctx.readiness?.register(…)` calls that
- * CONTRIBUTING.md requires of a builder opening a connection are silent no-ops
- * here. A sink holding a socket must own its cleanup another way until that
- * factory takes a context.
- *
- * There is deliberately no `"none"`. An unknown type — including the `"none"`
- * an operator might reasonably guess at — fails boot naming the sinks that
- * exist, rather than producing a deployment with no audit trail (#304).
+ * `createAuditSinkFactory()` takes no `BuilderContext`, so a sink builder
+ * receives `{}` and the `ctx.lifecycle?.register(…)` /
+ * `ctx.readiness?.register(…)` calls CONTRIBUTING.md requires of a builder
+ * opening a connection are silent no-ops: a sink holding a socket must own
+ * its cleanup another way.
  */
-export const auditSinkModule: Module = defineModule({
-	name: "standalone:audit-sink",
-	requires: ["config"] as const,
-	provides: {
-		auditSink: async ({ config }) => {
-			const factory = createAuditSinkFactory();
-			registerBuiltinAuditSinks(factory);
-			factory.register("logger", () => createLoggerAuditSink(createAuditLogger()));
-			const slice = (config as AppConfig).audit?.sink;
-			// Absence lands on the default sink rather than on `undefined`: a
-			// config that says nothing about auditing is not a config asking for
-			// the events to be dropped. The literal default lives in HOCON
-			// (`reference.conf` / `application.conf`); this is the floor under a
-			// hand-built config that never met either.
-			return factory.create(
-				slice
-					? flattenAdapterConfig(slice as { type: string } & Record<string, unknown>)
-					: { type: "logger" },
-			);
+export function auditSinkModuleFor(sink: string): Module {
+	return defineModule({
+		name: "audit-sink",
+		section: {
+			schema: auditSinkSectionSchema,
+			reference: templateReference(),
+			relocatedFrom: {
+				"audit.sink": { to: "", environmentVariable: null },
+				"audit.sink.type": null,
+			},
 		},
-	},
-});
+		provides: {
+			auditSink: async ({ section }) => {
+				const factory = createAuditSinkFactory();
+				registerBuiltinAuditSinks(factory);
+				factory.register("logger", () => createLoggerAuditSink(createAuditLogger()));
+				return factory.create(flattenAdapterConfig({ type: sink, [sink]: section?.[sink] }));
+			},
+		},
+	});
+}
 
 /**
- * @deprecated since Wave 5d (F4 PR2): split into `inMemorySessionStoresModule`
- * + `inMemoryFederationTokenStoreModule`. Re-exported for backward
- * compatibility with consumers that imported `storesModule` from this file.
- * New code should use the two split modules directly.
+ * @deprecated Split into `inMemorySessionStoresModule` and
+ * `inMemoryFederationTokenStoreModule`; use those. Kept for consumers that
+ * imported `storesModule` from this file.
  */
 export const storesModule: Module = defineModule({
-	name: "standalone:stores",
-	// #455: everything this bundle provides lives in process memory, so a
-	// composition still on it is refused under `deployment.mode = "multi"`
+	name: "stores",
+	// Everything this bundle provides lives in process memory, so a
+	// composition still on it is refused under `core.deployment.mode = "multi"`
 	// like the split modules it stands in for.
 	replicaSafety: {
 		unsafe: true,
@@ -365,289 +424,231 @@ export const storesModule: Module = defineModule({
 });
 
 /**
- * Shared ioredis clients module — opens ONE long-lived ioredis connection
- * per replica, wraps it via `makeIoredisClients()` (returns 16 typed
- * per-purpose clients), and exposes the slots consumed by the standalone's
- * 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 + 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).
- * This module consolidates them — `makeIoredisClients(io)` was always
- * designed to derive multiple per-purpose typed clients from a single
- * connection; using one socket realises that intent and minimises
- * connection-pool pressure on the upstream Redis.
+ * Shared ioredis clients module: opens ONE long-lived ioredis connection per
+ * replica and derives every per-purpose client from it (`makeIoredisClients`,
+ * plus the two federation-grant store clients from their own factories),
+ * rather than a socket per Redis-backed module, to keep connection-pool
+ * pressure off the upstream Redis. Every store module
+ * `@o3co/auth-provider-redis` ships finds its client slot here, including
+ * those this template does not select; `all-modules-composition.multi.test.mts`
+ * pins that.
  *
- * Connection-config: reuses `refreshTokenFamilyStore.redis.{url, password}`
- * (declared in `fullSectionsSchema` by D-2 v2 §1). No new top-level config
- * key is introduced — the connection is shared so its config is too. Future
- * splits (per-store distinct Redis instances) are operator-side via custom
- * composition roots, not standalone configuration.
+ * The connection's URL and password are the module's own section,
+ * `redis-clients`, which moved from `refreshTokenFamilyStore.redis` with its
+ * variables (`REDIS_CLIENTS_*`). Per-store Redis instances belong in a
+ * custom composition root. An empty URL throws rather than falling back to
+ * localhost. `io.quit()` is registered once with `lifecycleRegistrar`, so
+ * `handle.dispose()` closes the connection.
  *
- * Fails fast (throws) when the Redis URL is absent. The HOCON default in
- * `application.conf` covers single-instance / dev scenarios; an operator
- * who deliberately removes the section in production sees an explicit
- * error instead of a silent localhost fallback (the multi-replica failure
- * mode OR-1 was supposed to close).
- *
- * Lifecycle: registers `io.quit()` once with the boot-planner-pre-seeded
- * `lifecycleRegistrar` (D-5 ComponentMap slot) so `handle.dispose()` quits
- * the single connection cleanly.
- *
- * Conditional inclusion: `buildModules` only adds this module to the
- * 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.
+ * `buildModules` adds this module only when some composed module needs a
+ * Redis client (`usingRedisAnywhere`), so memory-only compositions open no
+ * socket.
  */
 export const standaloneRedisClientsModule: Module = defineModule({
-	name: "standalone:redis-clients",
-	requires: ["config"] as const,
+	name: "redis-clients",
+	section: {
+		schema: redisClientsSectionSchema,
+		reference: templateReference(),
+		relocatedFrom: { "refreshTokenFamilyStore.redis": "" },
+		renamedVariables: {
+			REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "refreshTokenFamilyStore.redis.url",
+			REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD: "refreshTokenFamilyStore.redis.password",
+		},
+	},
 	optional: ["lifecycleRegistrar", "readinessRegistrar", "logger"] as const,
 	provides: {
 		refreshTokenFamilyClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.refreshTokenFamilyClient;
 		},
-		userSessionStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		userSessionStoreClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.userSessionStoreClient;
 		},
-		sessionRPRegistryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		sessionRPRegistryClient: async ({
+			section,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionRPRegistryClient;
 		},
 		sessionFamilyIndexClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFamilyIndexClient;
 		},
 		sessionFederationIndexClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
-		// #593 slice 7: the grant store and the intent store, off the same
-		// socket. Consumed by the Redis grant modules when their switches say
-		// "redis"; provided whenever this module is installed, as every slot
-		// here is, because a slot is cheap and the socket is the cost.
+		// The grant store and the intent store, consumed by the Redis grant
+		// modules when their switches say "redis". Provided whenever this module
+		// is installed, as every slot here is: a slot is cheap, the socket is
+		// the cost.
 		federationGrantStoreClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.federationGrantStoreClient;
 		},
 		federationGrantIntentStoreClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.federationGrantIntentStoreClient;
 		},
-		// #484: the replay seen-set behind private_key_jwt client assertions.
-		replaySeenSetClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		// The replay seen-set behind private_key_jwt client assertions.
+		replaySeenSetClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.replaySeenSetClient;
 		},
-		rateLimiterClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		rateLimiterClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.rateLimiterClient;
 		},
-		// OR-9: code-repository client wired off the same shared ioredis
-		// socket. `redisCodeRepositoryModule` consumes this slot when
-		// `oauth.code.adapter = "redis"`. Codes are short-TTL (60-600s)
-		// high-volume — sharing the connection avoids opening a separate
-		// socket while the per-purpose typed wrapper keeps the Redis
-		// command surface consumed by RedisCodeRepository explicit.
-		codeRepositoryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		// `redisCodeRepositoryModule` consumes this slot when
+		// `adapters.codeRepository = "redis"`.
+		codeRepositoryClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.codeRepositoryClient;
 		},
-		// #277: access-token denylist client, off the same shared socket. A
-		// denylist is only worth having if every replica reads the same one —
-		// that is the entire reason `redisAccessTokenDenylistModule` exists — so
-		// it belongs on the connection the rest of the shared state already uses
-		// rather than opening a second one.
+		// A denylist is only worth having if every replica reads the same one,
+		// so it belongs on the connection the rest of the shared state uses
+		// rather than a second one.
 		accessTokenDenylistClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.accessTokenDenylistClient;
 		},
-		// #321: the two subject-level revocation client slots, off the same
-		// shared socket. `redisSessionStoresModule` requires both — the index
-		// enumerates what a credential change cascades over and the watermark
-		// refuses what the cascade missed — so without them the scaffold's
-		// Redis branch had no provider for the slots and stage-1 boot refused
-		// the manifest with `missing-required-component`. Nothing in the
-		// standalone consumes these slots directly; they exist so the module
-		// that does can be selected.
+		// The subject-level revocation pair, both required by
+		// `redisSessionStoresModule`: the index enumerates what a credential
+		// change cascades over, the watermark refuses what the cascade missed.
+		// Nothing in the standalone consumes them directly; they exist so that
+		// module can be selected.
 		subjectSessionIndexClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.subjectSessionIndexClient;
 		},
-		subjectRevocationClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		subjectRevocationClient: async ({
+			section,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.subjectRevocationClient;
 		},
-		// #433: the device-code store client, off the same shared socket.
-		// `redisDeviceCodeStoreModule` requires it. This template does not
-		// mount the device grant, so nothing in `buildModules` selects that
-		// module today; the slot is provided anyway, because a deployment that
-		// adds `deviceGrantModule` to this manifest and picks the Redis store
-		// must not hit the `missing-required-component` boot failure the
-		// subject-level slots above already paid for (#439) — a Redis-branch
-		// module whose client slot this module did not provide, caught only by
-		// the umbrella e2e.
-		deviceCodeStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		// Required by `redisDeviceCodeStoreModule`. This template does not mount
+		// the device grant; the slot is provided anyway, so a deployment that
+		// adds `deviceGrantModule` with the Redis store is not refused at boot
+		// (`missing-required-component`) for a client slot nothing provided.
+		deviceCodeStoreClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, 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)
+		// The WebAuthn challenge store's client, for the device-code slot's
+		// reason: 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 ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, 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
-		// it under `consentStore.adapter = "redis"`.
-		consentStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+		// The consent stores' clients. `redisConsentStoreModule` requires both
+		// (it provides the consent records and the parked requests together),
+		// and `buildModules` selects it under `adapters.consentStore = "redis"`.
+		consentStoreClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.consentStoreClient;
 		},
 		pendingConsentStoreClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.pendingConsentStoreClient;
 		},
-		// #456: the federation-token-store client, off the same shared socket.
-		// `redisFederationTokenStoreModule` requires it, and nothing provided
-		// it — which is why the Redis branch of the federation store could not
-		// boot in this template while the README said it could.
+		// Required by `redisFederationTokenStoreModule`.
 		federationTokenStoreClient: async ({
-			config,
+			section,
 			lifecycleRegistrar,
 			readinessRegistrar,
 			logger,
 		}) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
 				.federationTokenStoreClient;
 		},
+		// The two MFA stores' clients, required by `redisMfaFactorStoreModule`
+		// and `redisMfaTransactionStoreModule`, which `buildModules` selects
+		// with MFA on and `adapters.mfaFactorStore` / `.mfaTransactionStore`
+		// = "redis". Each module checks the server's eviction policy and
+		// persistence when it boots.
+		mfaFactorStoreClient: async ({ section, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
+				.mfaFactorStoreClient;
+		},
+		mfaTransactionStoreClient: async ({
+			section,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(section, lifecycleRegistrar, readinessRegistrar, logger)
+				.mfaTransactionStoreClient;
+		},
 	},
 });
 
 /**
- * Failure-timing options for the one shared ioredis socket (#286).
- *
- * On the driver's defaults this connection had no `commandTimeout` at all, so
- * a partition did not produce errors — it produced *waiting*. Every `/token`
- * request that touched Redis parked in the offline queue while the socket
- * reconnected, and because nothing threw, the `rateLimit.failMode = "closed"`
- * policy (`createRateLimitGuard`, OR-5) never engaged: it only fires when
- * `limiter.check()` rejects. The load the policy exists to shed kept arriving
- * and kept accumulating, and memory and sockets grew until ioredis's 20th
- * reconnect attempt finally flushed the queue — tens of seconds later.
- *
- * The values below are chosen against the actual command surface of this
- * socket, which is entirely O(1) primitives and small paged scans
- * (`SET`/`GET`/`DEL`/`EXISTS`/`PTTL`/`INCR`/`EVAL`/`HSCAN`/`SSCAN`/`ZADD`/…).
- * There is no blocking command here, so no legitimate command has any reason
- * to take a meaningful fraction of a second.
+ * Failure-timing options for the one shared ioredis socket. Each value's
+ * reason, and the trade the offline queue buys, is in
+ * `docs/operator-runbook.md`, "Failure timing on the shared socket". In
+ * short: on the driver's defaults a partition produces *waiting*, not errors,
+ * so the Redis limiter's `redis-rate-limiter.failMode = "closed"` policy, which the
+ * guard (`createRateLimitGuard`) applies only when `limiter.check()` rejects,
+ * never engages.
+ * `commandTimeout` bounds every command, queued or on the wire, zombie socket
+ * included; `maxRetriesPerRequest` bounds the offline queue's depth; the
+ * queue stays on because the option is per connection and this socket also
+ * carries sessions, codes and refresh rotation.
  *
- * - `commandTimeout: 1000` — the hard ceiling on any single command. ioredis
- *   arms this timer in `sendCommand`, *before* the writability check, so it
- *   bounds a command that went into the offline queue exactly as it bounds one
- *   already on the wire. That is what makes the queued case fail rather than
- *   hang, and it is also the only guard that survives the nastiest partition
- *   shape: a zombie TCP connection where no `close` event ever fires, so the
- *   reconnect path described next is never entered at all.
- * - `maxRetriesPerRequest: 3` — on the fourth reconnect attempt (roughly
- *   0.4–1 s in on ioredis 6's jittered exponential backoff) the whole queue is
- *   failed in one go with `MaxRetriesPerRequestError`, rather than on the
- *   twentieth as the default has it. `commandTimeout` alone bounds each command's
- *   *latency*, but the queue would still grow to (request rate × 1 s) entries
- *   for as long as the outage lasted; this bounds its *depth*. Three rather
- *   than one so an ordinary sub-second reconnect blip is ridden out silently.
- * - `connectTimeout: 5000` — halves the driver's 10 s default. A dropped SYN
- *   (a partition that black-holes packets rather than refusing them) is the
- *   only case that reaches this ceiling; a real connect on any deployment
- *   topology this template targets completes in well under a second.
- * - `enableOfflineQueue: true` — the driver default, declared explicitly
- *   because it is a decision, not an inherited value. See below.
- * - `lazyConnect: false` — also the driver default (still, on ioredis 6),
- *   declared so the boot-time-connect contract survives a future flip.
- *
- * **Why the offline queue stays on.** Turning it off is the sharper answer for
- * the rate limiter specifically: a command issued while the socket is down
- * rejects immediately instead of after `commandTimeout`, so the fail-closed
- * policy sheds load at the first request rather than one second per request
- * later. But `enableOfflineQueue` is a per-**connection** option, and this
- * template runs every purpose off one socket — refresh-token families, the
- * four user-session stores, the authorization-code repository, the
- * access-token denylist and the rate limiter all come out of a single
- * `makeIoredisClients(io)` call (pinned by "one connection in, one connection
- * used" in `packages/redis/__tests__/ioredis.test.mts`). There is no way to
- * express "off here, on there" without opening a second socket, which is the
- * connection-pool pressure the shared-socket design was built to avoid.
- *
- * So the choice is one setting for all eleven purposes, and `false` is the
- * wrong one to pick for all eleven: it converts every reconnect — including
- * the sub-second blip of a routine managed-Redis failover, during which
- * ioredis would have recovered transparently — into hard errors on session
- * lookup, code redemption and refresh rotation. A failed refresh rotation is
- * not a retryable blip to the end user; it is a re-login.
- *
- * `true` costs the rate limiter up to `commandTimeout` of delay before it
- * starts shedding, and that is the honest trade. It is affordable precisely
- * because `commandTimeout` exists: the pile-up is now bounded by
- * (request rate × 1 s) and self-draining, rather than unbounded and growing.
- * A deployment that wants the sharper behavior gives the rate limiter its own
- * connection in its own composition root — the per-purpose client interfaces
- * exist for exactly that, and it is a deliberate second socket rather than a
- * silent global.
+ * One second is ample: the socket's commands are O(1) primitives and small
+ * paged scans (`SET`/`GET`/`DEL`/`EXISTS`/`PTTL`/`INCR`/`EVAL`/`HSCAN`/
+ * `SSCAN`/`ZADD`/…), none blocking. `lazyConnect: false` is the driver
+ * default, declared so the boot-time-connect contract survives a future flip.
  */
 const SHARED_REDIS_TIMEOUTS = {
 	commandTimeout: 1_000,
@@ -657,26 +658,12 @@ const SHARED_REDIS_TIMEOUTS = {
 	lazyConnect: false,
 } as const;
 
-// Module-scoped cache so each `provides.*` factory invocation reuses the
-// same `Redis` instance (and its `makeIoredisClients()` derivation) within
-// a single createApp() invocation. The boot planner calls each `provides`
-// in dependency order; without this, every consumed slot would create its
-// own Redis socket, defeating the unification purpose.
-//
-// Cache key: the `lifecycleRegistrar` IDENTITY (which is per-boot — each
-// `createApp()` invocation seeds a fresh registrar via the boot planner).
-// Keying solely on `config` would incorrectly share connections across
-// boots when the same config object is reused with a new registrar (and
-// only the FIRST boot's registrar would receive disposal — Copilot review
-// on PR #121). When `lifecycleRegistrar` is undefined (test scenarios
-// that don't seed it), each call creates a fresh client; tests are
-// isolated and don't need cross-slot sharing.
 /**
  * Every per-purpose client off the one socket: the general bundle, plus the
- * two the federation-grant stores need (#593 slice 7). Those two have their
- * own factories in the Redis package, so a Cluster deployment can give the
- * grants a connection of their own; this template shares the socket, as it
- * does for every other store.
+ * two the federation-grant stores need. Those two have their own factories in
+ * the Redis package, so a Cluster deployment can give the grants a
+ * connection of their own; this template shares the socket, as it does for
+ * every other store.
  */
 type StandaloneRedisClients = ReturnType<typeof makeIoredisClients> & {
 	readonly federationGrantStoreClient: ReturnType<typeof makeIoredisFederationGrantStoreClient>;
@@ -684,9 +671,15 @@ type StandaloneRedisClients = ReturnType<typeof makeIoredisClients> & {
 		typeof makeIoredisFederationGrantIntentStoreClient
 	>;
 };
+// So every `provides.*` factory reuses one `Redis` instance (and its clients)
+// within a createApp() call, rather than opening a socket per consumed slot.
+// Keyed on the `lifecycleRegistrar` identity, fresh per boot: keying on
+// `config` would share connections across boots that reuse a config object,
+// and only the first boot's registrar would dispose them. Without a
+// registrar (tests that seed none), each call creates a fresh client.
 const clientsCache = new WeakMap<LifecycleRegistrar, StandaloneRedisClients>();
 function getOrCreateClients(
-	config: AppConfig,
+	section: { readonly url: string; readonly password?: string | undefined },
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
 	readinessRegistrar?: ReadinessRegistrar,
 	injectedLogger?: Logger,
@@ -695,18 +688,16 @@ function getOrCreateClients(
 	const cached = lifecycleRegistrar ? clientsCache.get(lifecycleRegistrar) : undefined;
 	if (cached) return cached;
 
-	const cfg = config.refreshTokenFamilyStore?.redis;
-	if (typeof cfg?.url !== "string" || cfg.url.length === 0) {
+	if (section.url.length === 0) {
 		throw new Error(
-			"standaloneRedisClientsModule: `refreshTokenFamilyStore.redis.url` is required when any " +
-				"Redis-backed adapter is selected. Set REFRESH_TOKEN_FAMILY_STORE_REDIS_URL or " +
-				"restore the `refreshTokenFamilyStore.redis` block in application.conf. Multi-replica " +
-				"deployments require a shared Redis 7.2+ instance.",
+			"standaloneRedisClientsModule: `redis-clients.url` is required when any " +
+				"Redis-backed adapter is selected. Set REDIS_CLIENTS_URL, or the " +
+				"key in a configuration layer, to a non-empty URL. Multi-replica deployments require " +
+				"a shared Redis 7.2+ instance.",
 		);
 	}
-	const password = typeof cfg.password === "string" ? cfg.password : undefined;
 
-	const io = new Redis(cfg.url, { password, ...SHARED_REDIS_TIMEOUTS });
+	const io = new Redis(section.url, { password: section.password, ...SHARED_REDIS_TIMEOUTS });
 
 	// Attach an error handler so unhandled "error" events do not crash the
 	// process. Initial connection failures surface here; downstream adapter
@@ -721,9 +712,9 @@ function getOrCreateClients(
 		await io.quit();
 	});
 
-	// One probe for the one socket. Registering per consumed slot would report
-	// the same connection six times; the cache above means this runs once per
-	// boot, on the call that actually constructs the client.
+	// One probe for the one socket, not one per consumed slot: the cache
+	// above means this runs once per boot, on the call that constructs the
+	// client.
 	readinessRegistrar?.register({
 		name: "redis",
 		check: () => io.ping(),
@@ -742,13 +733,11 @@ function getOrCreateClients(
 }
 
 /**
- * Reads an optional string field off a federation slice.
- *
- * A field the operator did not set stays absent rather than becoming
- * `undefined`, so `"sessionDomain" in config` still distinguishes the two. A
- * field that is present but not a string throws: HOCON hands through whatever
- * shape the file holds, and silently ignoring `sessionDomain = 42` would leave
- * the redirect policy running with one fewer constraint than the operator
+ * Reads an optional string field off a federation slice. An unset field stays
+ * absent rather than becoming `undefined`, so `"sessionDomain" in config`
+ * still distinguishes the two. A present non-string throws: HOCON hands
+ * through whatever the file holds, and silently ignoring `sessionDomain = 42`
+ * would run the redirect policy with one fewer constraint than the operator
  * wrote down.
  */
 function optionalString(
@@ -758,20 +747,19 @@ function optionalString(
 	const value = slice[field];
 	if (value === undefined || value === null) return {};
 	if (typeof value !== "string") {
-		throw new Error(`federations.google.${field} must be a string when present`);
+		throw new Error(`core.federations.google.${field} must be a string when present`);
 	}
 	return { [field]: value };
 }
 
 /**
- * An optional boolean from the `federations.google` slice. HOCON gives a
- * boolean; an environment override (`${?VAR}`) gives the string, in the
- * spellings core's `coerceBooleanFromEnv` accepts: "true" / "false" / "1" /
- * "0", trimmed and in any case. One deliberate difference: that coercion reads
- * an empty value as false, and this refuses it. HOCON substitutes an
- * exported-but-empty variable as "", and for a security switch that must not
- * quietly turn the check off. Anything else is refused too — a typo that
- * silently reads as either value is worse than a boot failure.
+ * An optional boolean from the `core.federations.google` entry: a HOCON boolean, or
+ * from an environment override (`${?VAR}`) a string in the spellings core's
+ * `coerceBooleanFromEnv` accepts ("true" / "false" / "1" / "0", trimmed, any
+ * case). Unlike that coercion, an empty value is refused, not read as false:
+ * HOCON substitutes an exported-but-empty variable as "", and a security
+ * switch must not quietly turn the check off. Anything else is refused too,
+ * so a typo fails boot rather than reading as either value.
  */
 function optionalBoolean(
 	slice: Record<string, unknown>,
@@ -786,12 +774,12 @@ function optionalBoolean(
 		if (normalized === "false" || normalized === "0") return { [field]: false };
 	}
 	throw new Error(
-		`federations.google.${field} must be one of true, false, "true", "false", "1" or "0" when present`,
+		`core.federations.google.${field} must be one of true, false, "true", "false", "1" or "0" when present`,
 	);
 }
 
 /**
- * `accessType` from the `federations.google` slice: `"offline"` or `"online"`,
+ * `accessType` from the `core.federations.google` entry: `"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.
  */
@@ -801,35 +789,30 @@ function optionalAccessType(
 	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');
+	throw new Error('core.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.
- *
- * Per `@o3co/auth-provider-federation-google` README. Per-federation modules
- * (Phase 7 A5) consume this slot; the bridge is the standalone composition
- * root's responsibility because the slot's content is consumer-specific.
+ * Google federation config bridge: supplies the typed `googleFederationConfig`
+ * slot from the `core.federations.google` entry. The bridge is the
+ * composition root's responsibility because the slot's content is
+ * consumer-specific (see the `@o3co/auth-provider-federation-google` README).
  *
- * #278: this used to return `{ clientId, clientSecret, callbackURL }` and stop
- * there, dropping `redirectAllowlist` / `sessionDomain` / `authCallbackUrl` /
- * `clientUrl` on the floor. Nothing complained — `googleFederationModule` hands
- * this same object to `createFederationRedirectPolicy`, so the redirect policy
- * was built from a config with none of the fields it reads, and a deployment
- * that had configured them ran as though it had not. The generated app is the
- * shape most operators start from, so the safe path has to be the one that
- * works by filling in the config file.
+ * It carries every field the provider reads, not only the credentials:
+ * `googleFederationModule` hands this same object to
+ * `createFederationRedirectPolicy`, so a dropped `redirectAllowlist` /
+ * `sessionDomain` / `authCallbackUrl` / `clientUrl` would silently run the
+ * policy without the constraints the operator configured.
  */
 export const googleFederationConfigModule: Module = defineModule({
-	name: "standalone:google-federation-config",
+	name: "google-federation-config",
 	requires: ["config"] as const,
 	provides: {
 		googleFederationConfig: ({ config }): GoogleProviderConfig => {
-			const slice = extractFederationSection((config as AppConfig).federations, "google");
+			const slice = extractFederationSection(federationsOf(config), "google");
 			if (!slice) {
 				throw new Error(
-					"federations.google must be enabled with credentials when googleFederationModule is in the manifest",
+					"core.federations.google must be enabled with credentials when googleFederationModule is in the manifest",
 				);
 			}
 			const clientId = slice.clientId;
@@ -841,7 +824,7 @@ export const googleFederationConfigModule: Module = defineModule({
 				typeof callbackURL !== "string"
 			) {
 				throw new Error(
-					"federations.google requires clientId, clientSecret, callbackURL when enabled",
+					"core.federations.google requires clientId, clientSecret, callbackURL when enabled",
 				);
 			}
 
@@ -855,7 +838,7 @@ export const googleFederationConfigModule: Module = defineModule({
 			if (rawAllowlist !== undefined && rawAllowlist !== null) {
 				if (!Array.isArray(rawAllowlist) || rawAllowlist.some((e) => typeof e !== "string")) {
 					throw new Error(
-						"federations.google.redirectAllowlist must be a list of URL strings, " +
+						"core.federations.google.redirectAllowlist must be a list of URL strings, " +
 							'e.g. ["https://app.example.com/welcome"]',
 					);
 				}
@@ -870,7 +853,7 @@ export const googleFederationConfigModule: Module = defineModule({
 				...optionalString(slice, "sessionDomain"),
 				...optionalString(slice, "authCallbackUrl"),
 				...optionalString(slice, "clientUrl"),
-				// #597: absent means the provider's default, which is to require it.
+				// 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.
@@ -881,19 +864,18 @@ export const googleFederationConfigModule: Module = defineModule({
 });
 
 /**
- * OIDC federation config bridge (#524) — supplies the `oidcFederationConfigs`
+ * OIDC federation config bridge: supplies the `oidcFederationConfigs`
  * slot every `oidcFederationModule(<name>)` in the manifest reads its entry
  * from. One bridge for all instances: `readOidcFederationConfigs` walks
- * `config.federations` and reads every enabled section of type `oidc`,
- * refusing a malformed field by `federations.<name>.<field>` at boot.
+ * `core.federations` and reads every enabled entry of type `oidc`,
+ * refusing a malformed field by `core.federations.<name>.<field>` at boot.
  * `buildModules` lists this module only when at least one such section
  * exists.
  */
 export const oidcFederationConfigModule: Module = defineModule({
-	name: "standalone:oidc-federation-config",
+	name: "oidc-federation-config",
 	requires: ["config"] as const,
 	provides: {
-		oidcFederationConfigs: ({ config }) =>
-			readOidcFederationConfigs((config as AppConfig).federations),
+		oidcFederationConfigs: ({ config }) => readOidcFederationConfigs(federationsOf(config)),
 	},
 });