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

package/templates/standalone/tests/package.json

@@ -7,10 +7,10 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"axios": "^1.6.0",
+		"axios": "^1.18.0",
 		"jsonwebtoken": "^9.0.3"
 	},
 	"devDependencies": {
-		"vitest": "^1.0.0"
+		"vitest": "^5.0.2"
 	}
 }

package/templates/standalone/tests/vitest.config.mjs

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+// This directory is its own npm project, run against a live provider. Its own
+// config fixes what this project collects; no config of the template's around
+// it decides that, whichever vitest the lockfile carries.
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		include: ["*.test.js"],
+	},
+});

package/templates/standalone/vitest.config.mts

@@ -3,7 +3,7 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
 	test: {
 		include: ["src/**/__tests__/**/*.test.mts"],
-		// #357: the workspace-wide deadline floor, repeated as literals rather
+		// The workspace-wide deadline floor, repeated as literals rather
 		// than imported from vitest.shared.mts — this template is copied
 		// verbatim into scaffolded projects, where that file does not exist.
 		// Rationale lives there: under a loaded parallel run, transform+import
@@ -11,7 +11,7 @@ export default defineConfig({
 		// 20s.
 		testTimeout: 20_000,
 		hookTimeout: 20_000,
-		// #512: run the @o3co/auth-provider-* packages through vitest instead of
+		// Run the @o3co/auth-provider-* packages through vitest instead of
 		// letting Node load them natively. In a scaffolded project they are
 		// installed from npm under node_modules, which vitest externalizes by
 		// default — and an externalized package's own `import "ioredis"` /
@@ -20,11 +20,12 @@ export default defineConfig({
 		// monorepo the same packages are symlinks to source and are inlined
 		// anyway; this makes the two layouts behave the same.
 		server: { deps: { inline: [/@o3co\/auth-provider-/] } },
-		// #556: the server `request(app)` starts listens on 127.0.0.1, the
-		// address supertest dials. Unpatched, macOS can give it a port another
-		// process holds on 127.0.0.1, and the request hangs on that process until
-		// the test timeout. Rationale and mechanics in the file itself. The
-		// Dockerfile `test` stage copies it; scaffold-assets.test.mts checks that.
+		// The supertest loopback guard: the server `request(app)` starts
+		// listens on 127.0.0.1, the address supertest dials. Unpatched, macOS
+		// can give it a port another process holds on 127.0.0.1, and the
+		// request hangs on that process until the test timeout. Rationale and
+		// mechanics in the file itself. The Dockerfile `test` stage copies it;
+		// scaffold-assets.test.mts checks that.
 		setupFiles: ["./vitest.supertest-loopback.mts"],
 	},
 });

package/templates/standalone/vitest.supertest-loopback.mts

@@ -15,50 +15,47 @@
  */
 
 /**
- * vitest setup file (#556): the server supertest starts listens on the
- * address supertest dials.
+ * vitest setup file: the server supertest starts listens on the address
+ * supertest dials.
  *
  * `request(app)` / `request.agent(app)` start a server with `app.listen(0)`
  * and send the request to `127.0.0.1:<port>`. A hostless `listen` binds the
- * dual-stack wildcard `[::]:P`, and on macOS (BSD `SO_REUSEADDR` semantics —
+ * dual-stack wildcard `[::]:P`, and on macOS (BSD `SO_REUSEADDR` semantics;
  * libuv sets it on every TCP listener) the kernel will choose a `P` that
  * another process already holds as `127.0.0.1:P`. The more specific socket
- * wins, so the test's request is delivered to that process. When it accepts
- * and never answers — an editor helper, in the case that was caught — the
- * request hangs until the test timeout, in whichever supertest test drew the
- * port, and passes on the next run. Linux refuses the conflicting bind
- * (EADDRINUSE), so CI does not show it.
+ * wins, so the request goes to that process; if it accepts and never answers,
+ * the test hangs until its timeout and passes on the next run. Linux refuses
+ * the conflicting bind (EADDRINUSE), so CI does not show it.
  *
  * Binding `127.0.0.1` explicitly removes both halves: the kernel will not
  * give out a `127.0.0.1:P` someone else holds, and against a wildcard holder
  * our specific socket is the one that receives. A specific-host `listen` is
- * asynchronous (it goes through `dns.lookup`), and supertest reads the port
+ * asynchronous (it goes through `dns.lookup`) and supertest reads the port
  * synchronously in its constructor, so the URL is completed when the request
  * is sent (`end`, which `then` and `expect(..., fn)` go through). A server the
  * test started itself is never touched.
  *
- * Which version of supertest closes the server it started, and when, has
- * changed under this file once (7.3.0): 7.2 closed `_server` before asserting;
- * 7.3 tracks the servers it started itself in a private registry and closes
- * only those, so a server this file bound is left listening. The patched
- * `end` therefore closes the server this request started, before the test's
- * callback, whenever supertest has not — the same order either way.
+ * supertest does not close a server bound here (7.3 counts requests only on
+ * servers in its own registry; 7.2 closed after the response of the request
+ * that bound it, resetting an agent's other requests on the shared server).
+ * So this file counts every request on such a server from `end`, and the last
+ * to settle closes the server before its own callback, the order supertest
+ * keeps. A request built before that close and sent after it binds the server
+ * again.
  *
  * supertest is loaded from the package that owns the running test file (the
  * nearest `package.json` above it), so the patched class is the one that test
- * imports, whatever directory vitest was started from. A package that does
- * not declare supertest is left alone. Everything else this file cannot do —
- * no test path, a declared supertest that does not load, a supertest whose
- * internals no longer look like this — throws, so the guard is never silently
- * off. That load-time check sees only the two methods' presence; a supertest
- * that moved the `listen` out of `serverAddress` would pass it and leave the
- * guard off. The behavioural tests catch that shape of change: this
- * template's `supertest-loopback.test.mts` and its twin in the session
- * package assert the address the server actually bound.
+ * imports. A package that does not declare supertest is left alone. Anything
+ * else this file cannot do (no test path, a declared supertest that does not
+ * load, internals that no longer look like this) throws, so the guard is
+ * never silently off. That load-time check sees only the two methods'
+ * presence; a supertest that moved the `listen` out of `serverAddress` would
+ * pass it, which `supertest-loopback.test.mts` here and its twin in the
+ * session package catch by asserting the address the server actually bound.
  *
- * This file is part of the project template and ships with every scaffold.
- * The auth.provider workspace loads this same file for its packages (see
- * `WORKSPACE_TEST_SETUP` in its `vitest.shared.mts`).
+ * Part of the project template, shipped with every scaffold; the
+ * auth.provider workspace loads it for its packages too
+ * (`WORKSPACE_TEST_SETUP` in its `vitest.shared.mts`).
  */
 
 import { once } from "node:events";
@@ -73,17 +70,28 @@ const LOOPBACK = "127.0.0.1";
 const PATCHED = Symbol.for("o3co.auth.provider.supertest-loopback");
 const PENDING = Symbol("o3co.auth.provider.supertest-loopback.pending");
 
+/**
+ * A server this file bound, from its `listen` until the last request on it
+ * settles. It is the server's current bind for as long as `bound` maps the
+ * server to it; a request built on one that no longer is — closed by its last
+ * request, or failed — binds again when it is sent.
+ */
+type Bound = {
+	/** Settles on `listening`, rejects on a listen `error`. */
+	readonly ready: Promise<unknown>;
+	/** The requests sent over it that have not settled. */
+	pending: number;
+};
+
 type Pending = {
 	readonly server: Server;
 	readonly protocol: string;
 	readonly path: string;
-	/** Settles on `listening`, rejects on a listen `error`. */
-	readonly ready: Promise<unknown>;
+	readonly bound: Bound;
 };
 
 type TestInstance = {
 	url: string;
-	_server?: Server;
 	[PENDING]?: Pending;
 };
 
@@ -126,7 +134,7 @@ function supertestFor(testPath: string): TestPrototype | undefined {
 		supertest = createRequire(manifestPath)("supertest");
 	} catch (cause) {
 		throw new Error(
-			`vitest.supertest-loopback.mts: ${manifestPath} declares supertest, but it cannot be loaded from there; the #556 loopback guard would be off.`,
+			`vitest.supertest-loopback.mts: ${manifestPath} declares supertest, but it cannot be loaded from there; the supertest loopback guard would be off.`,
 			{ cause },
 		);
 	}
@@ -134,19 +142,46 @@ function supertestFor(testPath: string): TestPrototype | undefined {
 	if (typeof proto?.serverAddress !== "function" || typeof proto.end !== "function") {
 		throw new Error(
 			"vitest.supertest-loopback.mts: supertest no longer exposes Test.prototype.serverAddress/end; " +
-				"re-check the #556 loopback guard against the installed supertest before removing it.",
+				"re-check the supertest loopback guard against the installed supertest before removing it.",
 		);
 	}
 	return proto;
 }
 
 /**
- * The bind in progress per server. A second request on a server whose bind has
- * not finished (an agent's requests sent together share one server) waits on
- * the same bind instead of calling `listen` twice — and, like unpatched
- * supertest when it finds a server already listening, does not own it.
+ * The servers this file bound, each until the last request on it closes it.
+ * A request on a server whose bind has not finished (an agent's requests sent
+ * together share one server) waits on that bind instead of calling `listen`
+ * twice, and one sent while the server is serving others joins their count.
  */
-const binding = new WeakMap<Server, Promise<unknown>>();
+const bound = new WeakMap<Server, Bound>();
+
+/** The server's bind in progress or in service, or a new one. */
+function share(server: Server): Bound {
+	const current = bound.get(server);
+	if (current) return current;
+	server.listen(0, LOOPBACK);
+	// Subscribed now, not in `end`: a listen error emitted before the test
+	// sends the request must still reach it, not crash the worker as an
+	// unhandled 'error' event.
+	const fresh: Bound = { ready: once(server, "listening"), pending: 0 };
+	bound.set(server, fresh);
+	// Once it has failed, the bind is left to the requests already waiting on
+	// it, each of which fails with its error, and is no longer the server's:
+	// the next request sent binds again, one built on the failed bind included.
+	// Forgotten on the error event itself, and not on the rejection it becomes
+	// — that settles a few microtasks later, and a request built in between
+	// would join the failed bind.
+	const failed = (): void => {
+		if (bound.get(server) === fresh) bound.delete(server);
+	};
+	server.once("error", failed);
+	fresh.ready.then(
+		() => server.removeListener("error", failed),
+		() => {},
+	);
+	return fresh;
+}
 
 /**
  * A throw from the test's own callback, raised where it cannot propagate to
@@ -165,27 +200,14 @@ function patch(proto: TestPrototype): void {
 	const originalEnd = proto.end;
 
 	proto.serverAddress = function serverAddress(app, path) {
-		// Already listening: the test owns the server and chose its address.
-		if (app.address()) return originalServerAddress.call(this, app, path);
+		// Listening, and not bound here: the test owns the server and chose its
+		// address.
+		if (!bound.has(app) && app.address()) return originalServerAddress.call(this, app, path);
 
+		// supertest is never told about this bind — neither 7.2's `_server` nor
+		// 7.3's registry — so neither closes the server; the patched `end` does.
 		const protocol = app instanceof TlsServer ? "https" : "http";
-		let ready = binding.get(app);
-		if (!ready) {
-			// supertest 7.2 closes `_server` after the response; 7.3 does not,
-			// and the callback in the patched `end` below closes it instead.
-			this._server = app.listen(0, LOOPBACK);
-			// Subscribed now, not in `end`: a listen error emitted before the test
-			// sends the request must still reach it, not crash the worker as an
-			// unhandled 'error' event.
-			const bound = once(app, "listening");
-			binding.set(app, bound);
-			bound.then(
-				() => binding.delete(app),
-				() => binding.delete(app),
-			);
-			ready = bound;
-		}
-		this[PENDING] = { server: app, protocol, path, ready };
+		this[PENDING] = { server: app, protocol, path, bound: share(app) };
 		// No port yet; `end` fills it in before anything is sent.
 		return `${protocol}://${LOOPBACK}${path}`;
 	};
@@ -195,17 +217,24 @@ function patch(proto: TestPrototype): void {
 		if (!pending) return originalEnd.call(this, fn);
 		this[PENDING] = undefined;
 
-		const { server, protocol, path, ready } = pending;
+		const { server, protocol, path } = pending;
+		// Built on a bind that is no longer the server's — closed by its last
+		// request, or failed — and sent now: bind it again, or join the bind
+		// another request has made since.
+		const shared = bound.get(server) === pending.bound ? pending.bound : share(server);
+		shared.pending += 1;
 		let called = false;
 		const callback = (err: unknown, res?: unknown) => {
 			called = true;
-			// supertest 7.2 has closed the server it started by now, before the
-			// callback; 7.3 closes only servers in its own private registry, which
-			// this bind is not in. Close what this request started, if it is
-			// still open, before the callback — the order 7.2 kept.
-			if (this._server === server && server.listening) {
-				server.close(() => fn?.(err, res));
-				return;
+			// The last request on the server closes it, before its own callback —
+			// the order supertest keeps. A bind that failed has nothing to close.
+			shared.pending -= 1;
+			if (shared.pending === 0 && bound.get(server) === shared) {
+				bound.delete(server);
+				if (server.listening) {
+					server.close(() => fn?.(err, res));
+					return;
+				}
 			}
 			fn?.(err, res);
 		};
@@ -218,16 +247,15 @@ function patch(proto: TestPrototype): void {
 		// this chain is one nobody awaits.
 		const fail = (err: unknown) => {
 			if (called) return rethrowOutsideThisChain(err);
-			// The request never went out, so supertest will not close the server
-			// this request started.
-			if (this._server?.listening) this._server.close();
+			// The request never went out; it still leaves the count, and closes
+			// the server if it was the last one on it.
 			try {
 				callback(err);
 			} catch (thrown) {
 				rethrowOutsideThisChain(thrown);
 			}
 		};
-		ready
+		shared.ready
 			.then(() => {
 				const { port } = server.address() as { port: number };
 				this.url = `${protocol}://${LOOPBACK}:${port}${path}`;
@@ -243,7 +271,7 @@ function patch(proto: TestPrototype): void {
 const { testPath } = expect.getState();
 if (!testPath) {
 	throw new Error(
-		"vitest.supertest-loopback.mts: vitest did not say which test file this setup runs for, so the #556 loopback guard cannot find supertest.",
+		"vitest.supertest-loopback.mts: vitest did not say which test file this setup runs for, so the supertest loopback guard cannot find supertest.",
 	);
 }
 const proto = supertestFor(testPath);

package/templates/versions.json

@@ -1,17 +1,20 @@
 {
-	"@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.17.0-rc.1",
+	"@o3co/auth-provider-device-grant": "0.17.0-rc.1",
+	"@o3co/auth-provider-dpop": "0.17.0-rc.1",
+	"@o3co/auth-provider-mtls": "0.17.0-rc.1",
+	"@o3co/auth-provider-federation-apple": "0.17.0-rc.1",
+	"@o3co/auth-provider-federation-google": "0.17.0-rc.1",
+	"@o3co/auth-provider-federation-github": "0.17.0-rc.1",
+	"@o3co/auth-provider-federation-grants": "0.17.0-rc.1",
+	"@o3co/auth-provider-federation-oidc": "0.17.0-rc.1",
+	"@o3co/auth-provider-oauth": "0.17.0-rc.1",
+	"@o3co/auth-provider-oauth-token-exchange": "0.17.0-rc.1",
+	"@o3co/auth-provider-session": "0.17.0-rc.1",
+	"@o3co/auth-provider-foundation": "0.17.0-rc.1",
+	"@o3co/auth-provider-mfa": "0.17.0-rc.1",
+	"@o3co/auth-provider-redis": "0.17.0-rc.1",
+	"@o3co/auth-provider-standard": "0.17.0-rc.1",
+	"@o3co/auth-provider-test-kit": "0.17.0-rc.1",
+	"@o3co/auth-provider-webauthn": "0.17.0-rc.1"
 }

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"));
-	};
-};