@o3co/create-auth-provider 0.15.0 → 0.16.0

package/templates/standalone/src/routes.mts

@@ -0,0 +1,95 @@
+/*
+ * 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 routes, in the order `app.mts` mounts them: liveness, readiness
+ * and the metrics scrape ahead of the composed auth router — so they keep
+ * answering while the auth pipeline is degraded, which is when an operator
+ * needs them — then that router, then core's terminal error handler, last,
+ * because Express hands an error only to handlers mounted after the route
+ * that raised it. A function rather than inline in `app.mts`, so the order
+ * and the handler can be tested as the process mounts them.
+ *
+ * The handler is core's `terminalErrorHandler`, the one that already ends
+ * the composed router, so an error one of the host's routes lets through
+ * is answered as every other route's is: `500 server_error` /
+ * `unexpected_error` in the RFC 6749 envelope with `Cache-Control:
+ * no-store`, logged once as `unhandled_request_error` with the path through
+ * `auditErrorText` and the error's `loggableError` projection; a refusal an
+ * `http-errors` error marks as the client's keeps its 4xx; a response whose
+ * headers already went out is closed rather than handed to Express's final
+ * handler, which would print the stack.
+ */
+
+import {
+	createHealthcheckRouter,
+	createReadinessRouter,
+	type Logger,
+	type ReadinessProbe,
+	terminalErrorHandler,
+} from "@o3co/auth-provider-core";
+import express, { type Express, type Router } from "express";
+import type { Metrics } from "./metrics.mjs";
+
+export interface MountRoutesOptions {
+	/** The router `createApp` composed (`handle.router`). */
+	readonly router: Router;
+	/** The readiness probes the builders registered (`handle.readinessProbes`). */
+	readonly probes: readonly ReadinessProbe[];
+	/** Per-probe deadline, in milliseconds: `config.http.readinessTimeoutMs`. */
+	readonly readinessTimeoutMs: number;
+	readonly metrics: Metrics;
+	readonly logger: Logger;
+}
+
+/** Mount the host's routes, the composed router and the terminal error handler on `app`. */
+export function mountRoutes(app: Express, options: MountRoutesOptions): void {
+	// 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: options.probes,
+			timeoutMs: options.readinessTimeoutMs,
+			logger: options.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(
+		options.metrics.route(express, {
+			probes: options.probes,
+			probeTimeoutMs: options.readinessTimeoutMs,
+		}),
+	);
+
+	// The composed auth router, which ends in core's terminal handler.
+	app.use(options.router);
+	// Core's terminal handler again, LAST (#293 item 8), for the host routes
+	// above: Express routes an error only to handlers registered after the
+	// route that threw it. See the file header.
+	app.use(terminalErrorHandler(options.logger));
+}

package/templates/standalone/src/shutdown.mts

@@ -15,7 +15,7 @@
  */
 
 import type { Server } from "node:http";
-import type { Logger } from "@o3co/auth-provider-core";
+import { type Logger, loggableError } from "@o3co/auth-provider-core";
 
 /**
  * Graceful shutdown for the scaffolded server (#290).
@@ -54,13 +54,20 @@ import type { Logger } from "@o3co/auth-provider-core";
  *    and the process exits **non-zero** — an orchestrator that only ever sees
  *    `0` cannot tell a clean drain from one that ran out of time.
  * 5. **`cleanup` runs after draining, before exit**, and its failure is logged
- *    through the app logger and reflected in the exit code. It never wedges the
- *    process: a dispose that throws still exits, and one that never settles is
- *    cut off at `cleanupTimeoutMs`.
+ *    through the app logger — as core's `loggableError` projection, never the
+ *    error, which holds every cleanup's own error — and reflected in the exit
+ *    code. It never wedges the process: a dispose that throws still exits, and
+ *    one that never settles is cut off at `cleanupTimeoutMs`.
  * 6. **A `close` that fails is not reported as a clean drain.** `server.close`
  *    reports through its callback, and treating that as success would tell an
  *    orchestrator the listener came down when it did not.
  *
+ * Every stage is one object-first line under a snake_case event name:
+ * `shutdown_draining` (info, `drainTimeoutMs`), `shutdown_drain_deadline_exceeded`
+ * (error), `shutdown_server_close_failed` (error, `err`), `shutdown_cleanup_timed_out`
+ * (error, `cleanupTimeoutMs`), `shutdown_cleanup_failed` (error, `err`) and
+ * `shutdown_complete` (info, `reason`, `drain`, `exitCode`).
+ *
  * Size `drainTimeoutMs` plus `cleanupTimeoutMs` **below** the orchestrator's
  * own kill grace period (Kubernetes `terminationGracePeriodSeconds` is 30s by
  * default, compose `stop_grace_period` 10s; with federation grants on the sum
@@ -226,7 +233,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		let outcome = reason;
 		try {
 			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
-				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
+				logger.error({ cleanupTimeoutMs }, "shutdown_cleanup_timed_out");
 				exitCode = 1;
 				outcome = "cleanup-timeout";
 			}
@@ -234,12 +241,14 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 			// Through the app logger, not `console.error`: a shutdown that
 			// failed to release its Redis connections is exactly the line an
 			// operator needs to find later, and a bare write is the one their
-			// pipeline drops.
-			logger.error({ err }, "graceful shutdown: cleanup failed");
+			// pipeline drops. The projection, not the error: `dispose()`
+			// rejects with every cleanup's own error on `errors`, a store's
+			// write — and what it wrote — among them.
+			logger.error({ err: loggableError(err) }, "shutdown_cleanup_failed");
 			exitCode = 1;
 			outcome = "cleanup-failed";
 		}
-		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
+		logger.info({ reason: outcome, drain: reason, exitCode }, "shutdown_complete");
 		exit(exitCode);
 	};
 
@@ -247,13 +256,10 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		if (shuttingDown) return;
 		shuttingDown = true;
 		for (const signal of SIGNALS) offSignal(signal, handler);
-		logger.info({ drainTimeoutMs }, "graceful shutdown: draining");
+		logger.info({ drainTimeoutMs }, "shutdown_draining");
 
 		const deadline = setTimeout(() => {
-			logger.error(
-				{ drainTimeoutMs },
-				"graceful shutdown: drain deadline exceeded, closing remaining connections",
-			);
+			logger.error({ drainTimeoutMs }, "shutdown_drain_deadline_exceeded");
 			server.closeAllConnections();
 			void finish(1, "drain-timeout");
 		}, drainTimeoutMs);
@@ -269,7 +275,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 				// here. Reporting "drained" and exiting 0 on it would tell an
 				// orchestrator the shutdown went cleanly when the listener did
 				// not actually come down.
-				logger.error({ err }, "graceful shutdown: server close failed");
+				logger.error({ err: loggableError(err) }, "shutdown_server_close_failed");
 				void finish(1, "close-failed");
 				return;
 			}

package/templates/versions.json

@@ -1,17 +1,17 @@
 {
-	"@o3co/auth-provider-core": "0.15.0",
-	"@o3co/auth-provider-device-grant": "0.15.0",
-	"@o3co/auth-provider-dpop": "0.15.0",
-	"@o3co/auth-provider-mtls": "0.15.0",
-	"@o3co/auth-provider-federation-apple": "0.15.0",
-	"@o3co/auth-provider-federation-google": "0.15.0",
-	"@o3co/auth-provider-federation-github": "0.15.0",
-	"@o3co/auth-provider-federation-grants": "0.15.0",
-	"@o3co/auth-provider-federation-oidc": "0.15.0",
-	"@o3co/auth-provider-oauth": "0.15.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.15.0",
-	"@o3co/auth-provider-session": "0.15.0",
-	"@o3co/auth-provider-foundation": "0.15.0",
-	"@o3co/auth-provider-redis": "0.15.0",
-	"@o3co/auth-provider-webauthn": "0.15.0"
+	"@o3co/auth-provider-core": "0.16.0",
+	"@o3co/auth-provider-device-grant": "0.16.0",
+	"@o3co/auth-provider-dpop": "0.16.0",
+	"@o3co/auth-provider-mtls": "0.16.0",
+	"@o3co/auth-provider-federation-apple": "0.16.0",
+	"@o3co/auth-provider-federation-google": "0.16.0",
+	"@o3co/auth-provider-federation-github": "0.16.0",
+	"@o3co/auth-provider-federation-grants": "0.16.0",
+	"@o3co/auth-provider-federation-oidc": "0.16.0",
+	"@o3co/auth-provider-oauth": "0.16.0",
+	"@o3co/auth-provider-oauth-token-exchange": "0.16.0",
+	"@o3co/auth-provider-session": "0.16.0",
+	"@o3co/auth-provider-foundation": "0.16.0",
+	"@o3co/auth-provider-redis": "0.16.0",
+	"@o3co/auth-provider-webauthn": "0.16.0"
 }

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

@@ -1,96 +0,0 @@
-/*
- * 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/terminalError.mts

@@ -1,60 +0,0 @@
-/*
- * Copyright 2026 1o1 Co. Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { errorEnvelope, type Logger } from "@o3co/auth-provider-core";
-import type { ErrorRequestHandler } from "express";
-
-/**
- * Terminal Express error handler (#293 item 8).
- *
- * Anything a route threw past its own try/catch — and every body-parser
- * rejection, which fires before any route runs — used to fall through to
- * Express's default handler: an HTML 500 outside the structured-log pipeline,
- * carrying a stack trace outside production. A client that parses only the
- * RFC 6749 §5.2 JSON envelope this surface answers with everywhere else has
- * no way to read that page.
- *
- * Body-parser failures (malformed JSON/form, over-limit, bad charset) carry
- * their own 4xx `status` and are the client's fault: keep the status, wrap it
- * in the shared envelope, and do not log them as server errors. Everything
- * else is logged with the request path and answered `500 server_error`.
- *
- * Mount it AFTER every route (`app.use(handle.router)` included) — Express
- * routes errors only to handlers registered later.
- */
-export const createTerminalErrorHandler = (logger: Logger): ErrorRequestHandler => {
-	return (err, req, res, next) => {
-		// A failure after the response started is not ours to rewrite; handing
-		// it back lets Express close the connection.
-		if (res.headersSent) {
-			next(err);
-			return;
-		}
-		const status = (err as { status?: unknown; statusCode?: unknown } | null) ?? {};
-		const httpStatus =
-			typeof status.status === "number"
-				? status.status
-				: typeof status.statusCode === "number"
-					? status.statusCode
-					: undefined;
-		if (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500) {
-			const description = httpStatus === 413 ? "request body too large" : "malformed request body";
-			res.status(httpStatus).json(errorEnvelope("invalid_request", description));
-			return;
-		}
-		logger.error({ err, endpoint: req.path }, "unhandled_request_error");
-		res.status(500).json(errorEnvelope("server_error", "Internal server error"));
-	};
-};