@o3co/create-auth-provider 0.17.0 → 0.18.0-rc.1

package/templates/standalone/src/shutdown.mts

@@ -1,213 +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.
- */
-
-/*
- * Graceful shutdown for the scaffolded server, kept in the template so that
- * "does SIGTERM wait for in-flight requests, and for how long?" is answerable
- * from the code you deploy. See the template README, "Shutdown guarantees".
- */
-
-import type { Server } from "node:http";
-import { type Logger, loggableError } from "@o3co/auth-provider-core";
-
-/** Options for {@link installGracefulShutdown}. */
-export interface GracefulShutdownOptions {
-	readonly logger: Logger;
-	/** Reverse-topological component cleanup — normally `handle.dispose()`. */
-	readonly cleanup?: () => void | Promise<void>;
-	/** How long in-flight requests get before connections are cut. Default 10s. */
-	readonly drainTimeoutMs?: number;
-	/**
-	 * How long `cleanup` gets before the shutdown gives up on it, unless
-	 * `cleanupAllowanceMs` is longer. Defaults to `drainTimeoutMs`, so the
-	 * worst-case shutdown is the two budgets in sequence — size both against
-	 * the orchestrator's grace period, not one.
-	 */
-	readonly cleanupTimeoutMs?: number;
-	/**
-	 * The least `cleanup` gets, read when the signal arrives: normally
-	 * `() => handle.cleanupAllowanceMs`, the longest tail a module registered
-	 * its cleanup with. Absent, unreadable, or not a whole number of
-	 * milliseconds from 1 to 2147483647, the budget is `cleanupTimeoutMs` alone.
-	 */
-	readonly cleanupAllowanceMs?: () => number | undefined;
-	/** Injected in tests; defaults to {@link deferExit}. */
-	readonly exit?: (code: number) => void;
-	/** Injected in tests; defaults to `process.on`. */
-	readonly onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
-	/** Injected in tests; defaults to `process.removeListener`. */
-	readonly offSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
-}
-
-/**
- * Exit after yielding the loop once.
- *
- * The scaffolded app logs NDJSON through pino, whose default destination is not
- * synchronous, so calling `process.exit` in the same tick as the last
- * `logger.error` can drop exactly the lines that say why the shutdown failed.
- * One turn is a flush window, not a guarantee: a deployment that needs
- * certainty should pass an `exit` that flushes its own transport first.
- */
-export function deferExit(code: number, exitProcess: (code: number) => void = process.exit): void {
-	setImmediate(() => exitProcess(code));
-}
-
-const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
-const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
-
-/** The longest delay a timer takes; a larger one, or NaN, fires after about a millisecond. */
-const MAX_TIMER_MS = 2_147_483_647;
-
-/** What `read` reports, when it is a delay a timer can wait; otherwise nothing. */
-function allowanceFrom(read: (() => number | undefined) | undefined): number | undefined {
-	let allowance: unknown;
-	try {
-		allowance = read?.();
-	} catch {
-		return undefined;
-	}
-	return typeof allowance === "number" &&
-		Number.isInteger(allowance) &&
-		allowance >= 1 &&
-		allowance <= MAX_TIMER_MS
-		? allowance
-		: undefined;
-}
-
-/**
- * Install the graceful shutdown on `server`. The guarantees (a deadline on the
- * drain, a non-zero exit past it, a bounded `cleanup` that never wedges the
- * process), the log line of each stage and how to size `drainTimeoutMs` plus
- * `cleanupTimeoutMs` below the orchestrator's kill grace period are in the
- * template README, "Shutdown guarantees". Beyond them: a `close` that fails is
- * not reported as a clean drain, and exits non-zero.
- */
-export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
-	const {
-		logger,
-		cleanup,
-		drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
-		exit = deferExit,
-		onSignal = (signal, handler): void => {
-			process.on(signal, handler);
-		},
-		offSignal = (signal, handler): void => {
-			process.removeListener(signal, handler);
-		},
-	} = options;
-
-	// Settled when the signal arrives, with the allowance as it stands then.
-	let cleanupTimeoutMs = options.cleanupTimeoutMs ?? drainTimeoutMs;
-
-	let shuttingDown = false;
-	let finished = false;
-
-	/** Sentinel so a timed-out cleanup is reported as that, not as a throw. */
-	const CLEANUP_TIMED_OUT = Symbol("cleanup-timed-out");
-
-	/**
-	 * Await `cleanup`, but not forever. `cleanup()` is invoked inside the async
-	 * wrapper so a synchronous throw lands in the same rejection path as an
-	 * async one.
-	 */
-	const runCleanup = async (): Promise<typeof CLEANUP_TIMED_OUT | undefined> => {
-		if (!cleanup) return;
-		let timer: ReturnType<typeof setTimeout> | undefined;
-		try {
-			return await Promise.race([
-				(async (): Promise<undefined> => {
-					await cleanup();
-					return undefined;
-				})(),
-				new Promise<typeof CLEANUP_TIMED_OUT>((resolve) => {
-					timer = setTimeout(() => resolve(CLEANUP_TIMED_OUT), cleanupTimeoutMs);
-					timer.unref?.();
-				}),
-			]);
-		} finally {
-			if (timer) clearTimeout(timer);
-		}
-	};
-
-	/** Run `cleanup` and exit. Called by whichever of drain / deadline wins. */
-	const finish = async (code: number, reason: string): Promise<void> => {
-		if (finished) return;
-		finished = true;
-		let exitCode = code;
-		// `reason` names whatever decided the exit code, so the line an operator
-		// alerts on cannot say "drained" next to a non-zero code. The drain
-		// outcome keeps its own key rather than being overwritten — both facts
-		// are wanted, and a stable shape is what makes the line queryable.
-		let outcome = reason;
-		try {
-			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
-				logger.error({ cleanupTimeoutMs }, "shutdown_cleanup_timed_out");
-				exitCode = 1;
-				outcome = "cleanup-timeout";
-			}
-		} catch (err) {
-			// 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. 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 }, "shutdown_complete");
-		exit(exitCode);
-	};
-
-	const handler = (): void => {
-		if (shuttingDown) return;
-		shuttingDown = true;
-		for (const signal of SIGNALS) offSignal(signal, handler);
-		cleanupTimeoutMs = Math.max(cleanupTimeoutMs, allowanceFrom(options.cleanupAllowanceMs) ?? 0);
-		logger.info({ drainTimeoutMs, cleanupTimeoutMs }, "shutdown_draining");
-
-		const deadline = setTimeout(() => {
-			logger.error({ drainTimeoutMs }, "shutdown_drain_deadline_exceeded");
-			server.closeAllConnections();
-			void finish(1, "drain-timeout");
-		}, drainTimeoutMs);
-		// The deadline must not be what keeps the process alive once the drain
-		// has already finished.
-		deadline.unref?.();
-
-		server.close((err) => {
-			clearTimeout(deadline);
-			if (err) {
-				// `close` reports through its callback — "Server is not running"
-				// is the common one, but any listener teardown failure lands
-				// 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: loggableError(err) }, "shutdown_server_close_failed");
-				void finish(1, "close-failed");
-				return;
-			}
-			void finish(0, "drained");
-		});
-		// Idle keep-alive sockets have no request behind them, so nothing is
-		// lost by releasing them — and without this a quiet server waits out
-		// the whole deadline for connections that will never send anything.
-		server.closeIdleConnections();
-	};
-
-	for (const signal of SIGNALS) onSignal(signal, handler);
-}

package/templates/standalone/tests/Makefile

@@ -1,5 +0,0 @@
-install:
-	npm install
-
-test:
-	npm test

package/templates/standalone/tests/index.test.js

@@ -1,283 +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 axios from "axios";
-import jwt from "jsonwebtoken";
-import { describe, expect, it } from "vitest";
-
-const BASE_URL = process.env.API_BASE_URL || "http://localhost:3000";
-const JWT_SECRET = process.env.OAUTH_JWT_SECRET || "your-token-secret";
-
-const client = axios.create({
-	baseURL: BASE_URL,
-	withCredentials: true,
-	validateStatus: () => true,
-});
-
-const _extractCookies = (res) => (res.headers["set-cookie"] ?? []).join("; ");
-
-/**
- * The server's own origin, as a browser would report it.
- *
- * `POST /session/login` and `POST /session/logout` reject a request
- * that carries neither a same-origin `Origin`/`Referer` nor a valid
- * double-submit CSRF token. A browser sets `Origin` on its own; a scripted
- * client like this one has to say it.
- */
-const SERVER_ORIGIN = new URL(BASE_URL).origin;
-
-/** POST to a state-changing session route the way a same-origin browser would. */
-const sessionPost = (path, data, config = {}) =>
-	client.post(path, data, {
-		...config,
-		headers: { Origin: SERVER_ORIGIN, ...(config.headers ?? {}) },
-	});
-
-describe("POST /oauth/introspect", () => {
-	// Helper: self-introspect sends the token as both Bearer credential and body parameter
-	const selfIntrospect = (token, contentType = "application/json") => {
-		const headers = {
-			Authorization: `Bearer ${token}`,
-			"Content-Type": contentType,
-		};
-		const data =
-			contentType === "application/x-www-form-urlencoded"
-				? `token=${encodeURIComponent(token)}`
-				: { token };
-		return client.post("/oauth/introspect", data, { headers });
-	};
-
-	it("returns 401 when no authentication is provided", async () => {
-		const res = await client.post("/oauth/introspect", {});
-		expect(res.status).toBe(401);
-	});
-
-	describe("self-introspect (JSON)", () => {
-		it("returns active: true for a valid JWT", async () => {
-			const token = jwt.sign({ user: { id: 1 }, scopes: ["read"] }, JWT_SECRET, {
-				expiresIn: 60,
-			});
-			const res = await selfIntrospect(token);
-			expect(res.status).toBe(200);
-			expect(res.data.active).toBe(true);
-		});
-
-		it("returns scope as space-separated string per RFC 7662", async () => {
-			const token = jwt.sign({ user: { id: 1 }, scopes: ["read", "write"] }, JWT_SECRET, {
-				expiresIn: 60,
-			});
-			const res = await selfIntrospect(token);
-			expect(res.status).toBe(200);
-			expect(res.data.scope).toBe("read write");
-			expect(res.data.scopes).toBeUndefined();
-		});
-
-		it("returns 401 for an invalid JWT", async () => {
-			const res = await selfIntrospect("invalid.token.here");
-			expect(res.status).toBe(401);
-			expect(res.data.active).toBe(false);
-		});
-
-		it("returns 401 for an expired JWT", async () => {
-			const token = jwt.sign({ user: { id: 1 } }, JWT_SECRET, { expiresIn: -1 });
-			const res = await selfIntrospect(token);
-			expect(res.status).toBe(401);
-			expect(res.data.active).toBe(false);
-		});
-	});
-
-	describe("self-introspect (application/x-www-form-urlencoded)", () => {
-		it("returns active: true for a valid JWT", async () => {
-			const token = jwt.sign({ user: { id: 1 }, scopes: ["read"] }, JWT_SECRET, {
-				expiresIn: 60,
-			});
-			const res = await selfIntrospect(token, "application/x-www-form-urlencoded");
-			expect(res.status).toBe(200);
-			expect(res.data.active).toBe(true);
-		});
-
-		it("returns 401 for an invalid JWT", async () => {
-			const res = await selfIntrospect("invalid.token.here", "application/x-www-form-urlencoded");
-			expect(res.status).toBe(401);
-			expect(res.data.active).toBe(false);
-		});
-
-		it("returns 401 for an expired JWT", async () => {
-			const token = jwt.sign({ user: { id: 1 } }, JWT_SECRET, { expiresIn: -1 });
-			const res = await selfIntrospect(token, "application/x-www-form-urlencoded");
-			expect(res.status).toBe(401);
-			expect(res.data.active).toBe(false);
-		});
-	});
-});
-
-describe("POST /session/login", () => {
-	it("returns 400 when no credentials are provided", async () => {
-		const res = await sessionPost("/session/login", {});
-		expect(res.status).toBe(400);
-	});
-
-	it("returns 400 when redirect_to has an invalid scheme", async () => {
-		const res = await sessionPost("/session/login", {
-			username: "testuser",
-			password: "testpass",
-			redirect_to: "javascript:alert(1)",
-		});
-		expect(res.status).toBe(400);
-		expect(res.data.error).toBe("invalid_redirect");
-	});
-
-	it("returns 400 when redirect_to is not a valid URL", async () => {
-		const res = await sessionPost("/session/login", {
-			username: "testuser",
-			password: "testpass",
-			redirect_to: "not-a-url",
-		});
-		expect(res.status).toBe(400);
-		expect(res.data.error).toBe("invalid_redirect");
-	});
-
-	it("returns 400 when redirect_to exceeds 2048 characters", async () => {
-		const res = await sessionPost("/session/login", {
-			username: "testuser",
-			password: "testpass",
-			redirect_to: `https://example.com/${"a".repeat(2048)}`,
-		});
-		expect(res.status).toBe(400);
-		expect(res.data.error).toBe("invalid_redirect");
-	});
-
-	it("accepts a valid redirect_to without error", async () => {
-		// redirect_to validation runs before authentication, so even with
-		// invalid credentials, a valid redirect_to should not cause a 400
-		// with error: "invalid_redirect". It should fail with 401 (auth failure).
-		const res = await sessionPost("/session/login", {
-			username: "testuser",
-			password: "testpass",
-			redirect_to: "http://localhost:3000/oauth/authorize",
-		});
-		expect(res.status).not.toBe(400);
-		expect(res.data.error).not.toBe("invalid_redirect");
-	});
-});
-
-describe("CSRF on the state-changing session routes", () => {
-	it("rejects a login carrying neither an origin signal nor a token", async () => {
-		// The bypass this replaced: omitting `Origin` skipped the check entirely.
-		const res = await client.post("/session/login", {
-			username: "testuser",
-			password: "testpass",
-		});
-		expect(res.status).toBe(403);
-		expect(res.data.error).toBe("access_denied");
-	});
-
-	it("rejects a logout carrying neither an origin signal nor a token", async () => {
-		const res = await client.post("/session/logout", {});
-		expect(res.status).toBe(403);
-		expect(res.data.error).toBe("access_denied");
-	});
-
-	it("rejects a login from a foreign origin", async () => {
-		const res = await client.post(
-			"/session/login",
-			{ username: "testuser", password: "testpass" },
-			{ headers: { Origin: "https://evil.example.com" } },
-		);
-		expect(res.status).toBe(403);
-	});
-
-	it("accepts a header-less client that presents a token from GET /session/csrf", async () => {
-		const issued = await client.get("/session/csrf");
-		expect(issued.status).toBe(200);
-		expect(typeof issued.data.csrf_token).toBe("string");
-
-		const res = await client.post(
-			"/session/login",
-			{ username: "testuser", password: "testpass" },
-			{
-				headers: {
-					Cookie: _extractCookies(issued).split(";")[0],
-					[issued.data.header_name]: issued.data.csrf_token,
-				},
-			},
-		);
-		// Credentials are still wrong in this environment — the point is that the
-		// request got past the CSRF guard rather than stopping at 403.
-		expect(res.status).not.toBe(403);
-	});
-});
-
-describe("POST /oauth/token", () => {
-	it("returns 401 for grant_type=session without an authenticated session", async () => {
-		const res = await client.post("/oauth/token", "grant_type=session", {
-			headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		});
-		expect(res.status).toBe(401);
-	});
-
-	it("returns 400 for an unsupported grant_type", async () => {
-		const res = await client.post("/oauth/token", "grant_type=unknown", {
-			headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		});
-		expect(res.status).toBe(400);
-	});
-
-	it("returns 400 for grant_type=authorization_code without a code", async () => {
-		const res = await client.post("/oauth/token", "grant_type=authorization_code", {
-			headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		});
-		expect(res.status).toBe(400);
-	});
-});
-
-describe("GET /oauth/authorize", () => {
-	it("redirects to login with redirect_to when the session is not authenticated", async () => {
-		const res = await client.get(
-			"/oauth/authorize?response_type=code&client_id=test&redirect_uri=http://localhost:9999/callback",
-			{ maxRedirects: 0 },
-		);
-		expect(res.status).toBe(302);
-		const location = res.headers.location;
-		expect(location).toContain("login");
-		expect(location).toContain("redirect_to=");
-		expect(location).not.toContain("redirect_uri=");
-		// Verify the authorize URL is properly encoded (? and & should be escaped)
-		expect(location).toContain(encodeURIComponent("response_type=code"));
-	});
-});
-
-describe("GET /session/oauth/federation/google", () => {
-	// NOTE: Development config has Google federation disabled (google.enabled: false).
-	// No federation is registered under that name, so the route answers 404 before
-	// redirect_to is validated, and redirect_to validation tests cannot run in this
-	// environment. Validation logic is identical to POST /session/login and covered
-	// by those tests.
-
-	it("returns 404 when Google federation is disabled", async () => {
-		const res = await client.get(
-			"/session/oauth/federation/google?redirect_to=https://localhost:3001",
-		);
-		expect(res.status).toBe(404);
-	});
-
-	it("returns 404 even with invalid redirect_to when Google is disabled", async () => {
-		const res = await client.get(
-			"/session/oauth/federation/google?redirect_to=javascript:alert(1)",
-		);
-		expect(res.status).toBe(404);
-	});
-});