@o3co/create-auth-provider 0.9.0 → 0.11.0

package/templates/standalone/src/app.mts

@@ -14,16 +14,23 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import { gracefulShutdown } from "@o3co/auth.utils";
-import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createHealthcheckRouter,
+	createReadinessRouter,
+} from "@o3co/auth-provider-core";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import express from "express";
 import helmet from "helmet";
-
-import logger from "#/logger.mjs";
 import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
+import { createAppLogger } from "./logger.mjs";
+import { createMetrics } from "./metrics.mjs";
+import { installGracefulShutdown } from "./shutdown.mjs";
+import { createTerminalErrorHandler } from "./terminalError.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
 // ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
@@ -44,9 +51,23 @@ const config: AppConfig = validate(
 	AppConfigSchema,
 );
 
+// The logger is built from config so its level is operator-controlled, and it
+// is wired into `bootstrapComponents` so every module that declares
+// `optional: ["logger"]` receives this one rather than falling back to its own
+// default. Without that slot filled, configuring a level here would change
+// nothing about what the modules emit.
+const logger = createAppLogger(config);
+
 await (async (): Promise<void> => {
 	// Step 2: Create the Express app and apply base security middleware.
 	const app = express();
+	// `false` | `true` | a hop count | a list of IPs / CIDR ranges / named
+	// ranges — the schema hands Express exactly the shapes `trust proxy`
+	// already understands, validated at boot so a typo'd range fails here
+	// rather than becoming a rule that silently never matches (#292). Prefer
+	// naming the proxy: `true` believes a forwarded client address from anyone
+	// who can reach this process, and `req.ip` is what every IP-keyed rate
+	// limit is bucketed on.
 	app.set("trust proxy", config.http.trustProxy);
 	app.use(
 		helmet({
@@ -59,6 +80,12 @@ await (async (): Promise<void> => {
 		}),
 	);
 
+	// Timing middleware goes ahead of everything so the histogram covers the
+	// whole stack — including responses produced by middleware that short-circuits
+	// before any route runs, such as the rate limiter's 429s.
+	const metrics = createMetrics();
+	app.use(metrics.middleware);
+
 	// Step 3: Boot the auth pipeline.
 	// D-5: express-session middleware is now wired by `sessionStoreModule`
 	// inside the boot planner. Mount order is enforced by declarationIndex
@@ -77,17 +104,49 @@ await (async (): Promise<void> => {
 		bootstrapComponents: {
 			config,
 			pathResolver: import.meta.resolve,
+			logger,
 		},
 	});
 
-	// Step 4: Wire host-level routes (healthcheck) before the auth router so
-	// they remain reachable even when the auth pipeline is degraded.
-	app.get("/_healthcheck", (_req, res) => {
-		res.status(200).json({ status: "ok" });
-	});
+	// Step 4: Wire host-level routes before the auth router so they remain
+	// reachable even when the auth pipeline is degraded — which is exactly when
+	// an operator needs an answer from them.
+	//
+	// Liveness: the process is up and its event loop is turning. Deliberately
+	// static — restarting the process would not bring Redis back, so a Redis
+	// outage must not read as "this container is broken, kill it".
+	app.use(createHealthcheckRouter(express));
+
+	// Readiness: can this replica serve right now? Redis backs sessions,
+	// authorization codes and refresh-token families in the deployable
+	// defaults, so a replica that has lost it answers 503 here and should be
+	// taken out of rotation. Probes are contributed by the builders that own
+	// each connection; a memory-only deployment registers none and is always
+	// ready.
+	app.use(
+		createReadinessRouter(express, {
+			probes: handle.readinessProbes,
+			timeoutMs: config.http.readinessTimeoutMs,
+			logger,
+		}),
+	);
+
+	// Prometheus scrape endpoint. Same reasoning as the probes above: it has to
+	// keep answering while the auth pipeline is degraded, because that is when
+	// the series matter.
+	app.use(
+		metrics.route(express, {
+			probes: handle.readinessProbes,
+			probeTimeoutMs: config.http.readinessTimeoutMs,
+		}),
+	);
 
 	// Step 5: Mount the composed auth router and start the HTTP server.
 	app.use(handle.router);
+	// Terminal error handler LAST (#293 item 8): Express routes an error only
+	// to handlers registered after the route that threw it. See
+	// `terminalError.mts` for what it catches and why.
+	app.use(createTerminalErrorHandler(logger));
 	const server = app.listen(config.http.port, (): void => {
 		logger.info(`Server is running on http://localhost:${config.http.port}`);
 	});
@@ -95,5 +154,14 @@ await (async (): Promise<void> => {
 	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
 	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain
 	// (Redis clients, interval timers).
-	gracefulShutdown(server, () => handle.dispose());
+	//
+	// #290: in the template rather than a dependency, because "does SIGTERM
+	// wait for in-flight requests, and for how long?" has to be answerable
+	// from the code you deploy. See `shutdown.mts` for the stated guarantees
+	// and for the deadline the previous implementation did not have. Size
+	// `drainTimeoutMs` below your orchestrator's kill grace period.
+	installGracefulShutdown(server, {
+		logger,
+		cleanup: () => handle.dispose(),
+	});
 })();

package/templates/standalone/src/buildModules.mts

@@ -19,6 +19,7 @@ import {
 	defaultRefreshTokenFamilyRotationModule,
 	jwksModule,
 	type Module,
+	memoryAccessTokenDenylistModule,
 	memoryRateLimiterModule,
 } from "@o3co/auth-provider-core";
 import { googleFederationModule } from "@o3co/auth-provider-federation-google";
@@ -28,6 +29,7 @@ import {
 	oauthSessionModule,
 } from "@o3co/auth-provider-oauth";
 import {
+	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
@@ -35,6 +37,7 @@ import {
 } from "@o3co/auth-provider-redis";
 import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
 import {
+	auditSinkModule,
 	federationTokenStoreModule,
 	googleFederationConfigModule,
 	inMemoryCodeRepositoryModule,
@@ -65,6 +68,18 @@ export interface BuildModulesOverrides {
 	 * is dropped from the manifest unless the override list includes it.
 	 */
 	readonly refreshTokenFamilyModules?: readonly Module[];
+	/**
+	 * #287: override the module filling the `auditSink` slot. Tests substitute
+	 * a sink they can assert on; the default writes the audit trail to stdout
+	 * and is what a deployment gets.
+	 *
+	 * The override REPLACES the default — it does not add a second provider,
+	 * which would be a boot-time slot collision. There is intentionally no way
+	 * to pass "no audit sink": #304's sink policy is that the trail is always
+	 * wired, and a composition that genuinely wants events discarded says so by
+	 * providing a sink that discards them.
+	 */
+	readonly auditSinkModule?: Module;
 }
 
 /**
@@ -95,6 +110,13 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// single ioredis socket per replica. Memory-only deployments skip it.
 	const rateLimiterAdapter = config.rateLimiter?.adapter ?? "memory";
 	const userSessionStoresAdapter = config.userSessionStores?.adapter ?? "memory";
+	// #277: the RFC 7009 access-token denylist. Unlike the switches above there
+	// is no "no denylist" branch — `oauthModule` reads the `accessTokenDenylist`
+	// slot because it mounts `/oauth/revoke`, and core's boot validator refuses
+	// a composition that reads the slot with nothing filling it, since the
+	// endpoint would answer 200 while the token kept working. The switch here is
+	// only over WHICH denylist.
+	const accessTokenDenylistAdapter = config.accessTokenDenylist?.adapter ?? "memory";
 
 	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
 	// authoritative switch; the legacy `repositories.code.type = "redis"`
@@ -131,7 +153,8 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		refreshTokenFamilyUsesRedis ||
 		rateLimiterAdapter === "redis" ||
 		userSessionStoresAdapter === "redis" ||
-		codeRepositoryAdapter === "redis";
+		codeRepositoryAdapter === "redis" ||
+		accessTokenDenylistAdapter === "redis";
 
 	// Federation-token store is always wired; only the 4 user-session
 	// stores switch on the adapter. Pre-Wave-5d the redis branch dropped
@@ -156,6 +179,15 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 			? [redisCodeRepositoryModule]
 			: [inMemoryCodeRepositoryModule];
 
+	// #277: mutually-exclusive denylist pair, same shape as the three switches
+	// above. The memory branch is a dev convenience and nothing more: it forks
+	// per replica, so `deployment.mode = "multi"` refuses it by name (see core's
+	// replica-safety guard). The template's own application.conf ships `"redis"`.
+	const accessTokenDenylistModules: Module[] =
+		accessTokenDenylistAdapter === "redis"
+			? [redisAccessTokenDenylistModule]
+			: [memoryAccessTokenDenylistModule];
+
 	return [
 		// D-5: sessionStoreModule wires the express-session middleware into the
 		// boot-planner-managed lifecycle. **Mount order is enforced by this
@@ -177,6 +209,13 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
 		overrides.keyStoreModule ?? keyStoreModule,
 		overrides.repositoriesModule ?? repositoriesModule,
+		// #287: the audit sink, always wired. Unlike every switch above there is
+		// no "off" branch — the routes' security events (`token.issued.failure`,
+		// `authorize.rejected`, `rate_limit.unavailable`, …) went nowhere in the
+		// shipped artifact because the slot was empty and `emitAuditEvent`
+		// no-ops when it is. Which sink is a config question
+		// (`audit.sink.type`); whether there is one is not.
+		overrides.auditSinkModule ?? auditSinkModule,
 		// Shared ioredis clients — only when at least one consumer adapter
 		// actually needs Redis. Memory-only deployments skip this so they
 		// don't open an unused socket.
@@ -192,6 +231,9 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		...rateLimiterModules,
 		// OAuth code repository: redis (multi-replica) or memory (single-instance).
 		...codeRepositoryModules,
+		// RFC 7009 access-token denylist: redis (shared revocations) or memory
+		// (single-instance dev). Always wired — see the switch above.
+		...accessTokenDenylistModules,
 		// RT family store: redis by default (closes OR-1); override path
 		// swaps to `[memoryRefreshTokenFamilyStoreModule]` for unit tests.
 		...refreshTokenFamilyModules,

package/templates/standalone/src/configPath.mts

@@ -31,8 +31,8 @@ const REFERENCE_CONF_SUBPATH = "@o3co/auth-provider-core/reference.conf";
  * 3-tier HOCON precedence chain (reference.conf → application.conf → {env}.conf).
  *
  * Primary path: `import.meta.resolve` (Node.js Stability 1.2 RC, unflagged
- * since Node 18.19.0 / 20.6.0 — the engine floor of every package in this
- * scope). Fallback: `createRequire(import.meta.url).resolve(...)`. The
+ * since Node 18.19.0 / 20.6.0 — well below this scope's Node 22 engine floor,
+ * so it is always available). Fallback: `createRequire(import.meta.url).resolve(...)`. The
  * fallback covers two edge cases:
  *
  * 1. A future Node release deprecates or alters the sync form of

package/templates/standalone/src/logger.mts

@@ -13,6 +13,94 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createLogger } from "@o3co/auth.utils";
+import type { AppConfig, AuditSink, Logger } from "@o3co/auth-provider-core";
+import { pino, stdSerializers } from "pino";
 
-export default createLogger("provider");
+/**
+ * The composition root's logger, and the value wired into the `logger`
+ * ComponentMap slot that every module reads.
+ *
+ * pino, emitting newline-delimited JSON on stdout — the shape every log
+ * aggregator ingests without a parser, and the reason `Logger` was given
+ * pino's two-overload call signature in the first place. A pino instance
+ * therefore satisfies `Logger` structurally, with no adapter.
+ *
+ * Two things this closes:
+ *
+ * - **The slot was never filled.** Only a value satisfying `Logger` can occupy
+ *   it, and the logger this template used before exposes four methods with a
+ *   narrower call shape. So every module that declares `optional: ["logger"]`
+ *   — oauth, session, dpop, mtls, token-exchange — silently fell back to its
+ *   own `consoleLogger` default, and nothing an operator configured here
+ *   reached any of them.
+ * - **`logging.level` is honoured.** pino drops sub-threshold calls before
+ *   formatting, so `trace` / `debug` cost nothing in production rather than
+ *   being emitted and filtered downstream.
+ *
+ * `silent` is pino's own name for "emit nothing", so the config vocabulary
+ * maps across unchanged.
+ */
+export function createAppLogger(config: AppConfig): Logger {
+	return pino({
+		name: "provider",
+		level: config.logging.level,
+		// `err` is pino's conventional key for an Error, and every structured
+		// event in this stack uses it — `logger.error({ err }, "…_error")`.
+		// Without the serialiser an Error stringifies to `{}` and the stack is
+		// lost exactly where it is needed.
+		serializers: { err: stdSerializers.err },
+	});
+}
+
+/**
+ * The stream the audit trail is written on: `name: "audit"`, newline-delimited
+ * JSON on stdout, in the same pino envelope as every other line this template
+ * emits. One output style, so an aggregator ingests security events and
+ * application logs through one parser and separates them on `name`.
+ *
+ * **It takes no config, and its level is fixed.** That is the point rather
+ * than an oversight. `logging.level` is a diagnostics knob — `warn` is an
+ * ordinary production setting and `silent` a legitimate one — and an audit
+ * trail is evidence, not diagnostics. Routing audit events through the
+ * application logger would mean either of those settings silently deleting
+ * the record of who authenticated, what was issued, and what was refused:
+ * the same drop #287 is about, reached from the operator's side instead of
+ * the scaffold's. Where audit events go is chosen by `audit.sink.type`, and
+ * that selector has no "none" (#304).
+ *
+ * A second pino instance rather than a child of the app logger: a child
+ * inherits its parent's level, and depending on a level-override subtlety to
+ * keep the audit trail alive is exactly the kind of thing that stops being
+ * true in a later refactor without anything failing.
+ */
+export function createAuditLogger(): Logger {
+	return pino({
+		name: "audit",
+		level: "info",
+		serializers: { err: stdSerializers.err },
+	});
+}
+
+/**
+ * `AuditSink` writing each event through `auditLogger` — the `"logger"` sink
+ * kind this template registers and ships as its default.
+ *
+ * The event is nested under `audit` rather than spread at the top level:
+ * `level`, `time`, `name` and `msg` belong to the log envelope, and a future
+ * audit field colliding with one of them would corrupt the line for every
+ * consumer. The event type doubles as the message so operators alert on the
+ * name — `token.issued.failure`, `authorize.rejected` — the same way they
+ * already alert on `session_store_redis_error`.
+ *
+ * Errors are core's problem, not this function's: `emitAuditEvent` dispatches
+ * without awaiting and swallows rejections, because audit recording must never
+ * add latency to (or fail) an auth flow.
+ */
+export function createLoggerAuditSink(auditLogger: Logger): AuditSink {
+	return {
+		kind: "logger",
+		async record(event) {
+			auditLogger.info({ audit: event }, event.type);
+		},
+	};
+}

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 };
+}