@o3co/create-auth-provider 0.15.0 → 0.16.0

package/templates/standalone/src/__tests__/redis-connection-error-log.test.mts

@@ -0,0 +1,139 @@
+/*
+ * 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.
+ */
+
+/**
+ * What the template's shared Redis connection logs when the server refuses
+ * it: the real ioredis the template ships, against a TCP server that answers
+ * the way Redis answers a password it no longer accepts. ioredis puts the
+ * handshake it sent — `AUTH` and the password — on the error it emits, so
+ * the `error` listener must log core's `loggableError` projection, never
+ * the error. The logger here serialises every own property of what it is
+ * handed, as a deployment's logger may.
+ */
+
+import { once } from "node:events";
+import { type AddressInfo, createServer, type Socket } from "node:net";
+import type { LifecycleRegistrar, Logger } from "@o3co/auth-provider-core";
+import { describe, expect, it, vi } from "vitest";
+import { standaloneRedisClientsModule } from "#/modules.mjs";
+
+/** Redis's reply to a handshake whose password it does not accept. */
+const WRONGPASS = "-WRONGPASS invalid username-password pair or user is disabled.\r\n";
+
+/** The password the deployment is configured with, and the server no longer takes. */
+const STALE_PASSWORD = "stale-s3cret-redis-password";
+
+/** A TCP server that answers everything sent to it as Redis answers a refused password. */
+async function refusingRedis(): Promise<{ port: number; close: () => Promise<void> }> {
+	const sockets = new Set<Socket>();
+	const server = createServer((socket) => {
+		sockets.add(socket);
+		socket.on("close", () => sockets.delete(socket));
+		socket.on("data", () => {
+			socket.write(WRONGPASS);
+		});
+	});
+	server.listen(0, "127.0.0.1");
+	await once(server, "listening");
+	const { port } = server.address() as AddressInfo;
+	return {
+		port,
+		close: async () => {
+			for (const socket of sockets) socket.destroy();
+			await new Promise<void>((resolve) => server.close(() => resolve()));
+		},
+	};
+}
+
+/**
+ * A logger that serialises every own property of what it is handed, `cause`
+ * and non-enumerable fields included. `lines` is what it wrote; its levels
+ * are spies.
+ */
+const serialiseEverythingLogger = () => {
+	const lines: string[] = [];
+	const walk = (value: unknown, seen = new WeakSet<object>()): unknown => {
+		if (typeof value !== "object" || value === null) return value;
+		if (seen.has(value)) return "[circular]";
+		seen.add(value);
+		const out: Record<string, unknown> = {};
+		for (const key of Object.getOwnPropertyNames(value)) {
+			out[key] = walk((value as Record<string, unknown>)[key], seen);
+		}
+		return out;
+	};
+	const record = (level: string) =>
+		vi.fn((...args: unknown[]): void => {
+			lines.push(JSON.stringify({ level, args: walk(args) }));
+		});
+	const logger = {
+		trace: record("trace"),
+		debug: record("debug"),
+		info: record("info"),
+		warn: record("warn"),
+		error: record("error"),
+		fatal: record("fatal"),
+		child: () => logger,
+	};
+	return { logger: logger as typeof logger & Logger, lines };
+};
+
+describe("standaloneRedisClientsModule: the shared connection refused by the server", () => {
+	it("logs the connection's error as loggableError's projection, never the AUTH arguments ioredis puts on it", async () => {
+		const redis = await refusingRedis();
+		const cleanups: Array<() => Promise<void>> = [];
+		const lifecycleRegistrar: LifecycleRegistrar = {
+			register: (cleanup) => {
+				cleanups.push(cleanup);
+			},
+		};
+		const { logger, lines } = serialiseEverythingLogger();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		try {
+			await provides.refreshTokenFamilyClient({
+				config: {
+					refreshTokenFamilyStore: {
+						redis: { url: `redis://127.0.0.1:${redis.port}`, password: STALE_PASSWORD },
+					},
+				},
+				lifecycleRegistrar,
+				logger,
+			});
+			await vi.waitFor(() => expect(logger.error).toHaveBeenCalled(), { timeout: 10_000 });
+		} finally {
+			// `io.quit()`, as `handle.dispose()` runs it.
+			await Promise.all(cleanups.map((cleanup) => cleanup().catch(() => {})));
+			await redis.close();
+		}
+
+		expect(logger.error).toHaveBeenCalledWith(
+			{
+				err: expect.objectContaining({
+					name: "ReplyError",
+					detail: expect.stringMatching(/^WRONGPASS /),
+					// Which command the server refused, and nothing it carried.
+					command: { name: "hello" },
+				}),
+			},
+			"standalone_redis_clients_error",
+		);
+		for (const line of lines) expect(line).not.toContain(STALE_PASSWORD);
+	});
+});

package/templates/standalone/src/__tests__/replica-safety.test.mts

@@ -510,12 +510,22 @@ describe("#473: the Redis federation store's plaintext guard, booted from the sh
 		const config = resolveConfig({ ...PLAINTEXT_ENV, DEPLOYMENT_MODE: "single" });
 		handleRef = await boot(config, "development");
 		expect(handleRef.components.federationTokenStore?.kind).toBe("redis");
-		expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("allow-plaintext"));
+		expect(warnSpy).toHaveBeenCalledWith(
+			{ store: "federation-tokens", mode: "allow-plaintext" },
+			"federation_store_plaintext",
+		);
 	});
 
-	it("keeps the FEDERATION_TOKENS_ALLOW_INSECURE=1 escape hatch under multi, at CRITICAL", async () => {
+	it("keeps the FEDERATION_TOKENS_ALLOW_INSECURE=1 escape hatch under multi, logged at error", async () => {
 		process.env.FEDERATION_TOKENS_ALLOW_INSECURE = "1";
 		handleRef = await boot(resolveConfig(PLAINTEXT_ENV), "development");
-		expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("CRITICAL"));
+		expect(errorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				store: "federation-tokens",
+				deploymentMode: "multi",
+				override: "FEDERATION_TOKENS_ALLOW_INSECURE",
+			}),
+			"federation_store_plaintext_override",
+		);
 	});
 });

package/templates/standalone/src/__tests__/router-error-answers.test.mts

@@ -0,0 +1,149 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The template's composition, booted through core's `createApp` and mounted
+ * with no terminal handler of the template's after it — the router alone, as
+ * a composition root that copies nothing of `app.mts` mounts it.
+ *
+ * The OAuth and session routers parse their own bodies and have no error
+ * handler: a body parser's refusal on `/oauth/token`, `/oauth/introspect` or
+ * `/session/login`, and any error a route let through, went on to whatever
+ * the host had after the router. Only `app.mts` had a handler there, so any
+ * other host answered with Express's final handler — an HTML page, with the
+ * stack outside production, where V8's JSON error quotes the body it could
+ * not parse. The router core returns now answers them itself.
+ */
+
+import { defineModule } from "@o3co/auth-provider-core";
+import { Router } from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	basic,
+	type Composition,
+	compose,
+	JSON_TYPE,
+	KIB,
+	M2M,
+	padJson,
+} from "./all-modules-composition.fixture.mjs";
+
+let current: Composition | undefined;
+
+afterEach(async () => {
+	await current?.handle.dispose();
+	current = undefined;
+});
+
+/** A route that lets an error through, contributed as a deployment adds one. */
+const throwingRouteModule = defineModule({
+	name: "test:throwing-route",
+	contributes: {
+		routes: [
+			() => {
+				const router = Router();
+				router.get("/", () => {
+					throw new Error("a store said something: escaped-error-marker");
+				});
+				return { id: "test:throwing-route", mountPath: "/throws", handler: router };
+			},
+		],
+	},
+});
+
+/** The composition, the router alone mounted. */
+const boot = async (): Promise<Composition> => {
+	current = await compose({
+		terminalErrorHandler: false,
+		extraModules: () => [throwingRouteModule],
+	});
+	return current;
+};
+
+/** The routes that parse a body, and what each needs to reach its parser. */
+const PARSING_ROUTES = [
+	["/oauth/token", { authorization: basic(M2M) }],
+	["/oauth/introspect", { authorization: basic(M2M) }],
+	["/session/login", {}],
+] as const;
+
+const errorLines = (c: Composition) => c.logger.lines.filter((line) => line.level === "error");
+
+describe("the composed router, mounted alone, answers a body parser's refusal", () => {
+	it.each(PARSING_ROUTES)(
+		"%s: malformed JSON is 400 in the envelope, nothing logged",
+		async (path, headers) => {
+			const c = await boot();
+			const res = await request(c.app)
+				.post(path)
+				.set(headers)
+				.set("Content-Type", JSON_TYPE)
+				.send('{"password":"body-secret-marker');
+
+			expect(res.status).toBe(400);
+			expect(res.headers["content-type"]).toMatch(/^application\/json/);
+			expect(res.body).toEqual({ error: "invalid_request", error_description: "malformed_body" });
+			expect(res.text).not.toContain("body-secret-marker");
+			expect(res.text).not.toMatch(/ at /);
+			expect(errorLines(c)).toEqual([]);
+		},
+	);
+
+	it.each(PARSING_ROUTES)(
+		"%s: a body over the parser's limit is 413 in the envelope, nothing logged",
+		async (path, headers) => {
+			const c = await boot();
+			const res = await request(c.app)
+				.post(path)
+				.set(headers)
+				.set("Content-Type", JSON_TYPE)
+				.send(padJson(200 * KIB));
+
+			expect(res.status).toBe(413);
+			expect(res.headers["content-type"]).toMatch(/^application\/json/);
+			expect(res.body).toEqual({ error: "invalid_request", error_description: "body_too_large" });
+			expect(errorLines(c)).toEqual([]);
+		},
+	);
+});
+
+describe("the composed router, mounted alone, answers an error a route let through", () => {
+	it("is 500 server_error in the envelope, logged once at error", async () => {
+		const c = await boot();
+		const res = await request(c.app).get("/throws");
+
+		expect(res.status).toBe(500);
+		expect(res.headers["content-type"]).toMatch(/^application\/json/);
+		expect(res.body).toEqual({ error: "server_error", error_description: "unexpected_error" });
+		expect(res.text).not.toContain("escaped-error-marker");
+		expect(errorLines(c)).toEqual([
+			{
+				level: "error",
+				args: [
+					{
+						endpoint: "/throws",
+						err: expect.objectContaining({
+							name: "Error",
+							detail: "a store said something: escaped-error-marker",
+						}),
+					},
+					"unhandled_request_error",
+				],
+			},
+		]);
+	});
+});

package/templates/standalone/src/__tests__/shutdown.test.mts

@@ -30,8 +30,15 @@
  * and these tests are the contract the issue said was missing.
  */
 
-import type { Server } from "node:http";
-import type { Logger } from "@o3co/auth-provider-core";
+import { createServer, type Server } from "node:http";
+import {
+	type BootstrapMap,
+	createApp,
+	createMemoryReplaySeenSet,
+	defineModule,
+	type Logger,
+} from "@o3co/auth-provider-core";
+import { makeValidCoreConfig } from "@o3co/auth-provider-core/testing";
 import { describe, expect, it, vi } from "vitest";
 import {
 	cleanupAllowanceFor,
@@ -85,16 +92,53 @@ const makeLogger = () => {
 	return spy satisfies Logger;
 };
 
+/**
+ * A logger that serialises every own property of what it is handed, `cause`
+ * and non-enumerable fields included — a deployment is free to install one.
+ * `lines` is what it wrote; its levels are spies.
+ */
+const serialiseEverythingLogger = () => {
+	const lines: string[] = [];
+	const walk = (value: unknown, seen = new WeakSet<object>()): unknown => {
+		if (typeof value !== "object" || value === null) return value;
+		if (seen.has(value)) return "[circular]";
+		seen.add(value);
+		const out: Record<string, unknown> = {};
+		for (const key of Object.getOwnPropertyNames(value)) {
+			out[key] = walk((value as Record<string, unknown>)[key], seen);
+		}
+		return out;
+	};
+	const record = (level: string) =>
+		vi.fn((...args: unknown[]): void => {
+			lines.push(JSON.stringify({ level, args: walk(args) }));
+		});
+	const logger = {
+		trace: record("trace"),
+		debug: record("debug"),
+		info: record("info"),
+		warn: record("warn"),
+		error: record("error"),
+		fatal: record("fatal"),
+		child: vi.fn(() => logger as unknown as Logger),
+	};
+	return { logger: logger satisfies Logger, lines };
+};
+
+/** A logged projection's `stack`: frames only, from the first. */
+const FRAMES = expect.stringMatching(/^ {4}at /);
+
 /** Drive one shutdown without touching the real `process` or exiting. */
 function install(
 	opts: {
 		cleanup?: () => void | Promise<void>;
 		drainTimeoutMs?: number;
 		cleanupTimeoutMs?: number;
+		logger?: ReturnType<typeof makeLogger>;
 	} = {},
 ) {
 	const { server, spies, finishDraining, failClose } = makeServer();
-	const logger = makeLogger();
+	const logger = opts.logger ?? makeLogger();
 	const exit = vi.fn();
 	const signals = new Map<string, () => void>();
 
@@ -172,7 +216,12 @@ describe("installGracefulShutdown (#290)", () => {
 			signals.get("SIGTERM")?.();
 			await vi.advanceTimersByTimeAsync(5_000);
 			expect(exit).toHaveBeenCalledWith(1);
-			expect(logger.error).toHaveBeenCalled();
+			// Each stage is an event: object-first, a snake_case name.
+			expect(logger.info).toHaveBeenCalledWith({ drainTimeoutMs: 5_000 }, "shutdown_draining");
+			expect(logger.error).toHaveBeenCalledWith(
+				{ drainTimeoutMs: 5_000 },
+				"shutdown_drain_deadline_exceeded",
+			);
 		} finally {
 			vi.useRealTimers();
 		}
@@ -193,21 +242,91 @@ describe("installGracefulShutdown (#290)", () => {
 		}
 	});
 
-	it("reports a cleanup failure through the app logger, not console", async () => {
+	it("reports a cleanup failure through the app logger, not console, as loggableError's projection", async () => {
 		// Every other line this service emits is NDJSON through pino; a bare
 		// console.error on the shutdown path is the one a log pipeline drops.
-		const { logger, exit, signals, finishDraining } = install({
-			cleanup: () => {
-				throw new Error("redis quit failed");
+		// What a real `handle.dispose()` rejects with is an AggregateError of
+		// every cleanup's own error. The line names each member and its code,
+		// and carries nothing of what they hold: an OAuth library's refusal
+		// keeps the refresh answer it refused on a non-Error cause, an ioredis
+		// reply the write it refused.
+		const refusedRefresh = Object.assign(
+			new Error("invalid response encountered", {
+				cause: { body: { refresh_token: "1//0g-UPSTREAM-S3CRET" } },
+			}),
+			{ name: "ClientError", code: "OAUTH_INVALID_RESPONSE" },
+		);
+		const refusedWrite = Object.assign(
+			new Error("READONLY You can't write against a read only replica."),
+			{
+				name: "ReplyError",
+				command: { name: "set", args: ["fg:credential:grant-1", "1//0g-ARGS-S3CRET"] },
+			},
+		);
+		const failingCleanups = defineModule({
+			name: "test:failing-cleanups",
+			provides: {
+				replaySeenSet: () => createMemoryReplaySeenSet(),
+				challengeStore: () => ({}) as never,
+			},
+			lifecycle: {
+				replaySeenSet: {
+					eager: true,
+					cleanup: () => {
+						throw refusedRefresh;
+					},
+				},
+				challengeStore: {
+					eager: true,
+					cleanup: () => {
+						throw refusedWrite;
+					},
+				},
 			},
 		});
+		const handle = await createApp({
+			modules: [failingCleanups],
+			bootstrapComponents: {
+				config: makeValidCoreConfig(),
+				pathResolver: (path: string) => path,
+			} as unknown as BootstrapMap,
+		});
+		const { logger, lines } = serialiseEverythingLogger();
+		const { exit, signals, finishDraining } = install({
+			logger,
+			cleanup: () => handle.dispose(),
+		});
 		signals.get("SIGTERM")?.();
 		finishDraining();
 		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
 		expect(logger.error).toHaveBeenCalledWith(
-			expect.objectContaining({ err: expect.any(Error) }),
-			expect.stringContaining("cleanup"),
+			{
+				err: {
+					name: "AggregateError",
+					detail: expect.stringMatching(/^AppHandle\.dispose: 2 cleanup errors /),
+					stack: FRAMES,
+					aggregateErrors: expect.arrayContaining([
+						{
+							name: "ClientError",
+							detail: "invalid response encountered",
+							code: "OAUTH_INVALID_RESPONSE",
+							stack: FRAMES,
+						},
+						{
+							name: "ReplyError",
+							detail: "READONLY You can't write against a read only replica.",
+							command: { name: "set" },
+							stack: FRAMES,
+						},
+					]),
+				},
+			},
+			"shutdown_cleanup_failed",
 		);
+		for (const line of lines) {
+			expect(line).not.toContain("S3CRET");
+			expect(line).not.toContain("refresh_token");
+		}
 	});
 
 	it("still exits when cleanup throws — a failed dispose must not wedge the process", async () => {
@@ -221,19 +340,37 @@ describe("installGracefulShutdown (#290)", () => {
 		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
 	});
 
-	it("does not report a failed close as a clean drain", async () => {
+	it("does not report a failed close as a clean drain, and logs the failure as loggableError's projection", async () => {
 		// `server.close` reports through its callback -- "Server is not running"
 		// is the common one, but any listener teardown failure lands there.
 		// Exiting 0 on it would tell an orchestrator the listener came down
-		// when it did not.
-		const { exit, logger, signals, failClose } = install();
+		// when it did not. A real server that is not listening gives Node's
+		// own error; the line keeps its name, message, code and frames.
+		const server = createServer();
+		const { logger, lines } = serialiseEverythingLogger();
+		const exit = vi.fn();
+		const signals = new Map<string, () => void>();
+		installGracefulShutdown(server, {
+			logger,
+			exit,
+			onSignal: (name, handler) => signals.set(name, handler),
+			offSignal: (name) => signals.delete(name),
+		});
 		signals.get("SIGTERM")?.();
-		failClose(new Error("Server is not running"));
 		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
 		expect(logger.error).toHaveBeenCalledWith(
-			expect.objectContaining({ err: expect.any(Error) }),
-			expect.stringContaining("close"),
+			{
+				err: {
+					name: "Error",
+					detail: "Server is not running.",
+					code: "ERR_SERVER_NOT_RUNNING",
+					stack: FRAMES,
+				},
+			},
+			"shutdown_server_close_failed",
 		);
+		// The frames, never the header line that repeats the message.
+		for (const line of lines) expect(line).not.toContain("Error [ERR_SERVER_NOT_RUNNING]");
 	});
 
 	it("still runs cleanup when close reports a failure", async () => {
@@ -263,8 +400,8 @@ describe("installGracefulShutdown (#290)", () => {
 			finishDraining();
 			await vi.advanceTimersByTimeAsync(5_000);
 			expect(logger.error).toHaveBeenCalledWith(
-				expect.objectContaining({ cleanupTimeoutMs: 5_000 }),
-				expect.stringContaining("cleanup timed out"),
+				{ cleanupTimeoutMs: 5_000 },
+				"shutdown_cleanup_timed_out",
 			);
 			expect(exit).toHaveBeenCalledWith(1);
 		} finally {
@@ -311,7 +448,7 @@ describe("installGracefulShutdown (#290)", () => {
 		await new Promise((resolve) => setImmediate(resolve));
 		expect(logger.info).toHaveBeenCalledWith(
 			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
-			"graceful shutdown: complete",
+			"shutdown_complete",
 		);
 		expect(exit).toHaveBeenCalledWith(1);
 	});
@@ -323,7 +460,7 @@ describe("installGracefulShutdown (#290)", () => {
 		await new Promise((resolve) => setImmediate(resolve));
 		expect(logger.info).toHaveBeenCalledWith(
 			{ reason: "drained", drain: "drained", exitCode: 0 },
-			"graceful shutdown: complete",
+			"shutdown_complete",
 		);
 	});
 

package/templates/standalone/src/__tests__/smoke.test.mts

@@ -618,27 +618,46 @@ describe("standalone smoke test", () => {
 			expect(names).toContain("standalone:redis-clients");
 		});
 
-		it("buildModules honors legacy repositories.code.type='redis' with deprecation warn when oauth.code.adapter is absent", () => {
-			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-			try {
-				const legacyConfig = {
-					...config,
-					oauth: { ...config.oauth, code: undefined },
-					repositories: {
-						...config.repositories,
-						code: { type: "redis" as const, defaultExpiresIn: 600 },
+		it("buildModules honors legacy repositories.code.type='redis' with one object-first deprecation warn when oauth.code.adapter is absent", () => {
+			const warn = vi.fn();
+			const logger = {
+				trace: vi.fn(),
+				debug: vi.fn(),
+				info: vi.fn(),
+				warn,
+				error: vi.fn(),
+				fatal: vi.fn(),
+				child: () => logger,
+			};
+			const legacyConfig = {
+				...config,
+				oauth: { ...config.oauth, code: undefined },
+				repositories: {
+					...config.repositories,
+					code: { type: "redis" as const, defaultExpiresIn: 600 },
+				},
+			};
+			const modules = buildModules(legacyConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+				logger,
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redis-code-repository");
+			expect(warn.mock.calls).toEqual([
+				[
+					{
+						key: "repositories.code.type",
+						env: "CLIENT_CODE_TYPE",
+						replacement: "oauth.code.adapter",
+						replacementEnv: "OAUTH_CODE_ADAPTER",
 					},
-				};
-				const modules = buildModules(legacyConfig, {
-					keyStoreModule: testKeyStoreModule,
-					repositoriesModule: testRepositoriesModule,
-					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
-				});
-				const names = modules.map((m) => m.name);
-				expect(names).toContain("redis-code-repository");
-				expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("repositories.code.type"));
-			} finally {
-				warnSpy.mockRestore();
+					"config_key_deprecated",
+				],
+			]);
+			for (const level of ["trace", "debug", "info", "error", "fatal"] as const) {
+				expect(logger[level]).not.toHaveBeenCalled();
 			}
 		});