@o3co/create-auth-provider 0.15.0 → 0.16.0

package/templates/standalone/src/__tests__/host-routes.test.mts

@@ -0,0 +1,141 @@
+/*
+ * 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 host's own routes — liveness, readiness, the metrics scrape — mounted
+ * as the process mounts them (`mountRoutes`), and what an error one of them
+ * lets through is answered with.
+ *
+ * The composed router answers its own errors with core's terminal handler.
+ * The host's routes sat in front of a handler of the template's own, which
+ * answered in other words ("Internal server error"), took any 4xx `status`
+ * for the client's mistake and answered it as one, handed an error on to
+ * Express once the headers were out (whose final handler prints the stack),
+ * and logged the path as it arrived. Core's handler is now the one after
+ * them too, so a deployment answers every route's error the same way.
+ */
+
+import type { Logger, ReadinessProbe } from "@o3co/auth-provider-core";
+import express, { Router } from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { createMetrics } from "#/metrics.mjs";
+import { mountRoutes } from "#/routes.mjs";
+
+const spyLogger = () => {
+	const logger = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: () => logger,
+	};
+	return logger;
+};
+
+/** A probe that breaks its own contract: reading its `name` throws. */
+const probeWhoseNameThrows = (thrown: Error): ReadinessProbe =>
+	({
+		get name(): string {
+			throw thrown;
+		},
+		check: async () => undefined,
+	}) as ReadinessProbe;
+
+const host = (probes: readonly ReadinessProbe[]) => {
+	const logger = spyLogger();
+	const app = express();
+	mountRoutes(app, {
+		router: Router(),
+		probes,
+		readinessTimeoutMs: 1_000,
+		metrics: createMetrics(),
+		logger: logger as unknown as Logger,
+	});
+	return { app, logger };
+};
+
+/** Every call on a level other than `error`. */
+const otherLevels = (logger: ReturnType<typeof spyLogger>) =>
+	[logger.trace, logger.debug, logger.info, logger.warn, logger.fatal].flatMap(
+		(level) => level.mock.calls,
+	);
+
+describe("the host's routes, mounted as the process mounts them", () => {
+	it("/_healthcheck answers 200, and nothing is logged", async () => {
+		const { app, logger } = host([]);
+		const res = await request(app).get("/_healthcheck");
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual({ status: "ok" });
+		expect(logger.error).not.toHaveBeenCalled();
+		expect(otherLevels(logger)).toEqual([]);
+	});
+
+	it.each(["/readyz", "/metrics"])(
+		"%s: an error it lets through is 500 server_error in the envelope, no-store, logged once with its projection",
+		async (path) => {
+			const { app, logger } = host([
+				probeWhoseNameThrows(new Error("probe registry at internal-host-marker is gone")),
+			]);
+
+			const res = await request(app).get(path);
+
+			expect(res.status).toBe(500);
+			expect(res.headers["content-type"]).toMatch(/^application\/json/);
+			expect(res.headers["cache-control"]).toBe("no-store");
+			expect(res.body).toEqual({ error: "server_error", error_description: "unexpected_error" });
+			expect(res.text).not.toContain("internal-host-marker");
+			expect(logger.error).toHaveBeenCalledTimes(1);
+			const [fields, event, ...rest] = logger.error.mock.calls[0] as unknown[];
+			expect(event).toBe("unhandled_request_error");
+			expect(rest).toEqual([]);
+			expect(fields).toEqual({
+				endpoint: path,
+				err: expect.objectContaining({
+					name: "Error",
+					detail: "probe registry at internal-host-marker is gone",
+				}),
+			});
+			expect((fields as { err: unknown }).err).not.toBeInstanceOf(Error);
+			expect(otherLevels(logger)).toEqual([]);
+		},
+	);
+
+	it("takes a 4xx status an error did not mark as the client's for the server's: 500, logged", async () => {
+		// A store's or a library's error can carry an HTTP status of its own —
+		// the answer it got — which is not this server's answer to the client.
+		const { app, logger } = host([
+			probeWhoseNameThrows(
+				Object.assign(new Error("the probe registry refused this deployment"), { status: 403 }),
+			),
+		]);
+
+		const res = await request(app).get("/readyz");
+
+		expect(res.status).toBe(500);
+		expect(res.body).toEqual({ error: "server_error", error_description: "unexpected_error" });
+		expect(logger.error).toHaveBeenCalledTimes(1);
+		expect(logger.error).toHaveBeenCalledWith(
+			{
+				endpoint: "/readyz",
+				err: expect.objectContaining({ name: "Error", status: 403 }),
+			},
+			"unhandled_request_error",
+		);
+	});
+});

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

@@ -0,0 +1,128 @@
+/*
+ * 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.
+ */
+
+/**
+ * Starting the listener: one object-first `server_listening` line once the
+ * socket is bound — and none for a port that was never bound.
+ *
+ * The line used to be a template string, `Server is running on
+ * http://localhost:<port>`, which a log pipeline indexes as free text rather
+ * than as an event with a port. And the standalone called Express 5's
+ * `app.listen`, which hands its callback the server's `error` as well as its
+ * `listening`: a callback that ignored its argument announced a server on a
+ * port another process held, while the error that should have ended the
+ * process was swallowed. `listen` now builds the server and wires its events
+ * itself.
+ */
+
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { Logger } from "@o3co/auth-provider-core";
+import express from "express";
+import { afterEach, describe, expect, it } from "vitest";
+import { listen } from "#/listen.mjs";
+
+/** A logger that records what each level is handed. */
+function recordingLogger(): { logger: Logger; calls: Array<{ level: string; args: unknown[] }> } {
+	const calls: Array<{ level: string; args: unknown[] }> = [];
+	const record =
+		(level: string) =>
+		(...args: unknown[]): void => {
+			calls.push({ level, args });
+		};
+	const logger: Logger = {
+		trace: record("trace"),
+		debug: record("debug"),
+		info: record("info"),
+		warn: record("warn"),
+		error: record("error"),
+		fatal: record("fatal"),
+		child: () => logger,
+	};
+	return { logger, calls };
+}
+
+const opened: Server[] = [];
+
+afterEach(async () => {
+	await Promise.all(
+		opened.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))),
+	);
+});
+
+describe("listen", () => {
+	it("says server_listening once, object-first, with the port the socket holds", async () => {
+		const { logger, calls } = recordingLogger();
+		const server = await listen(express(), 0, logger);
+		opened.push(server);
+		const { port } = server.address() as AddressInfo;
+		expect(port).toBeGreaterThan(0);
+		expect(calls).toEqual([{ level: "info", args: [{ port }, "server_listening"] }]);
+	});
+
+	it("logs a server error after the bind — server_error, the projection — rather than swallowing it", async () => {
+		// Once the socket is bound, a later `error` (accept EMFILE) went to
+		// Express 5's spent listen callback and was lost — and the one after
+		// it, with no listener left, threw out of the process.
+		const { logger, calls } = recordingLogger();
+		const server = await listen(express(), 0, logger);
+		opened.push(server);
+		calls.length = 0;
+
+		const failure = Object.assign(new Error("accept EMFILE"), { code: "EMFILE" });
+		server.emit("error", failure);
+		server.emit("error", failure);
+
+		expect(calls).toEqual([
+			{
+				level: "error",
+				args: [{ err: expect.objectContaining({ name: "Error", code: "EMFILE" }) }, "server_error"],
+			},
+			{
+				level: "error",
+				args: [{ err: expect.objectContaining({ name: "Error", code: "EMFILE" }) }, "server_error"],
+			},
+		]);
+		const line = calls[0]?.args[0] as { err: unknown };
+		expect(line.err).not.toBeInstanceOf(Error);
+	});
+
+	it("leaves the bound server one error listener, server_error's: the bind's own is removed", async () => {
+		// The listener that turns a bind failure into a rejection has done its
+		// job once the socket is bound. Left attached, it would take every
+		// later error beside server_error's — a callback already spent.
+		const { logger } = recordingLogger();
+		const server = await listen(express(), 0, logger);
+		opened.push(server);
+
+		expect(server.listenerCount("error")).toBe(1);
+		// And nothing of `listen`'s own left on `listening`: an http.Server
+		// keeps one there itself (its connection tracking).
+		expect(server.listenerCount("listening")).toBe(createServer().listenerCount("listening"));
+	});
+
+	it("rejects with the server's error for a port already bound, and announces nothing", async () => {
+		const holder = createServer();
+		// Every interface, as `server.listen(port)` binds, so the two collide.
+		await new Promise<void>((resolve) => holder.listen(0, resolve));
+		opened.push(holder);
+		const { port } = holder.address() as AddressInfo;
+
+		const { logger, calls } = recordingLogger();
+		await expect(listen(express(), port, logger)).rejects.toMatchObject({ code: "EADDRINUSE" });
+		expect(calls).toEqual([]);
+	});
+});

package/templates/standalone/src/__tests__/logger-projection.test.mts

@@ -0,0 +1,77 @@
+/*
+ * 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 own logger writes for a projected error — the line on
+ * stdout, from `createAppLogger` in a process of its own, as the service
+ * writes it. Every field of core's `loggableError` projection must reach
+ * it, at every level of the cause chain: the logger's `err` serializer must
+ * not take the projection for an Error and fold its causes into one message.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const templateRoot = fileURLToPath(new URL("../..", import.meta.url));
+const tsxCli = createRequire(import.meta.url).resolve("tsx/cli");
+
+/**
+ * A request failure caused by a Store failure caused by a parse failure,
+ * logged through `createAppLogger` in a child process; the line it wrote.
+ */
+const SCRIPT = `
+const { createAppLogger } = await import("./src/logger.mts");
+const { loggableError } = await import("@o3co/auth-provider-core");
+let parse;
+try { JSON.parse('{"a":1,'); } catch (err) { parse = err; }
+const store = Object.assign(new Error("the Store could not be read", { cause: parse }), {
+	name: "StoreTransportError", code: "ECONNREFUSED", reason: "unreachable", storeStatus: 503,
+});
+const failed = Object.assign(new Error("request failed", { cause: store }), {
+	type: "upstream.failed", status: 502,
+});
+createAppLogger({ logging: { level: "info" } }).error({ err: loggableError(failed) }, "unhandled_request_error");
+`;
+
+describe("createAppLogger writes a projected error whole", () => {
+	it("keeps every field of every level of the cause chain on the line", () => {
+		const stdout = execFileSync(
+			process.execPath,
+			[tsxCli, "--input-type=module", "--eval", SCRIPT],
+			{ cwd: templateRoot, encoding: "utf8" },
+		);
+		const line = JSON.parse(stdout.trim().split("\n").at(-1) ?? "{}") as {
+			msg?: string;
+			err?: Record<string, unknown>;
+		};
+
+		expect(line.msg).toBe("unhandled_request_error");
+		expect(line.err).toMatchObject({
+			name: "Error",
+			type: "upstream.failed",
+			status: 502,
+			cause: {
+				name: "StoreTransportError",
+				code: "ECONNREFUSED",
+				reason: "unreachable",
+				storeStatus: 503,
+				cause: { name: "SyntaxError", position: 7 },
+			},
+		});
+	});
+});

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

@@ -138,13 +138,26 @@ describe("GET /metrics", () => {
 		// `close` fires without `finish` when a client or proxy gives up
 		// mid-handler, and those are disproportionately the slow and failing
 		// requests RED metrics exist to surface.
+		//
+		// Sequenced on the server's own events, never on a fixed wait: the abort
+		// goes out once the handler holds the request, and /metrics is read once
+		// the response has closed. A 30 ms sleep either side raced a loaded
+		// machine — an abort sent before the request reached its route was
+		// counted as `unmatched`, or not at all, and one whose close had not yet
+		// been processed was read as nothing.
 		const metrics = createMetrics();
 		const app = express();
 		app.use(metrics.middleware);
 		app.use(metrics.route(express, { probes: [], probeTimeoutMs: 100 }));
+		const handling = Promise.withResolvers<void>();
+		const closed = Promise.withResolvers<void>();
 		app.get("/slow", (_req, res) => {
-			// Never responds; the test aborts the socket instead.
-			void res;
+			// Never responds; the test aborts the socket instead. This listener is
+			// added after the metrics middleware's, and a response emits `close`
+			// to its listeners in the order they were added, so once it runs the
+			// request has been observed.
+			res.once("close", () => closed.resolve());
+			handling.resolve();
 		});
 
 		const server = await listenOnLoopback(app);
@@ -154,17 +167,19 @@ describe("GET /metrics", () => {
 			const pending = fetch(`http://127.0.0.1:${port}/slow`, {
 				signal: controller.signal,
 			}).catch(() => undefined);
-			await new Promise((resolve) => setTimeout(resolve, 30));
+			await handling.promise;
 			controller.abort();
 			await pending;
-			await new Promise((resolve) => setTimeout(resolve, 30));
+			await closed.promise;
 
 			const res = await request(app).get("/metrics");
 			const slow = res.text
 				.split("\n")
 				.filter((l) => l.startsWith("http_request_duration_seconds_count"))
 				.filter((l) => l.includes('route="/slow"'));
-			expect(slow.length).toBeGreaterThan(0);
+			// One request, counted once, under the route it had reached.
+			expect(slow).toHaveLength(1);
+			expect(slow[0]?.trim().endsWith(" 1")).toBe(true);
 		} finally {
 			server.close();
 		}

package/templates/standalone/src/__tests__/post-logout-redirect.test.mts

@@ -0,0 +1,187 @@
+/*
+ * 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.
+ */
+
+/**
+ * A logout's `post_logout_redirect_uri` reaches the upstream federation's
+ * end-session call only once it has matched one of the client's registered
+ * `postLogoutRedirectUris` — at `/oauth/logout` and at
+ * `POST /oauth/federation/:name/logout` alike.
+ *
+ * Google publishes no end-session endpoint, and without one configured its
+ * adapter sends the browser straight to the `postLogoutRedirectUri` it is
+ * handed. Both logout routes used to hand it the caller's value unchecked,
+ * ahead of the allowlist check that guarded their own redirect, so a fresh
+ * id_token of the caller's own and `post_logout_redirect_uri=https://evil…`
+ * made this provider's origin answer `303` to any site. With an end-session
+ * endpoint configured, the unchecked value was forwarded to the upstream
+ * instead.
+ *
+ * The redirect asserted here is the one a browser would follow: the real
+ * Google adapter, composed as a deployment composes it
+ * (`google-session.fixture.mts`).
+ */
+
+import type express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	type GoogleSession,
+	type GoogleWiring,
+	idTokenHint,
+	REGISTERED_POST_LOGOUT_REDIRECT_URI as REGISTERED,
+	signInLinkedToGoogle,
+} from "./google-session.fixture.mjs";
+
+const UNREGISTERED = "https://evil.example/landing";
+const GOOGLE_LOGOUT = "https://accounts.google.com/Logout";
+const UPSTREAM_END_SESSION = "https://idp-logout.example/end-session";
+const UPSTREAM_ID_TOKEN = "upstream-id-token";
+
+/** Google's end-session endpoint, where a deployment names one. */
+const WITH_END_SESSION: GoogleWiring = { endSessionEndpoint: UPSTREAM_END_SESSION };
+
+describe("a logout's post_logout_redirect_uri reaches the upstream only once it is registered", () => {
+	let session: GoogleSession | undefined;
+
+	afterEach(async () => {
+		await session?.dispose();
+		session = undefined;
+	});
+
+	/** Alice signed in, with Google linked and its id_token held for the end-session call. */
+	async function signedInWithGoogle(google: GoogleWiring): Promise<GoogleSession> {
+		session = await signInLinkedToGoogle({
+			google,
+			tokens: {
+				accessToken: "upstream-access-token",
+				expiresAt: null,
+				refreshToken: undefined,
+				idToken: UPSTREAM_ID_TOKEN,
+				tokenType: "Bearer",
+				scope: undefined,
+				grantedScope: undefined,
+			},
+		});
+		return session;
+	}
+
+	const rpLogout = (app: express.Express, sid: string, postLogoutRedirectUri: string) =>
+		request(app)
+			.get("/oauth/logout")
+			.query({
+				id_token_hint: idTokenHint(sid),
+				post_logout_redirect_uri: postLogoutRedirectUri,
+				state: "s-1",
+			});
+
+	const federationLogout = (
+		app: express.Express,
+		accessToken: string,
+		postLogoutRedirectUri: string,
+	) =>
+		request(app)
+			.post("/oauth/federation/google/logout")
+			.set("Authorization", `Bearer ${accessToken}`)
+			.type("form")
+			.send({ post_logout_redirect_uri: postLogoutRedirectUri, state: "s-1" });
+
+	describe("GET /oauth/logout, Google with no end-session endpoint", () => {
+		it("does not send the browser to an unregistered post_logout_redirect_uri", async () => {
+			const { app, sid, userSessionStore } = await signedInWithGoogle("shipped");
+
+			const res = await rpLogout(app, sid, UNREGISTERED);
+
+			expect(res.status).toBe(303);
+			expect(new URL(res.headers.location as string).origin).not.toBe("https://evil.example");
+			// Google's own logout page: the adapter's answer when it is handed no
+			// redirect target, which is what an unregistered one now is.
+			expect(res.headers.location).toBe(`${GOOGLE_LOGOUT}?state=s-1`);
+			// The logout itself still happened.
+			expect(await userSessionStore.get(sid)).toBeNull();
+		});
+
+		it("still returns the browser to a registered post_logout_redirect_uri, with state", async () => {
+			const { app, sid, userSessionStore } = await signedInWithGoogle("shipped");
+
+			const res = await rpLogout(app, sid, REGISTERED);
+
+			expect(res.status).toBe(303);
+			expect(res.headers.location).toBe(`${REGISTERED}?state=s-1`);
+			expect(await userSessionStore.get(sid)).toBeNull();
+		});
+	});
+
+	describe("GET /oauth/logout, Google with a configured end-session endpoint", () => {
+		it("does not forward an unregistered post_logout_redirect_uri to the upstream", async () => {
+			const { app, sid } = await signedInWithGoogle(WITH_END_SESSION);
+
+			const res = await rpLogout(app, sid, UNREGISTERED);
+
+			expect(res.status).toBe(303);
+			const location = new URL(res.headers.location as string);
+			expect(`${location.origin}${location.pathname}`).toBe(UPSTREAM_END_SESSION);
+			expect(location.searchParams.get("id_token_hint")).toBe(UPSTREAM_ID_TOKEN);
+			expect(location.searchParams.has("post_logout_redirect_uri")).toBe(false);
+			expect(res.headers.location).not.toContain("evil.example");
+		});
+
+		it("forwards a registered one", async () => {
+			const { app, sid } = await signedInWithGoogle(WITH_END_SESSION);
+
+			const res = await rpLogout(app, sid, REGISTERED);
+
+			expect(res.status).toBe(303);
+			const location = new URL(res.headers.location as string);
+			expect(`${location.origin}${location.pathname}`).toBe(UPSTREAM_END_SESSION);
+			expect(location.searchParams.get("post_logout_redirect_uri")).toBe(REGISTERED);
+			expect(location.searchParams.get("state")).toBe("s-1");
+		});
+	});
+
+	describe("POST /oauth/federation/google/logout", () => {
+		it("does not send the browser to an unregistered post_logout_redirect_uri", async () => {
+			const { app, sid, accessToken, sessionFederationIndex } = await signedInWithGoogle("shipped");
+
+			const res = await federationLogout(app, accessToken, UNREGISTERED);
+
+			expect(res.status).toBe(303);
+			expect(new URL(res.headers.location as string).origin).not.toBe("https://evil.example");
+			expect(res.headers.location).toBe(`${GOOGLE_LOGOUT}?state=s-1`);
+			// The federation was disconnected all the same.
+			expect(await sessionFederationIndex.listFederations(sid)).not.toContain("google");
+		});
+
+		it("still returns the browser to one registered for the token's client", async () => {
+			const { app, accessToken } = await signedInWithGoogle("shipped");
+
+			const res = await federationLogout(app, accessToken, REGISTERED);
+
+			expect(res.status).toBe(303);
+			expect(res.headers.location).toBe(`${REGISTERED}?state=s-1`);
+		});
+
+		it("does not forward an unregistered one to a configured end-session endpoint", async () => {
+			const { app, accessToken } = await signedInWithGoogle(WITH_END_SESSION);
+
+			const res = await federationLogout(app, accessToken, UNREGISTERED);
+
+			expect(res.status).toBe(303);
+			const location = new URL(res.headers.location as string);
+			expect(`${location.origin}${location.pathname}`).toBe(UPSTREAM_END_SESSION);
+			expect(location.searchParams.has("post_logout_redirect_uri")).toBe(false);
+		});
+	});
+});