@o3co/create-auth-provider 0.8.0 → 0.10.0

package/templates/standalone/src/metrics.mts

@@ -0,0 +1,190 @@
+/*
+ * 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 type { ReadinessProbe } from "@o3co/auth-provider-core";
+import { runReadinessProbes } from "@o3co/auth-provider-core";
+import type { NextFunction, Request, RequestHandler, Response, Router } from "express";
+import { collectDefaultMetrics, Gauge, Histogram, Registry } from "prom-client";
+
+/**
+ * Route label for a request.
+ *
+ * Express only fills `req.route` once a handler has matched, and the label has
+ * to be **bounded**: labelling by `req.path` would mint a new time series per
+ * distinct URL, and this server's paths carry opaque values (`/oauth/authorize`
+ * query state, 404 probes from the internet). An unbounded label set is the
+ * classic way to take Prometheus down with the thing that was supposed to
+ * watch it. Unmatched requests collapse to a single `unmatched` bucket.
+ */
+/**
+ * Method label, bounded to the methods this server can actually serve.
+ *
+ * `req.method` is attacker-controlled: Node's HTTP parser accepts any valid
+ * token, so `FOO` and `M000001` reach here as readily as `GET`. Each distinct
+ * value would mint a fresh histogram child carrying every bucket — the same
+ * unbounded-cardinality failure {@link routeLabel} guards against, one label
+ * over, and reachable without any access to `/metrics` itself.
+ */
+const KNOWN_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS",
+	"TRACE",
+	"CONNECT",
+]);
+
+function methodLabel(req: Request): string {
+	return KNOWN_METHODS.has(req.method) ? req.method : "other";
+}
+
+function routeLabel(req: Request): string {
+	const route = (req as Request & { route?: { path?: string } }).route?.path;
+	if (typeof route === "string" && route.length > 0) {
+		return req.baseUrl ? `${req.baseUrl}${route === "/" ? "" : route}` : route;
+	}
+	return "unmatched";
+}
+
+export interface MetricsRouteOptions {
+	/**
+	 * Readiness probes, sampled on each scrape to publish a per-dependency
+	 * up/down gauge. Pass `handle.readinessProbes`.
+	 */
+	readonly probes: readonly ReadinessProbe[];
+	/** Per-probe deadline, in milliseconds. Use `config.http.readinessTimeoutMs`. */
+	readonly probeTimeoutMs: number;
+	/** Route path. Defaults to `/metrics`. */
+	readonly path?: string;
+}
+
+export interface Metrics {
+	/**
+	 * Mount FIRST, ahead of every route: it times the whole downstream stack,
+	 * and it records on the response's `finish` event so a request that ends in
+	 * an error handler is still counted.
+	 */
+	readonly middleware: RequestHandler;
+	/**
+	 * Mounts the scrape endpoint.
+	 *
+	 * The probes arrive here rather than at construction because the two halves
+	 * are needed at different moments: the middleware has to be mounted before
+	 * the app boots, and the probes only exist afterwards, on the `AppHandle`.
+	 */
+	readonly route: (express: { Router: () => Router }, options: MetricsRouteOptions) => Router;
+}
+
+/**
+ * Prometheus metrics for the standalone provider.
+ *
+ * What this publishes is chosen from what an operator cannot otherwise see.
+ * Before it, a degraded provider offered stderr lines and the load balancer's
+ * 5xx graph — no way to distinguish "rate limiter is failing closed" from
+ * "Redis-backed code repository is gone" without grepping container logs, and
+ * no latency series to alert on at all.
+ *
+ * - `http_request_duration_seconds` — histogram by method, bounded route, and
+ *   status. Carries request rate, error rate and latency in one series, which
+ *   is the whole RED method.
+ * - `auth_dependency_up` — 1/0 per readiness probe, sampled at scrape time.
+ *   This is the series that separates "Redis is gone" from "the app is slow",
+ *   and it reuses the probes the builders already registered rather than
+ *   inventing a second notion of what this deployment depends on.
+ * - Node process defaults (event-loop lag, heap, GC, handles) under the
+ *   `auth_provider_` prefix.
+ *
+ * Deliberately not here yet: rate-limiter fail-closed counts and audit-sink
+ * drops. Both happen inside `@o3co/auth-provider-core` and neither is
+ * observable from the composition root today; counting them needs a metrics
+ * hook in core (`BuilderContext` already reserves `metrics`) rather than
+ * something this file can reach.
+ */
+export function createMetrics(): Metrics {
+	const registry = new Registry();
+	collectDefaultMetrics({ register: registry, prefix: "auth_provider_" });
+
+	const requestDuration = new Histogram({
+		name: "http_request_duration_seconds",
+		help: "HTTP request latency in seconds, by method, route and status.",
+		labelNames: ["method", "route", "status"] as const,
+		// Tuned for an IdP: token and authorize calls sit in the low tens of
+		// milliseconds when healthy, and the tail is what an outage moves.
+		buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+		registers: [registry],
+	});
+
+	const middleware: RequestHandler = (req: Request, res: Response, next: NextFunction) => {
+		const endTimer = requestDuration.startTimer();
+		let observed = false;
+		// Both terminal events, with a guard, rather than `finish` alone.
+		// `finish` covers every response the server completes — including ones
+		// produced by an error handler, and `req.route` is populated by then. But
+		// a client or proxy that disconnects mid-handler emits `close` WITHOUT
+		// `finish`, and those are disproportionately the slow and failing requests
+		// that RED metrics exist to surface; counting only `finish` would drop
+		// them from both the rate and the latency series.
+		const observe = () => {
+			if (observed) return;
+			observed = true;
+			endTimer({
+				method: methodLabel(req),
+				route: routeLabel(req),
+				status: String(res.statusCode),
+			});
+		};
+		res.once("finish", observe);
+		res.once("close", observe);
+		next();
+	};
+
+	const dependencyUp = new Gauge({
+		name: "auth_dependency_up",
+		help: "1 when a backing dependency answered its readiness probe, 0 otherwise.",
+		labelNames: ["dependency"] as const,
+		registers: [registry],
+	});
+
+	// Shared across scrapes so a partitioned backend does not accumulate one
+	// in-flight command per scrape (see `runReadinessProbes`).
+	const inFlight = new Map<string, Promise<unknown>>();
+
+	const route = (express: { Router: () => Router }, opts: MetricsRouteOptions): Router => {
+		const router = express.Router();
+		router.get(opts.path ?? "/metrics", async (_req: Request, res: Response) => {
+			// Sampled per scrape rather than held as state: a cached value would
+			// report a dependency healthy for as long as the cache lives, which is
+			// exactly the window an incident lives in.
+			const report = await runReadinessProbes(opts.probes, {
+				timeoutMs: opts.probeTimeoutMs,
+				inFlight,
+			});
+			for (const check of report.checks) {
+				dependencyUp.set({ dependency: check.name }, check.ok ? 1 : 0);
+			}
+
+			res.setHeader("Content-Type", registry.contentType);
+			res.setHeader("Cache-Control", "no-store");
+			res.send(await registry.metrics());
+		});
+		return router;
+	};
+
+	return { middleware, route };
+}

package/templates/standalone/src/modules.mts

@@ -16,6 +16,8 @@
 import path from "node:path";
 import {
 	type AppConfig,
+	consoleLogger,
+	createAuditSinkFactory,
 	createFederationTokenStoreFactory,
 	createInMemorySessionFamilyIndex,
 	createInMemorySessionFederationIndex,
@@ -25,7 +27,10 @@ import {
 	createRepositoryFactories,
 	defineModule,
 	type LifecycleRegistrar,
+	type Logger,
 	type Module,
+	type ReadinessRegistrar,
+	registerBuiltinAuditSinks,
 	registerBuiltinFederationTokenStores,
 	registerBuiltinKeyStores,
 } from "@o3co/auth-provider-core";
@@ -34,16 +39,20 @@ import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
 import { redisFederationTokenStoreBuilder } from "@o3co/auth-provider-redis";
 import { makeIoredisClients } from "@o3co/auth-provider-redis/ioredis";
 import { extractFederationSection } from "@o3co/auth-provider-session";
-// Named import is required here, not default. Under `module: "nodenext"`
-// with esModuleInterop, the default import resolves to the entire ioredis
-// CJS module-exports namespace object (because ioredis 5.x ships
-// `export = Redis`), so `new Redis(...)` raises TS2351 "not constructable".
+// 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.
 import { Redis } from "ioredis";
+import { createAuditLogger, createLoggerAuditSink } from "./logger.mjs";
 
 /**
  * Helper: turn a v0.4.x { type, [type]: {...} } adapter-config slice into the
@@ -218,6 +227,66 @@ export const federationTokenStoreModule: 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 { … } }`).
+ *
+ * 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).
+ */
+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" },
+			);
+		},
+	},
+});
+
 /**
  * @deprecated since Wave 5d (F4 PR2): split into `inMemorySessionStoresModule`
  * + `federationTokenStoreModule`. Re-exported for backward compatibility
@@ -235,10 +304,10 @@ export const storesModule: Module = defineModule({
 
 /**
  * Shared ioredis clients module — opens ONE long-lived ioredis connection
- * per replica, wraps it via `makeIoredisClients()` (returns 9 typed
+ * per replica, wraps it via `makeIoredisClients()` (returns 11 typed
  * per-purpose clients), and exposes the slots consumed by the standalone's
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
- * rate limiter).
+ * rate limiter + code repository + access-token denylist).
  *
  * 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).
@@ -273,26 +342,46 @@ export const storesModule: Module = defineModule({
 export const standaloneRedisClientsModule: Module = defineModule({
 	name: "standalone:redis-clients",
 	requires: ["config"] as const,
-	optional: ["lifecycleRegistrar"] as const,
+	optional: ["lifecycleRegistrar", "readinessRegistrar", "logger"] as const,
 	provides: {
-		refreshTokenFamilyClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).refreshTokenFamilyClient;
+		refreshTokenFamilyClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.refreshTokenFamilyClient;
 		},
-		userSessionStoreClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).userSessionStoreClient;
+		userSessionStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.userSessionStoreClient;
 		},
-		sessionRPRegistryClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).sessionRPRegistryClient;
+		sessionRPRegistryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.sessionRPRegistryClient;
 		},
-		sessionFamilyIndexClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).sessionFamilyIndexClient;
+		sessionFamilyIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.sessionFamilyIndexClient;
 		},
-		sessionFederationIndexClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar)
+		sessionFederationIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
-		rateLimiterClient: async ({ config, lifecycleRegistrar }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).rateLimiterClient;
+		rateLimiterClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.rateLimiterClient;
 		},
 		// OR-9: code-repository client wired off the same shared ioredis
 		// socket. `redisCodeRepositoryModule` consumes this slot when
@@ -300,12 +389,105 @@ export const standaloneRedisClientsModule: Module = defineModule({
 		// 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 }) => {
-			return getOrCreateClients(config as AppConfig, lifecycleRegistrar).codeRepositoryClient;
+		codeRepositoryClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, 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.
+		accessTokenDenylistClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.accessTokenDenylistClient;
 		},
 	},
 });
 
+/**
+ * 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.
+ *
+ * - `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.
+ */
+const SHARED_REDIS_TIMEOUTS = {
+	commandTimeout: 1_000,
+	connectTimeout: 5_000,
+	maxRetriesPerRequest: 3,
+	enableOfflineQueue: true,
+	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`
@@ -324,7 +506,10 @@ const clientsCache = new WeakMap<LifecycleRegistrar, ReturnType<typeof makeIored
 function getOrCreateClients(
 	config: AppConfig,
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
+	readinessRegistrar?: ReadinessRegistrar,
+	injectedLogger?: Logger,
 ): ReturnType<typeof makeIoredisClients> {
+	const logger = injectedLogger ?? consoleLogger;
 	const cached = lifecycleRegistrar ? clientsCache.get(lifecycleRegistrar) : undefined;
 	if (cached) return cached;
 
@@ -339,29 +524,57 @@ function getOrCreateClients(
 	}
 	const password = typeof cfg.password === "string" ? cfg.password : undefined;
 
-	// `lazyConnect: false` is the ioredis 5.x default; the explicit option
-	// documents the boot-time-connect contract so a future ioredis version
-	// flip does not silently change the failure mode.
-	const io = new Redis(cfg.url, { password, lazyConnect: false });
+	const io = new Redis(cfg.url, { password, ...SHARED_REDIS_TIMEOUTS });
 
-	// Attach error handler so unhandled "error" events from ioredis 5.x do
-	// not crash the Node.js process. Initial connection failures surface
-	// here; downstream adapter operations then fail visibly. TODO(D-4):
-	// swap `console.error` for the Logger interface once a v0.5.2 polish
-	// PR lands.
+	// Attach an error handler so unhandled "error" events do not crash the
+	// process. Initial connection failures surface here; downstream adapter
+	// operations then fail visibly.
 	io.on("error", (err: unknown) => {
-		console.error("[standalone:redis-clients] ioredis error", err);
+		logger.error({ err }, "standalone_redis_clients_error");
 	});
 
 	lifecycleRegistrar?.register(async () => {
 		await io.quit();
 	});
 
-	const clients = makeIoredisClients(io);
+	// 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.
+	readinessRegistrar?.register({
+		name: "redis",
+		check: () => io.ping(),
+	});
+
+	// The wrapper opens its own connections for refresh rotation
+	// (`refreshTokenFamilyClient.duplicate()`), which inherit no listeners from
+	// `io`; passing the logger lets those report through the same channel.
+	const clients = makeIoredisClients(io, { logger });
 	if (lifecycleRegistrar) clientsCache.set(lifecycleRegistrar, clients);
 	return clients;
 }
 
+/**
+ * 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
+ * wrote down.
+ */
+function optionalString(
+	slice: Record<string, unknown>,
+	field: string,
+): Record<string, string> | Record<string, never> {
+	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`);
+	}
+	return { [field]: value };
+}
+
 /**
  * Google federation config bridge — supplies the typed `googleFederationConfig`
  * ComponentMap slot from the `config.federations.google` slice.
@@ -369,6 +582,15 @@ function getOrCreateClients(
  * 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.
+ *
+ * #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.
  */
 export const googleFederationConfigModule: Module = defineModule({
 	name: "standalone:google-federation-config",
@@ -393,7 +615,33 @@ export const googleFederationConfigModule: Module = defineModule({
 					"federations.google requires clientId, clientSecret, callbackURL when enabled",
 				);
 			}
-			return { clientId, clientSecret, callbackURL };
+
+			// The allowlist is checked for shape here and for content by
+			// `createFederationRedirectPolicy`, which owns the URL rules. This
+			// only has to establish that HOCON produced a list of strings —
+			// `redirectAllowlist = "https://…"` (a bare string, the natural typo)
+			// would otherwise reach the policy as a config it cannot read.
+			const rawAllowlist = slice.redirectAllowlist;
+			let redirectAllowlist: Record<string, readonly string[]> | Record<string, never> = {};
+			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, " +
+							'e.g. ["https://app.example.com/welcome"]',
+					);
+				}
+				redirectAllowlist = { redirectAllowlist: rawAllowlist as readonly string[] };
+			}
+
+			return {
+				clientId,
+				clientSecret,
+				callbackURL,
+				...redirectAllowlist,
+				...optionalString(slice, "sessionDomain"),
+				...optionalString(slice, "authCallbackUrl"),
+				...optionalString(slice, "clientUrl"),
+			};
 		},
 	},
 });

package/templates/standalone/src/terminalError.mts

@@ -0,0 +1,60 @@
+/*
+ * 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 { errorEnvelope, type Logger } from "@o3co/auth-provider-core";
+import type { ErrorRequestHandler } from "express";
+
+/**
+ * Terminal Express error handler (#293 item 8).
+ *
+ * Anything a route threw past its own try/catch — and every body-parser
+ * rejection, which fires before any route runs — used to fall through to
+ * Express's default handler: an HTML 500 outside the structured-log pipeline,
+ * carrying a stack trace outside production. A client that parses only the
+ * RFC 6749 §5.2 JSON envelope this surface answers with everywhere else has
+ * no way to read that page.
+ *
+ * Body-parser failures (malformed JSON/form, over-limit, bad charset) carry
+ * their own 4xx `status` and are the client's fault: keep the status, wrap it
+ * in the shared envelope, and do not log them as server errors. Everything
+ * else is logged with the request path and answered `500 server_error`.
+ *
+ * Mount it AFTER every route (`app.use(handle.router)` included) — Express
+ * routes errors only to handlers registered later.
+ */
+export const createTerminalErrorHandler = (logger: Logger): ErrorRequestHandler => {
+	return (err, req, res, next) => {
+		// A failure after the response started is not ours to rewrite; handing
+		// it back lets Express close the connection.
+		if (res.headersSent) {
+			next(err);
+			return;
+		}
+		const status = (err as { status?: unknown; statusCode?: unknown } | null) ?? {};
+		const httpStatus =
+			typeof status.status === "number"
+				? status.status
+				: typeof status.statusCode === "number"
+					? status.statusCode
+					: undefined;
+		if (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500) {
+			const description = httpStatus === 413 ? "request body too large" : "malformed request body";
+			res.status(httpStatus).json(errorEnvelope("invalid_request", description));
+			return;
+		}
+		logger.error({ err, endpoint: req.path }, "unhandled_request_error");
+		res.status(500).json(errorEnvelope("server_error", "Internal server error"));
+	};
+};