@o3co/create-auth-provider 0.9.0 → 0.10.0

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

@@ -0,0 +1,231 @@
+/*
+ * 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 { request as httpRequest } from "node:http";
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { createMetrics } from "../metrics.mjs";
+
+function buildApp(probes: Parameters<ReturnType<typeof createMetrics>["route"]>[1]["probes"] = []) {
+	const metrics = createMetrics();
+	const app = express();
+	app.use(metrics.middleware);
+	app.use(metrics.route(express, { probes, probeTimeoutMs: 100 }));
+
+	const api = express.Router();
+	api.get("/widgets/:id", (_req, res) => {
+		res.status(200).json({ ok: true });
+	});
+	api.get("/boom", (_req, res) => {
+		res.status(500).json({ ok: false });
+	});
+	app.use("/api", api);
+	return app;
+}
+
+describe("GET /metrics", () => {
+	it("serves the Prometheus text exposition format", async () => {
+		const res = await request(buildApp()).get("/metrics");
+
+		expect(res.status).toBe(200);
+		expect(res.headers["content-type"]).toContain("text/plain");
+		// Node process defaults are namespaced so they cannot collide with
+		// anything else scraped from the same job.
+		expect(res.text).toContain("auth_provider_process_cpu_user_seconds_total");
+	});
+
+	it("records latency by method, route and status", async () => {
+		const app = buildApp();
+		await request(app).get("/api/widgets/42");
+		await request(app).get("/api/boom");
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('route="/api/widgets/:id"');
+		expect(res.text).toContain('status="200"');
+		expect(res.text).toContain('status="500"');
+	});
+
+	it("labels by the route pattern, not the URL, so the label set stays bounded", async () => {
+		// Labelling by path would mint a series per id and eventually take down
+		// the system that is supposed to be watching this one.
+		const app = buildApp();
+		for (const id of ["1", "2", "3"]) {
+			await request(app).get(`/api/widgets/${id}`);
+		}
+
+		const res = await request(app).get("/metrics");
+		const series = res.text
+			.split("\n")
+			.filter((l) => l.startsWith("http_request_duration_seconds_count"));
+
+		expect(series.some((l) => l.includes('route="/api/widgets/:id"'))).toBe(true);
+		expect(res.text).not.toContain('route="/api/widgets/1"');
+	});
+
+	it("collapses unmatched requests into a single bucket", async () => {
+		// 404 probes from the internet carry attacker-chosen paths.
+		const app = buildApp();
+		await request(app).get(`/nope/${"x".repeat(50)}`);
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('route="unmatched"');
+		expect(res.text).not.toContain("xxxxx");
+	});
+
+	it("collapses unknown HTTP methods into one label", async () => {
+		// req.method is attacker-controlled — Node's HTTP parser accepts any
+		// valid token, so `FOO` and `M000001` arrive as readily as `GET`. An
+		// unbounded method label is the same cardinality bomb as an unbounded
+		// route label, reachable without any access to /metrics. Sent over a real
+		// socket because supertest cannot express a non-standard method.
+		const app = buildApp();
+		const server = app.listen(0);
+		const port = (server.address() as { port: number }).port;
+		try {
+			for (const method of ["FOO", "M000001", "PURGE"]) {
+				await new Promise<void>((resolve) => {
+					const req = httpRequest(
+						{ host: "127.0.0.1", port, path: "/api/widgets/1", method },
+						(res) => {
+							res.resume();
+							res.once("end", resolve);
+						},
+					);
+					req.once("error", () => resolve());
+					req.end();
+				});
+			}
+
+			const res = await request(app).get("/metrics");
+
+			expect(res.text).toContain('method="other"');
+			expect(res.text).not.toContain('method="M000001"');
+			expect(res.text).not.toContain('method="FOO"');
+		} finally {
+			server.close();
+		}
+	});
+
+	it("counts a request whose client disconnects before the response finishes", async () => {
+		// `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.
+		const metrics = createMetrics();
+		const app = express();
+		app.use(metrics.middleware);
+		app.use(metrics.route(express, { probes: [], probeTimeoutMs: 100 }));
+		app.get("/slow", (_req, res) => {
+			// Never responds; the test aborts the socket instead.
+			void res;
+		});
+
+		const server = app.listen(0);
+		const port = (server.address() as { port: number }).port;
+		try {
+			const controller = new AbortController();
+			const pending = fetch(`http://127.0.0.1:${port}/slow`, {
+				signal: controller.signal,
+			}).catch(() => undefined);
+			await new Promise((resolve) => setTimeout(resolve, 30));
+			controller.abort();
+			await pending;
+			await new Promise((resolve) => setTimeout(resolve, 30));
+
+			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);
+		} finally {
+			server.close();
+		}
+	});
+
+	it("observes a response exactly once even though both finish and close fire", async () => {
+		const app = buildApp();
+		await request(app).get("/api/widgets/1");
+
+		const res = await request(app).get("/metrics");
+		const line = res.text
+			.split("\n")
+			.find(
+				(l) =>
+					l.startsWith("http_request_duration_seconds_count") &&
+					l.includes('route="/api/widgets/:id"'),
+			);
+		expect(line?.trim().endsWith(" 1")).toBe(true);
+	});
+
+	it("publishes a per-dependency gauge from the readiness probes", async () => {
+		const app = buildApp([
+			{ name: "redis", check: async () => "PONG" },
+			{
+				name: "session-store",
+				check: async () => {
+					throw new Error("ECONNREFUSED");
+				},
+			},
+		]);
+
+		const res = await request(app).get("/metrics");
+
+		expect(res.text).toContain('auth_dependency_up{dependency="redis"} 1');
+		expect(res.text).toContain('auth_dependency_up{dependency="session-store"} 0');
+	});
+
+	it("re-samples dependencies on every scrape instead of caching a verdict", async () => {
+		let healthy = true;
+		const app = buildApp([
+			{
+				name: "redis",
+				check: async () => {
+					if (!healthy) throw new Error("down");
+					return "PONG";
+				},
+			},
+		]);
+
+		expect((await request(app).get("/metrics")).text).toContain(
+			'auth_dependency_up{dependency="redis"} 1',
+		);
+		healthy = false;
+		expect((await request(app).get("/metrics")).text).toContain(
+			'auth_dependency_up{dependency="redis"} 0',
+		);
+	});
+
+	it("joins an in-flight probe rather than issuing one per scrape", async () => {
+		// A partitioned backend never answers, and a scrape loop would otherwise
+		// stack one command per scrape against the dependency already in trouble.
+		const check = vi.fn(() => new Promise(() => {}));
+		const app = buildApp([{ name: "redis", check }]);
+
+		await request(app).get("/metrics");
+		await request(app).get("/metrics");
+
+		expect(check).toHaveBeenCalledTimes(1);
+	});
+
+	it("is never cached", async () => {
+		const res = await request(buildApp()).get("/metrics");
+
+		expect(res.headers["cache-control"]).toBe("no-store");
+	});
+});

package/templates/standalone/src/__tests__/refresh-token-family-client-module.test.mts

@@ -31,6 +31,7 @@ vi.mock("ioredis", () => {
 		}
 		on = vi.fn();
 		quit = vi.fn(async () => "OK" as const);
+		ping = vi.fn(async () => "PONG" as const);
 		// Minimal command surface — `makeIoredisClients` only invokes these
 		// during construction in some paths; tests never exercise the wrapped
 		// client itself, so most stubs are unused.
@@ -168,7 +169,50 @@ describe("D-2 / standaloneRedisClientsModule", () => {
 		expect(onSpies[0]).toHaveBeenCalledWith("error", expect.any(Function));
 	});
 
-	it("declares 'config' as required and 'lifecycleRegistrar' as optional", async () => {
+	it("bounds every command and every connect attempt (#286)", async () => {
+		// Without these the driver's defaults apply: no command timeout at all,
+		// a 10s connect timeout, and 20 reconnect attempts before a queued
+		// command is failed. A partition therefore parks in-flight `/token`
+		// requests indefinitely instead of erroring, which is what stops the
+		// fail-closed rate-limit policy from ever shedding load.
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		const options = redisCtorCalls[0]?.options;
+		expect(options?.commandTimeout).toBe(1_000);
+		expect(options?.connectTimeout).toBe(5_000);
+		expect(options?.maxRetriesPerRequest).toBe(3);
+		// `lazyConnect: false` is the driver default, but it is declared in
+		// SHARED_REDIS_TIMEOUTS as a load-bearing decision (connect at boot,
+		// not at first command) — pin it so a future flip has to come here.
+		expect(options?.lazyConnect).toBe(false);
+	});
+
+	it("keeps the offline queue ON, explicitly, because one socket serves every purpose (#286)", async () => {
+		// `enableOfflineQueue` is a per-CONNECTION option and every adapter in
+		// this template draws from the single socket built below, so the
+		// "off for the rate limiter, on elsewhere" split is not expressible
+		// here. Asserting the explicit `true` rather than accepting the
+		// driver default is the point: the value is a decision (see the
+		// comment in `getOrCreateClients`), and a future change that wants
+		// `false` has to come through this test.
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		expect(redisCtorCalls[0]?.options?.enableOfflineQueue).toBe(true);
+	});
+
+	it("declares 'config' as required and both registrars as optional", async () => {
 		const { standaloneRedisClientsModule } = await importModule();
 		const m = standaloneRedisClientsModule as {
 			requires?: readonly string[];
@@ -176,5 +220,36 @@ describe("D-2 / standaloneRedisClientsModule", () => {
 		};
 		expect(m.requires).toContain("config");
 		expect(m.optional).toContain("lifecycleRegistrar");
+		expect(m.optional).toContain("readinessRegistrar");
+	});
+
+	it("registers one readiness probe for the shared connection, not one per slot", async () => {
+		// Every Redis-backed adapter draws from a single socket, so a probe per
+		// consumed slot would report the same connection six times.
+		const probes: Array<{ name: string; check: () => Promise<unknown> }> = [];
+		const readinessRegistrar = { register: (p: (typeof probes)[number]) => probes.push(p) };
+
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		const lifecycleRegistrar: LifecycleRegistrar = { register: () => {} };
+
+		await provides.refreshTokenFamilyClient({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+			readinessRegistrar,
+		});
+		await provides.rateLimiterClient({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+			readinessRegistrar,
+		});
+
+		expect(redisCtorCalls).toHaveLength(1);
+		expect(probes.map((p) => p.name)).toEqual(["redis"]);
+		await expect(probes[0]?.check()).resolves.toBe("PONG");
 	});
 });

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

@@ -14,11 +14,14 @@
  * limitations under the License.
  */
 
+import { generateKeyPairSync } from "node:crypto";
 import { readFileSync } from "node:fs";
 import {
 	type AppConfig,
 	createApp,
+	createHealthcheckRouter,
 	createKeyStoreFactory,
+	createReadinessRouter,
 	defineModule,
 	generateToken,
 	InMemoryClientRepository,
@@ -33,17 +36,28 @@ import { buildModules } from "../buildModules.mjs";
 
 const dockerfile = readFileSync(new URL("../../Dockerfile", import.meta.url), "utf8");
 
+// #282: the template's shipped default is EdDSA with a published JWKS, so the
+// smoke test signs the way a real deployment of this scaffold does. Generated
+// per run — no key material is committed.
+const smokeKeyPair = generateKeyPairSync("ed25519", {
+	publicKeyEncoding: { type: "spki", format: "pem" },
+	privateKeyEncoding: { type: "pkcs8", format: "pem" },
+});
+
 const config: AppConfig = {
-	http: { port: 0, trustProxy: false },
+	http: { port: 0, trustProxy: false, readinessTimeoutMs: 1000 },
+	logging: { level: "silent" },
 	oauth: {
 		jwt: {
+			issuer: "https://auth.test",
 			signingKey: {
 				provider: "local",
 				local: {
-					algorithm: "HS256",
-					secret: "test-secret-for-smoke-test",
+					algorithm: "EdDSA",
 					kid: "v0",
-					previousSecrets: [],
+					privateKey: smokeKeyPair.privateKey,
+					publicKey: smokeKeyPair.publicKey,
+					previousKeys: [],
 				},
 			},
 		},
@@ -55,6 +69,8 @@ const config: AppConfig = {
 		},
 		grants: {},
 		oidcMode: "oidc-required",
+		// #330: no `authorize` section — the `allowUnmarkedClients` migration
+		// flag was removed; the first-party invariant is unconditional.
 		// OR-9: explicit memory adapter for the smoke test. The legacy
 		// `repositories.code.type` fallback would also pick memory here,
 		// but the explicit setting documents the intent and avoids
@@ -62,7 +78,8 @@ const config: AppConfig = {
 		code: { adapter: "memory" as const },
 	},
 	session: {
-		secret: "test-session-secret",
+		// #282: `session.secret` carries a 256-bit entropy floor.
+		secret: "test-session-secret.at-least-32-bytes.ok",
 		name: "auth.sid",
 		maxAge: 3600000,
 		secure: false,
@@ -173,9 +190,13 @@ describe("standalone smoke test", () => {
 		});
 
 		const app = express();
-		app.get("/_healthcheck", (_req, res) => {
-			res.status(200).json({ status: "ok" });
-		});
+		app.use(createHealthcheckRouter(express));
+		app.use(
+			createReadinessRouter(express, {
+				probes: handle.readinessProbes,
+				timeoutMs: config.http.readinessTimeoutMs,
+			}),
+		);
 		app.use(handle.router);
 		return { app, handle };
 	}
@@ -208,13 +229,36 @@ describe("standalone smoke test", () => {
 		expect(dockerfile).toMatch(
 			/CMD\s+wget\s+-q\s+-O\s+\/dev\/null\s+"http:\/\/localhost:[$]\{HTTP_PORT\}\/_healthcheck"\s+\|\|\s+exit\s+1/,
 		);
-		expect(dockerfile).toMatch(/FROM node-base AS deps[\s\S]*USER node[\s\S]*RUN pnpm install/);
+		expect(dockerfile).toMatch(
+			/FROM node-base AS deps[\s\S]*USER node[\s\S]*RUN pnpm install --frozen-lockfile/,
+		);
 		expect(dockerfile).toMatch(/FROM deps AS builder[\s\S]*USER node[\s\S]*RUN pnpm run build/);
+		// #289: dependencies are resolved exactly once, in `deps`. The runtime
+		// stage must take its node_modules from a prune of that same tree — a
+		// second `pnpm install` would be a second resolution, so its absence
+		// after the runtime FROM is part of the contract.
+		expect(dockerfile).toMatch(
+			/FROM deps AS prod-deps[\s\S]*USER node[\s\S]*RUN pnpm prune --prod/,
+		);
 		expect(dockerfile).toMatch(
-			/FROM node-base AS runtime[\s\S]*USER node[\s\S]*RUN pnpm install --prod/,
+			/FROM node-base AS runtime[\s\S]*COPY --from=prod-deps[\s\S]*USER node/,
+		);
+		expect(dockerfile.slice(dockerfile.indexOf("FROM node-base AS runtime"))).not.toContain(
+			"pnpm install",
 		);
 	});
 
+	it("Dockerfile pins its mutable build inputs (#289)", () => {
+		// Base image by digest — the tag alone is a moving pointer, and
+		// Dependabot's docker ecosystem bumps tag and digest together.
+		expect(dockerfile).toMatch(/FROM node:24-alpine@sha256:[0-9a-f]{64} AS node-base/);
+		// Global corepack by version — `npm install -g corepack` with no pin
+		// resolved whatever was latest at build time.
+		expect(dockerfile).toMatch(/npm install -g corepack@\d+\.\d+\.\d+ --force/);
+		// The lockfile is a required build input for --frozen-lockfile.
+		expect(dockerfile).toMatch(/COPY --chown=node:node package\.json pnpm-lock\.yaml/);
+	});
+
 	it("GET /_healthcheck returns 200", async () => {
 		const { app, handle } = await buildApp();
 		handleRef = handle;
@@ -222,6 +266,39 @@ describe("standalone smoke test", () => {
 		expect(res.status).toBe(200);
 	});
 
+	it("GET /readyz returns 200 for a memory-only composition with no probes", async () => {
+		// These smoke modules are all in-memory, so nothing registers a probe.
+		// Readiness must not invent a dependency that is not wired.
+		const { app, handle } = await buildApp();
+		handleRef = handle;
+		const res = await request(app).get("/readyz");
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual({ status: "ready", checks: [] });
+	});
+
+	it("GET /readyz returns 503 naming the dependency when a probe fails", async () => {
+		const { handle } = await buildApp();
+		handleRef = handle;
+		const app = express();
+		app.use(
+			createReadinessRouter(express, {
+				probes: [
+					{
+						name: "redis",
+						check: async () => {
+							throw new Error("ECONNREFUSED");
+						},
+					},
+				],
+				timeoutMs: config.http.readinessTimeoutMs,
+			}),
+		);
+		const res = await request(app).get("/readyz");
+		expect(res.status).toBe(503);
+		expect(res.body.status).toBe("unready");
+		expect(res.body.checks[0].name).toBe("redis");
+	});
+
 	it("issuer-configured buildModules serves the advertised jwks_uri (discovery <-> JWKS presence contract)", async () => {
 		// Guards the cross-module contract end-to-end against the REAL composition
 		// root: core's `jwksModule` contributes `jwks_uri` to discovery AND mounts
@@ -256,6 +333,12 @@ describe("standalone smoke test", () => {
 		const res = await request(app).get(jwksPath);
 		expect(res.status).toBe(200);
 		expect(Array.isArray(res.body.keys)).toBe(true);
+		// #282: presence is no longer enough — the advertised jwks_uri must
+		// publish an actual verification key, and never the private half.
+		expect(res.body.keys).toHaveLength(1);
+		expect(res.body.keys[0].alg).toBe("EdDSA");
+		expect(res.body.keys[0].kid).toBe("v0");
+		expect(res.body.keys[0].d).toBeUndefined();
 	});
 
 	it("POST /oauth/token with unsupported grant_type returns 400", async () => {
@@ -388,6 +471,81 @@ describe("standalone smoke test", () => {
 		});
 	});
 
+	// #277: the scaffold used to wire NO access-token denylist, so the
+	// `/oauth/revoke` it shipped answered 200 for an access token and left the
+	// JWT working until expiry. The template now always wires one, and its own
+	// application.conf selects the Redis-backed adapter — the memory one forks
+	// per replica and `deployment.mode = "multi"` refuses it.
+	describe("#277: access-token denylist wiring", () => {
+		it("always wires a denylist, so /oauth/revoke can keep its promise", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const providesDenylist = modules.filter((m) =>
+				Object.keys(m.provides ?? {}).includes("accessTokenDenylist"),
+			);
+			expect(providesDenylist).toHaveLength(1);
+		});
+
+		it("defaults to the memory denylist when no adapter is configured", () => {
+			const modules = buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("core-access-token-denylist-memory");
+			expect(names).not.toContain("redis-access-token-denylist");
+		});
+
+		it("switches to the Redis denylist when accessTokenDenylist.adapter = 'redis'", () => {
+			const redisDenylistConfig = {
+				...config,
+				accessTokenDenylist: { adapter: "redis" as const },
+			};
+			const modules = buildModules(redisDenylistConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redis-access-token-denylist");
+			expect(names).not.toContain("core-access-token-denylist-memory");
+			// The Redis branch must also pull in the shared ioredis socket, or the
+			// `accessTokenDenylistClient` slot has no provider and boot fails on a
+			// missing component instead of on the thing the operator changed.
+			expect(names).toContain("standalone:redis-clients");
+		});
+
+		it("the shipped application.conf selects the replica-safe adapter", () => {
+			// The template's own config is the artifact operators deploy. It runs
+			// with `deployment.mode = multi` in the umbrella E2E, which refuses
+			// every in-memory shared store — so shipping the memory denylist here
+			// would be a boot failure in the very stack that proves the scaffold
+			// works.
+			const conf = readFileSync(new URL("../../config/application.conf", import.meta.url), "utf8");
+			expect(conf).toMatch(/accessTokenDenylist\s*\{[\s\S]*?adapter\s*=\s*"redis"/);
+		});
+
+		it("keeps the composition boot-valid end to end", async () => {
+			// The core boot guard (#277 step 13.9) refuses a composition that reads
+			// the denylist slot without one. A scaffold that trips its own library's
+			// guard is not a scaffold.
+			const handle = await createApp({
+				modules: buildModules(config, {
+					keyStoreModule: testKeyStoreModule,
+					repositoriesModule: testRepositoriesModule,
+					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+				}),
+				bootstrapComponents: { config, pathResolver: (s) => s },
+			});
+			handleRef = handle;
+			expect(handle).toBeDefined();
+		});
+	});
+
 	// OR-9 (Wave 5d): adapter switch for the OAuth code repository. Closes
 	// the deferred Phase 10 module-pattern wrapper for `codeRepository`. The
 	// memory branch wires `inMemoryCodeRepositoryModule`; the redis branch
@@ -476,9 +634,17 @@ describe("standalone smoke test", () => {
 			type: "local",
 			...(config.oauth.jwt.signingKey.local ?? {}),
 		});
+		// The token must carry the deployment's configured `iss`: introspection
+		// pins it (RFC 9068 §4), and since #266 every deployment has one.
 		const { token } = await generateToken(
 			{},
-			{ keyStore, subject: "u1", expiresIn: 3600, tokenType: "at+jwt" },
+			{
+				keyStore,
+				subject: "u1",
+				expiresIn: 3600,
+				tokenType: "at+jwt",
+				issuer: config.oauth.jwt.issuer,
+			},
 		);
 
 		const res = await request(app)