@o3co/create-auth-provider 0.8.0 → 0.10.0

package/templates/standalone/src/__tests__/terminal-error.test.mts

@@ -0,0 +1,96 @@
+/*
+ * 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 { Logger } from "@o3co/auth-provider-core";
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { createTerminalErrorHandler } from "../terminalError.mjs";
+
+const makeLogger = () => {
+	const error = vi.fn();
+	const logger = {
+		error,
+		warn: vi.fn(),
+		info: vi.fn(),
+		debug: vi.fn(),
+	} as unknown as Logger;
+	return { logger, error };
+};
+
+const makeApp = (logger: Logger) => {
+	const app = express();
+	app.use(express.json());
+	app.post("/echo", (_req, res) => {
+		res.status(200).json({ ok: true });
+	});
+	app.get("/boom", () => {
+		throw new Error("route exploded");
+	});
+	app.use(createTerminalErrorHandler(logger));
+	return app;
+};
+
+describe("terminal error handler (#293 item 8)", () => {
+	it("answers malformed JSON with the client's 400 in the shared envelope, not Express's HTML page", async () => {
+		const { logger, error } = makeLogger();
+		const res = await request(makeApp(logger))
+			.post("/echo")
+			.set("Content-Type", "application/json")
+			.send("{not json");
+
+		expect(res.status).toBe(400);
+		expect(res.headers["content-type"]).toContain("application/json");
+		expect(res.body.error).toBe("invalid_request");
+		// The client's malformed body is not a server error worth an error line.
+		expect(error).not.toHaveBeenCalled();
+	});
+
+	it("keeps the body parser's own status for an over-limit body (413)", async () => {
+		const { logger } = makeLogger();
+		const app = express();
+		app.use(express.json({ limit: 16 }));
+		app.post("/echo", (_req, res) => {
+			res.status(200).json({ ok: true });
+		});
+		app.use(createTerminalErrorHandler(logger));
+
+		const res = await request(app)
+			.post("/echo")
+			.set("Content-Type", "application/json")
+			.send(JSON.stringify({ pad: "x".repeat(64) }));
+
+		expect(res.status).toBe(413);
+		expect(res.body.error).toBe("invalid_request");
+		expect(res.body.error_description).toBe("request body too large");
+	});
+
+	it("answers an unexpected route throw with 500 server_error and logs it structurally", async () => {
+		const { logger, error } = makeLogger();
+		const res = await request(makeApp(logger)).get("/boom");
+
+		expect(res.status).toBe(500);
+		expect(res.body).toEqual({
+			error: "server_error",
+			error_description: "Internal server error",
+		});
+		// No stack trace on the wire — the envelope is the whole body.
+		expect(JSON.stringify(res.body)).not.toContain("route exploded");
+		expect(error).toHaveBeenCalledWith(
+			expect.objectContaining({ endpoint: "/boom" }),
+			"unhandled_request_error",
+		);
+	});
+});

package/templates/standalone/src/__tests__/three-tier-resolution.test.mts

@@ -19,6 +19,7 @@ import { type AppConfig, AppConfigSchema } from "@o3co/auth-provider-core";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import { describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
 
 // config/ is two levels above this test file:
@@ -26,10 +27,13 @@ import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPa
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
 // Provide required secrets so AppConfigSchema parse succeeds. These are
-// test-only values — no real keys are embedded here.
+// test-only values — no real keys are embedded here. #282: SESSION_SECRET
+// carries a 256-bit entropy floor, so these clear it (the '.' characters keep
+// them outside the base64 alphabet, so the UTF-8 length is what counts).
 const testEnv = {
-	OAUTH_JWT_SECRET: "test-secret-three-tier",
-	SESSION_SECRET: "test-session-secret-three-tier",
+	OAUTH_JWT_SECRET: "test-secret-three-tier.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_SECRET: "test-session-secret-three-tier.at-least-32-bytes.ok",
 };
 
 function buildResolvedConfig(env: string, extraEnv: Record<string, string> = {}): AppConfig {
@@ -75,10 +79,15 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		// so OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED=false reaches the resolved value.
 		// Without the repeated env line, the substitution at reference.conf is
 		// shadowed by the template's literal `true`.
-		// Note: ts.hocon substitutes env vars as strings; the schema (passthrough)
-		// preserves the string. The assertion checks the string form so that
-		// the precedence invariant is testable now; a future schema-coercion PR
-		// (separate from this one) will make this resolve to boolean false.
+		// Note: ts.hocon substitutes env vars as strings, and `oauth.grants` is
+		// `z.object({}).passthrough()` — an open tree each grant module's own
+		// `configSchema` validates — so no shape-walking coercion reaches this
+		// leaf and the string survives to the resolved config. #288 unified the
+		// coercion for every DECLARED boolean in the schema and deliberately
+		// left this one alone: every consumer of a grant's `enabled`
+		// (`GrantRegistry.isEnabled`, `oauthAuthorization`, `oauthSession`)
+		// already reads `true` and `"true"` as enabled and everything else,
+		// `"false"` included, as not-enabled.
 		const config = buildResolvedConfig("development", {
 			OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED: "false",
 		});
@@ -114,4 +123,105 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		});
 		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
 	});
+
+	// #287 — the audit trail as the shipped artifact resolves it. The section is
+	// declared in core's schema for a load-bearing reason: `AppConfigSchema` is
+	// a plain `z.object` and strips what it does not declare, so an undeclared
+	// `audit` block would vanish between `parseFile` and `buildModules` and the
+	// sink selector would read `undefined` while the config sat in the file
+	// looking effective. These assertions run the real three-tier merge, so they
+	// fail if either layer stops carrying the key.
+	describe("#287: the audit sink as the shipped artifact resolves it", () => {
+		it("resolves audit.sink.type to the template's logger sink with nothing set", () => {
+			const config = buildResolvedConfig("production");
+			expect(config.audit?.sink.type).toBe("logger");
+		});
+
+		it("wires exactly one auditSink provider for that resolved config", () => {
+			const modules = buildModules(buildResolvedConfig("production"));
+			const providers = modules.filter((m) => Object.keys(m.provides ?? {}).includes("auditSink"));
+			expect(providers).toHaveLength(1);
+		});
+
+		it("lets an operator select core's built-in console sink by env var", () => {
+			// The env-override line has to be repeated at the template layer or
+			// the literal `"logger"` shadows reference.conf's substitution — the
+			// same precedence rule the grant tests above pin.
+			const config = buildResolvedConfig("production", { AUDIT_SINK_TYPE: "console" });
+			expect(config.audit?.sink.type).toBe("console");
+		});
+
+		it("reference.conf's own default is a sink, not a drop", () => {
+			// A consumer that resolves against reference.conf alone still lands on
+			// a sink. #304's sink policy is stdout JSON, never "none", and the
+			// library layer has to hold that on its own — a composition root that
+			// forgets to override it must not thereby lose its audit trail.
+			const referenceOnly = validate(
+				parseFile(resolveLibraryReferenceConfPath(), { env: testEnv }),
+				AppConfigSchema,
+			);
+			expect(referenceOnly.audit?.sink.type).toBe("console");
+		});
+	});
+
+	// #277 — this is the shape the umbrella E2E (o3co/auth) boots: the shipped
+	// application.conf, `DEPLOYMENT_MODE=multi`, and one shared ioredis socket.
+	// The assertions below are what keep that stack booting: a memory denylist
+	// under `multi` is refused by the replica-safety guard, and NO denylist is
+	// refused by the #277 guard, so the template has to land on "redis" without
+	// the deployment naming it.
+	describe("#277: access-token revocation as the shipped artifact resolves it", () => {
+		it("resolves accessTokenDenylist.adapter to redis with nothing set", () => {
+			const config = buildResolvedConfig("production");
+			expect(config.accessTokenDenylist?.adapter).toBe("redis");
+		});
+
+		it("resolves oauth.revocation.accessToken to denylist with nothing set", () => {
+			const config = buildResolvedConfig("production");
+			expect(config.oauth.revocation?.accessToken).toBe("denylist");
+		});
+
+		it("picks the replica-safe denylist module for that resolved config", () => {
+			const names = buildModules(buildResolvedConfig("production")).map((m) => m.name);
+			expect(names).toContain("redis-access-token-denylist");
+			expect(names).not.toContain("core-access-token-denylist-memory");
+		});
+
+		it("leaves nothing replica-unsafe under the umbrella E2E's environment", async () => {
+			// The environment `o3co/auth`'s tests/docker-compose.yml sets. Under
+			// `DEPLOYMENT_MODE=multi` the replica-safety guard fails boot naming
+			// every in-memory shared store, so the denylist this change adds has to
+			// come out of that environment as the Redis one — from the template's
+			// own config, since the compose file names no denylist variable.
+			// Asserted against the guard's own list rather than a module name, so a
+			// rename cannot quietly invalidate it.
+			const { REPLICA_UNSAFE_MODULES } = await import("@o3co/auth-provider-core");
+			const config = buildResolvedConfig("production", {
+				USER_SESSION_STORES_ADAPTER: "redis",
+				RATE_LIMITER_ADAPTER: "redis",
+				OAUTH_CODE_ADAPTER: "redis",
+			});
+			const names = buildModules(config).map((m) => m.name);
+			expect(names).toContain("redis-access-token-denylist");
+			for (const name of names) {
+				expect(REPLICA_UNSAFE_MODULES).not.toContain(name);
+			}
+		});
+
+		it("lets a single-instance deployment opt down to memory by env var", () => {
+			const config = buildResolvedConfig("production", {
+				ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+			});
+			expect(config.accessTokenDenylist?.adapter).toBe("memory");
+			const names = buildModules(config).map((m) => m.name);
+			expect(names).toContain("core-access-token-denylist-memory");
+		});
+
+		it("lets a deployment declare access-token revocation unsupported by env var", () => {
+			const config = buildResolvedConfig("production", {
+				OAUTH_REVOCATION_ACCESS_TOKEN: "unsupported",
+			});
+			expect(config.oauth.revocation?.accessToken).toBe("unsupported");
+		});
+	});
 });

package/templates/standalone/src/app.mts

@@ -15,15 +15,22 @@
  */
 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 { 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}`);
 	});

package/templates/standalone/src/buildModules.mts

@@ -17,7 +17,9 @@ import {
 	type AppConfig,
 	defaultRefreshTokenFamilyRevocationModule,
 	defaultRefreshTokenFamilyRotationModule,
+	jwksModule,
 	type Module,
+	memoryAccessTokenDenylistModule,
 	memoryRateLimiterModule,
 } from "@o3co/auth-provider-core";
 import { googleFederationModule } from "@o3co/auth-provider-federation-google";
@@ -27,6 +29,7 @@ import {
 	oauthSessionModule,
 } from "@o3co/auth-provider-oauth";
 import {
+	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
@@ -34,6 +37,7 @@ import {
 } from "@o3co/auth-provider-redis";
 import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
 import {
+	auditSinkModule,
 	federationTokenStoreModule,
 	googleFederationConfigModule,
 	inMemoryCodeRepositoryModule,
@@ -64,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;
 }
 
 /**
@@ -94,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"`
@@ -130,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
@@ -155,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
@@ -165,10 +198,24 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		oauthModule({ config }),
 		oauthSessionModule({ config }),
 		oauthAuthorizationModule({ config }),
+		// JWKS publishing — always wired (depends only on config + keyStore).
+		// Contributed by core's `jwksModule`, NOT oauthModule: a provider that
+		// signs tokens must publish its verification keys regardless of OIDC
+		// issuer config. Co-installed with oauthModule so the discovery
+		// `jwks_uri` (advertised by oauthModule when an issuer is set) always
+		// resolves to this mounted route.
+		jwksModule,
 		sessionModule,
 		...(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.
@@ -184,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);
+		},
+	};
+}