@o3co/create-auth-provider 0.11.0 → 0.12.1

package/templates/standalone/src/__tests__/session-logout-invalidates-token.test.mts

@@ -0,0 +1,288 @@
+/*
+ * 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.
+ */
+
+/**
+ * `POST /session/logout` must invalidate the token the `session` grant minted
+ * from the same browser session.
+ *
+ * This lives here rather than in `packages/session` or `packages/oauth`
+ * because it is the one assertion neither package can make alone: the logout
+ * endpoint is in `@o3co/auth-provider-session`, the introspection and userinfo
+ * endpoints are in `@o3co/auth-provider-oauth`, and the two are siblings that
+ * may not import each other. The standalone template is the composition root
+ * where both are mounted on one app, so it is where the contract between them
+ * is testable.
+ *
+ * What it pins: #506 stamped `sid` on the `session` grant's access token and
+ * gave `/oauth/introspect` the session-liveness check `/oauth/userinfo`
+ * already ran. Both resolve the `UserSession` record — which `/session/logout`
+ * used to leave alive, because it destroyed the cookie and nothing else. So in
+ * the BFF / `auth.proxy` injection topology, whose logout IS this endpoint, an
+ * access token minted from the session kept introspecting `active: true` and
+ * kept answering at `/userinfo` for its full lifetime after the user logged
+ * out. Only `/oauth/logout` with an `id_token_hint` was ever closed by #506.
+ */
+
+import { generateKeyPairSync } from "node:crypto";
+import {
+	type AppConfig,
+	createApp,
+	createKeyStoreFactory,
+	createReadinessRouter,
+	defineModule,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+} from "@o3co/auth-provider-core";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+
+const keyPair = generateKeyPairSync("ed25519", {
+	publicKeyEncoding: { type: "spki", format: "pem" },
+	privateKeyEncoding: { type: "pkcs8", format: "pem" },
+});
+
+const CLIENT_ID = "bff-client";
+const CLIENT_SECRET = "bff-secret";
+const BASIC = `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`;
+const USERNAME = "alice";
+const PASSWORD = "correct-horse-battery-staple";
+
+const config: AppConfig = {
+	http: { port: 0, trustProxy: false, readinessTimeoutMs: 1000 },
+	logging: { level: "silent" },
+	oauth: {
+		jwt: {
+			issuer: "https://auth.test",
+			signingKey: {
+				provider: "local",
+				local: {
+					algorithm: "EdDSA",
+					kid: "v0",
+					privateKey: keyPair.privateKey,
+					publicKey: keyPair.publicKey,
+					previousKeys: [],
+				},
+			},
+		},
+		accessToken: { expiresIn: 3600 },
+		refreshToken: {
+			expiresIn: 86400,
+			unknownFamilyPolicy: "reject" as const,
+			legacyRtPolicy: "reject" as const,
+		},
+		// The grant this whole test is about: it mints straight from an
+		// authenticated browser session, which is the BFF topology.
+		grants: { session: { enabled: true } },
+		oidcMode: "oidc-required",
+		code: { adapter: "memory" as const },
+	},
+	session: {
+		secret: "test-session-secret.at-least-32-bytes.ok",
+		name: "auth.sid",
+		maxAge: 3600000,
+		secure: false,
+		sameSite: "lax",
+		domain: null,
+		storage: { type: "memory", redis: { url: "redis://localhost:6379" } },
+	},
+	rateLimit: {
+		login: { windowMs: 60000, limit: 100 },
+		failMode: "open",
+	},
+	federations: { google: { enabled: false } },
+	repositories: {
+		client: { type: "yaml", path: "./config/clients.yaml" },
+		user: { type: "yaml", path: "./config/users.yaml", timeout: 5000 },
+		code: { type: "memory", defaultExpiresIn: 600 },
+	},
+	endpoints: { login: { url: "/login" } },
+	cors: { allowedOrigins: [] },
+} as unknown as AppConfig;
+
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: CLIENT_SECRET,
+							allowedRedirectUris: [],
+							allowedScopes: ["openid", "profile"],
+							allowedAudiences: [],
+							allowedGrantTypes: ["session"],
+							backchannelLogoutSessionRequired: true,
+							frontchannelLogoutSessionRequired: true,
+							allowedAzpForFederationToken: false,
+						},
+					],
+				]),
+			),
+		userRepository: () =>
+			new InMemoryUserRepository(
+				new Map([[USERNAME, { id: "u-alice", password: PASSWORD, email: "alice@example.com" }]]),
+			),
+	} as never,
+});
+
+const testKeyStoreModule = defineModule({
+	name: "test:key-store",
+	requires: ["config"] as const,
+	provides: {
+		keyStore: async ({ config: c }) => {
+			const factory = createKeyStoreFactory();
+			registerBuiltinKeyStores(factory);
+			return factory.create({
+				type: "local",
+				...((c as AppConfig).oauth.jwt.signingKey.local ?? {}),
+			});
+		},
+	},
+});
+
+describe("POST /session/logout invalidates the session grant's access token", () => {
+	let handleRef: Awaited<ReturnType<typeof createApp>> | undefined;
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	async function buildApp() {
+		const handle = await createApp({
+			modules: buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			bootstrapComponents: { config, pathResolver: (s) => s },
+		});
+		handleRef = handle;
+
+		const app = express();
+		app.use(
+			createReadinessRouter(express, {
+				probes: handle.readinessProbes,
+				timeoutMs: config.http.readinessTimeoutMs,
+			}),
+		);
+		app.use(handle.router);
+		return app;
+	}
+
+	/**
+	 * Drives the real browser half: fetch a CSRF pair, log in, and return the
+	 * cookies plus the token the login response reissued. `/session/login`
+	 * hands back a fresh CSRF cookie precisely so the follow-up logout needs no
+	 * second round trip.
+	 */
+	async function login(app: express.Express) {
+		const csrfRes = await request(app).get("/session/csrf");
+		expect(csrfRes.status).toBe(200);
+		const csrfToken = csrfRes.body.csrf_token as string;
+		const headerName = csrfRes.body.header_name as string;
+		const csrfCookies = csrfRes.headers["set-cookie"] as unknown as string[];
+
+		const loginRes = await request(app)
+			.post("/session/login")
+			.set("Cookie", csrfCookies)
+			.set(headerName, csrfToken)
+			.type("form")
+			.send({ username: USERNAME, password: PASSWORD });
+		expect(loginRes.status).toBe(200);
+
+		const loginCookies = loginRes.headers["set-cookie"] as unknown as string[];
+		// The session cookie comes from the login response, and so does a FRESH
+		// CSRF cookie — the login handler reissues one on the regenerated
+		// session so the follow-up logout needs no second round trip. The
+		// mechanism is a signed double-submit, so the cookie's value IS the
+		// token the header has to echo; the pre-login token no longer matches.
+		const csrfCookiePrefix = `${config.session.name}.csrf=`;
+		const reissued = loginCookies
+			.find((c) => c.startsWith(csrfCookiePrefix))
+			?.slice(csrfCookiePrefix.length)
+			.split(";")[0];
+		expect(reissued).toBeDefined();
+		return {
+			cookies: loginCookies,
+			csrfToken: decodeURIComponent(reissued as string),
+			headerName,
+		};
+	}
+
+	it("a token minted from the session stops introspecting active after the session logs out", async () => {
+		const app = await buildApp();
+		const { cookies, csrfToken, headerName } = await login(app);
+
+		// The BFF exchanges the browser session for an access token.
+		const tokenRes = await request(app)
+			.post("/oauth/token")
+			.set("Authorization", BASIC)
+			.set("Cookie", cookies)
+			.type("form")
+			.send({ grant_type: "session", scope: "openid profile" });
+		expect(tokenRes.status).toBe(200);
+		const accessToken = tokenRes.body.access_token as string;
+		expect(typeof accessToken).toBe("string");
+
+		// Before the logout the token is a live credential at both surfaces.
+		const beforeIntrospect = await request(app)
+			.post("/oauth/introspect")
+			.set("Authorization", BASIC)
+			.type("form")
+			.send({ token: accessToken });
+		expect(beforeIntrospect.status).toBe(200);
+		expect(beforeIntrospect.body.active).toBe(true);
+
+		const beforeUserinfo = await request(app)
+			.get("/oauth/userinfo")
+			.set("Authorization", `Bearer ${accessToken}`);
+		expect(beforeUserinfo.status).toBe(200);
+
+		// The logout the BFF topology actually performs — no id_token_hint, no
+		// `/oauth/logout`, just the session endpoint the browser calls.
+		const logoutRes = await request(app)
+			.post("/session/logout")
+			.set("Cookie", cookies)
+			.set(headerName, csrfToken);
+		expect(logoutRes.status).toBe(200);
+		expect(logoutRes.body).toMatchObject({ message: "Logged out successfully" });
+
+		// After it, the same token no longer authorizes anything. This is the
+		// assertion that failed before the fix: the `UserSession` record the
+		// liveness checks resolve outlived the logout.
+		const afterIntrospect = await request(app)
+			.post("/oauth/introspect")
+			.set("Authorization", BASIC)
+			.type("form")
+			.send({ token: accessToken });
+		expect(afterIntrospect.status).toBe(200);
+		expect(afterIntrospect.body.active).toBe(false);
+
+		const afterUserinfo = await request(app)
+			.get("/oauth/userinfo")
+			.set("Authorization", `Bearer ${accessToken}`);
+		expect(afterUserinfo.status).toBe(401);
+		expect(afterUserinfo.body.error_description).toBe("session_invalid");
+	});
+});

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

@@ -33,7 +33,7 @@
 import type { Server } from "node:http";
 import type { Logger } from "@o3co/auth-provider-core";
 import { describe, expect, it, vi } from "vitest";
-import { installGracefulShutdown } from "../shutdown.mjs";
+import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
 
 /** A `Server` double whose `close` callback fires only when we say so. */
 function makeServer() {
@@ -234,6 +234,86 @@ describe("installGracefulShutdown (#290)", () => {
 		expect(cleanup).toHaveBeenCalledTimes(1);
 	});
 
+	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
+		// The guarantees above say cleanup "never wedges the process", but `finish`
+		// awaited it with no deadline — and the drain deadline is already cleared
+		// by then, so a dispose that never settles meant `exit` was never reached.
+		// The same defect was found in auth.proxy#81 and auth.policy-verifier#210,
+		// both of which took this file as their starting point.
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(5_000);
+			expect(logger.error).toHaveBeenCalledWith(
+				expect.objectContaining({ cleanupTimeoutMs: 5_000 }),
+				expect.stringContaining("cleanup timed out"),
+			);
+			expect(exit).toHaveBeenCalledWith(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not penalise a cleanup that finishes inside its budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => Promise.resolve(),
+				drainTimeoutMs: 5_000,
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(10_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("defers the real exit a turn so a buffered log destination can flush", async () => {
+		// The scaffolded app logs NDJSON through pino, whose default destination is
+		// not synchronous: exiting in the same tick as the last `logger.error` can
+		// drop exactly the `cleanup failed` line an operator would look for.
+		const exitProcess = vi.fn();
+		deferExit(3, exitProcess);
+		expect(exitProcess).not.toHaveBeenCalled();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(exitProcess).toHaveBeenCalledWith(3);
+	});
+
+	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
+		// `exitCode` became 1 while `reason` still said "drained", so the one line
+		// an operator alerts on contradicted itself. The drain outcome is still
+		// carried, under its own key, so neither fact is lost.
+		const { signals, finishDraining, logger, exit } = install({
+			cleanup: () => Promise.reject(new Error("teardown failed")),
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
+			"graceful shutdown: complete",
+		);
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("keeps reason and drain identical when cleanup succeeds", async () => {
+		const { signals, finishDraining, logger } = install({ cleanup: () => Promise.resolve() });
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await new Promise((resolve) => setImmediate(resolve));
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "drained", drain: "drained", exitCode: 0 },
+			"graceful shutdown: complete",
+		);
+	});
+
 	it("removes its own signal listeners once shutting down", async () => {
 		// Otherwise a repeated signal keeps re-entering a handler that has
 		// already handed the process over to `close`.

package/templates/standalone/src/__tests__/three-tier-resolution.test.mts

@@ -193,18 +193,23 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 			// every in-memory shared store, so the denylist this change adds has to
 			// come out of that environment as the Redis one — from the template's
 			// own config, since the compose file names no denylist variable.
-			// Asserted against the guard's own list rather than a module name, so a
-			// rename cannot quietly invalidate it.
-			const { REPLICA_UNSAFE_MODULES } = await import("@o3co/auth-provider-core");
+			// Asked of each manifest, the way the guard does (#455), so a rename
+			// cannot quietly invalidate it and the template's own memory modules
+			// — which no name list in core covers — count too.
+			const { replicaUnsafeReason } = await import("@o3co/auth-provider-core");
 			const config = buildResolvedConfig("production", {
 				USER_SESSION_STORES_ADAPTER: "redis",
 				RATE_LIMITER_ADAPTER: "redis",
 				OAUTH_CODE_ADAPTER: "redis",
+				// #456: the federation token store defaults to memory, and the
+				// memory module declares itself replica-unsafe (#455).
+				FEDERATION_TOKEN_STORE_TYPE: "redis",
+				REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
 			});
-			const names = buildModules(config).map((m) => m.name);
-			expect(names).toContain("redis-access-token-denylist");
-			for (const name of names) {
-				expect(REPLICA_UNSAFE_MODULES).not.toContain(name);
+			const modules = buildModules(config);
+			expect(modules.map((m) => m.name)).toContain("redis-access-token-denylist");
+			for (const module of modules) {
+				expect(replicaUnsafeReason(module), module.name).toBeUndefined();
 			}
 		});
 

package/templates/standalone/src/app.mts

@@ -99,8 +99,12 @@ await (async (): Promise<void> => {
 	// `buildModules` is the single source of truth for the module list — it
 	// gates federation modules on `config.federations.<name>.enabled`, which
 	// the standalone scaffold defaults to false.
+	//
+	// `environment` is the name the config above was selected by (#473): the
+	// Redis federation-token store's plaintext guard reads it in addition to
+	// NODE_ENV, so `CONFIG_ENV=production` is production to the guard too.
 	const handle = await createApp({
-		modules: buildModules(config),
+		modules: buildModules(config, { environment: env }),
 		bootstrapComponents: {
 			config,
 			pathResolver: import.meta.resolve,

package/templates/standalone/src/buildModules.mts

@@ -31,16 +31,17 @@ import {
 import {
 	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
+	redisFederationTokenStoreModuleFor,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
 	redisSessionStoresModule,
 } from "@o3co/auth-provider-redis";
-import { sessionModule, sessionStoreModule } from "@o3co/auth-provider-session";
+import { sessionModule, sessionStoreModuleFor } from "@o3co/auth-provider-session";
 import {
 	auditSinkModule,
-	federationTokenStoreModule,
 	googleFederationConfigModule,
 	inMemoryCodeRepositoryModule,
+	inMemoryFederationTokenStoreModule,
 	inMemorySessionStoresModule,
 	keyStoreModule,
 	repositoriesModule,
@@ -48,11 +49,21 @@ import {
 } from "./modules.mjs";
 
 /**
- * Test-only overrides allowing the smoke test to substitute in-memory
- * implementations of the file-system-backed modules. Production callers
- * should not pass overrides; the defaults match the standalone scaffold.
+ * Overrides for the composition. All but `environment` are test-only: they let
+ * the smoke test substitute in-memory implementations of the file-system-backed
+ * modules, and production callers should not pass them — the defaults match the
+ * standalone scaffold.
  */
 export interface BuildModulesOverrides {
+	/**
+	 * #473: the name this deployment selected its configuration by —
+	 * `CONFIG_ENV || NODE_ENV`, computed once in `app.mts` and passed here so
+	 * the Redis federation-token store's `allow-plaintext` guard reads the
+	 * environment the config actually came from, not `NODE_ENV` alone. Omitted,
+	 * the guard falls back to `NODE_ENV` (and `deployment.mode`, which it reads
+	 * off the config either way).
+	 */
+	readonly environment?: string;
 	readonly keyStoreModule?: Module;
 	readonly repositoriesModule?: Module;
 	readonly storesModule?: Module;
@@ -117,6 +128,12 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// endpoint would answer 200 while the token kept working. The switch here is
 	// only over WHICH denylist.
 	const accessTokenDenylistAdapter = config.accessTokenDenylist?.adapter ?? "memory";
+	// #456: adapter switch for the federation token store. `"memory"` by
+	// default, the template's local-dev shape; `"redis"` mounts
+	// `redisFederationTokenStoreModule` off the shared socket — what the README
+	// promised and what the previous factory-based module never delivered: it
+	// built the Redis store without a client and failed at boot.
+	const federationTokenStoreAdapter = config.federationTokenStore?.type ?? "memory";
 
 	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
 	// authoritative switch; the legacy `repositories.code.type = "redis"`
@@ -154,12 +171,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		rateLimiterAdapter === "redis" ||
 		userSessionStoresAdapter === "redis" ||
 		codeRepositoryAdapter === "redis" ||
-		accessTokenDenylistAdapter === "redis";
+		accessTokenDenylistAdapter === "redis" ||
+		federationTokenStoreAdapter === "redis";
 
-	// Federation-token store is always wired; only the 4 user-session
-	// stores switch on the adapter. Pre-Wave-5d the redis branch dropped
-	// the federation-token-store provider entirely (Copilot review on
-	// PR #121); splitting `storesModule` fixes that boot failure.
+	// The four user-session stores switch on `userSessionStores.adapter`; the
+	// federation-token store is always wired and switches on its own key
+	// below (#456). Pre-Wave-5d the redis branch dropped the
+	// federation-token-store provider entirely (Copilot review on PR #121);
+	// splitting `storesModule` fixed that boot failure.
 	const sessionStoresModules: Module[] =
 		userSessionStoresAdapter === "redis"
 			? [redisSessionStoresModule]
@@ -188,13 +207,32 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 			? [redisAccessTokenDenylistModule]
 			: [memoryAccessTokenDenylistModule];
 
+	// #455 / #456: mutually-exclusive federation-token-store pair, the same
+	// shape as the session stores. One module per adapter, so the memory one
+	// can declare `replicaSafety` on its manifest and the Redis one can
+	// `require` its client slot. The previous single module chose the adapter
+	// at runtime under one name — the replica guard could not tell the two
+	// apart, and the Redis branch had no client to hand the builder.
+	//
+	// #473: the Redis module is built for this composition root so its
+	// plaintext guard knows which environment selected the config; it reads
+	// `deployment.mode` off the config itself.
+	const federationTokenStoreModules: Module[] =
+		federationTokenStoreAdapter === "redis"
+			? [redisFederationTokenStoreModuleFor({ environment: overrides.environment })]
+			: [inMemoryFederationTokenStoreModule];
+
 	return [
 		// D-5: sessionStoreModule wires the express-session middleware into the
 		// boot-planner-managed lifecycle. **Mount order is enforced by this
 		// list position (declarationIndex tie-breaking)** — the module
 		// intentionally has no `before`/`after` clause, so it MUST be listed
 		// ahead of every session-consuming module here. Do not reorder.
-		sessionStoreModule,
+		//
+		// #474: built from `config` rather than the static manifest, so that
+		// `session.storage.type = "memory"` declares itself replica-unsafe and
+		// `deployment.mode = "multi"` refuses it by name like the other stores.
+		sessionStoreModuleFor(config),
 		oauthModule({ config }),
 		oauthSessionModule({ config }),
 		oauthAuthorizationModule({ config }),
@@ -220,11 +258,11 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// actually needs Redis. Memory-only deployments skip this so they
 		// don't open an unused socket.
 		...(usingRedisAnywhere ? [standaloneRedisClientsModule] : []),
-		// Federation-token store — always wired; independent of the
-		// `userSessionStores.adapter` switch. Was bundled into `storesModule`
-		// pre-Wave-5d; split so the redis session-stores branch doesn't
-		// drop the provider.
-		federationTokenStoreModule,
+		// Federation-token store: redis (multi-replica) or memory (dev). Always
+		// wired, independent of the `userSessionStores.adapter` switch — it was
+		// bundled into `storesModule` pre-Wave-5d, and the redis session-stores
+		// branch dropped the provider.
+		...federationTokenStoreModules,
 		// User-session-store family: redis (multi-replica) or memory (dev).
 		...sessionStoresModules,
 		// OAuth-endpoint rate limiter: redis (shared counters) or memory.