@o3co/create-auth-provider 0.14.0 → 0.16.0

package/templates/standalone/src/__tests__/store-credential.test.mts

@@ -0,0 +1,276 @@
+/*
+ * 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 credential auth.provider presents to the Store, through the shipped
+ * composition: `CLIENT_USER_BEARER_TOKEN` in the environment → the HOCON
+ * layers → `AppConfigSchema` → the production `repositoriesModule` → the
+ * `"http"` user adapter → the `Authorization` header a real `node:http` Store
+ * receives. Unset, the Store receives no `Authorization` header; set blank —
+ * an exported-but-empty variable — the user repository is refused.
+ *
+ * And what a mismatch looks like from outside, with the app booted from the
+ * shipped config through `createApp`: a Store that refuses the token with a
+ * `401` and a `Bearer` challenge turns `POST /session/login` into a `503`
+ * whose log line names the refused credential and never the token; a `401`
+ * without the challenge is still a wrong password.
+ */
+
+import { createServer, type OutgoingHttpHeaders, type Server } from "node:http";
+import { fileURLToPath } from "node:url";
+import { inspect } from "node:util";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	type Logger,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+	type UserRepository,
+} from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+import { repositoriesModule } from "../modules.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/** 32 bytes of key material — what `openssl rand -hex 32` prints. */
+const TOKEN = "7d1f0c3b9a5e2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f";
+
+let servers: Server[] = [];
+afterEach(async () => {
+	await Promise.all(
+		servers.map((server) => {
+			server.closeAllConnections();
+			return new Promise<void>((resolve) => server.close(() => resolve()));
+		}),
+	);
+	servers = [];
+});
+
+/** How the Store answers every request. */
+interface StoreAnswer {
+	readonly status: number;
+	readonly headers?: OutgoingHttpHeaders;
+	readonly body: unknown;
+}
+
+const USER: StoreAnswer = { status: 200, body: { id: "user-1", username: "alice" } };
+
+/** A Store on its own loopback port that records each request's Authorization header. */
+const recordingStore = async (
+	answer: StoreAnswer = USER,
+): Promise<{ origin: string; heard: (string | undefined)[] }> => {
+	const heard: (string | undefined)[] = [];
+	const server = createServer((req, res) => {
+		req.resume();
+		req.on("end", () => {
+			heard.push(req.headers.authorization);
+			res.writeHead(answer.status, { "Content-Type": "application/json", ...answer.headers });
+			res.end(JSON.stringify(answer.body));
+		});
+	});
+	servers.push(server);
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const { port } = server.address() as { port: number };
+	return { origin: `http://127.0.0.1:${port}`, heard };
+};
+
+/** The shipped config for the production overlay, resolved against `env`. */
+const resolve = (env: Record<string, string>): AppConfig => {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	return validate(
+		parseFile(envConfPath, { env })
+			.withFallback(parseFile(applicationConfPath, { env }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env })),
+		AppConfigSchema,
+	);
+};
+
+/** The user repository the production `repositoriesModule` builds from `config`. */
+const userRepositoryFrom = (config: AppConfig): Promise<UserRepository> =>
+	Promise.resolve(
+		repositoriesModule.provides?.userRepository?.({ config } as never) as
+			| UserRepository
+			| Promise<UserRepository>,
+	);
+
+const envFor = (origin: string): Record<string, string> => ({
+	OAUTH_JWT_ALGORITHM: "HS256",
+	OAUTH_JWT_SECRET: "store-credential-composition.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_SECRET: "store-credential-composition-session.at-least-32-bytes.ok",
+	CLIENT_USER_TYPE: "http",
+	CLIENT_USER_AUTHENTICATE_URL: `${origin}/authenticate`,
+	CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL: `${origin}/authenticate-by-token`,
+});
+
+describe("CLIENT_USER_BEARER_TOKEN reaches the Store through the shipped composition", () => {
+	it("sends Authorization: Bearer <token> on every Store call when the variable is set", async () => {
+		const { origin, heard } = await recordingStore();
+		const repo = await userRepositoryFrom(
+			resolve({ ...envFor(origin), CLIENT_USER_BEARER_TOKEN: TOKEN }),
+		);
+
+		await repo.authenticate("alice", "pass");
+		await repo.authenticateByToken("apple:a1");
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`, `Bearer ${TOKEN}`]);
+	});
+
+	it("sends no Authorization header when the variable is unset", async () => {
+		const { origin, heard } = await recordingStore();
+		const repo = await userRepositoryFrom(resolve(envFor(origin)));
+
+		await repo.authenticate("alice", "pass");
+
+		expect(heard).toEqual([undefined]);
+	});
+
+	it("refuses the user repository when the variable is exported but empty", async () => {
+		const { origin, heard } = await recordingStore();
+		const config = resolve({ ...envFor(origin), CLIENT_USER_BEARER_TOKEN: "" });
+
+		await expect(userRepositoryFrom(config)).rejects.toThrow(/"bearerToken" must not be empty/);
+		expect(heard).toEqual([]);
+	});
+});
+
+describe("a token the Store refuses, seen from outside the booted app", () => {
+	/** Every store on memory, so the boot opens no socket but the Store's. */
+	const MEMORY_ENV: Readonly<Record<string, string>> = {
+		SESSION_SECURE: "false",
+		SESSION_NAME: "auth.session",
+		SESSION_STORAGE_TYPE: "memory",
+		USER_SESSION_STORES_ADAPTER: "memory",
+		RATE_LIMITER_ADAPTER: "memory",
+		OAUTH_CODE_ADAPTER: "memory",
+		ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+		REPLAY_SEEN_SET_ADAPTER: "memory",
+		FEDERATION_TOKEN_STORE_TYPE: "memory",
+		CONSENT_STORE_ADAPTER: "none",
+		FEDERATION_GRANT_STORE_ADAPTER: "memory",
+		FEDERATION_GRANT_INTENT_STORE_ADAPTER: "memory",
+	};
+
+	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 ?? {}),
+				});
+			},
+		},
+	});
+
+	/** Every log call, as the arguments it was made with. */
+	const capturingLogger = (): { logger: Logger; lines: { level: string; args: unknown[] }[] } => {
+		const lines: { level: string; args: unknown[] }[] = [];
+		const at =
+			(level: string) =>
+			(...args: unknown[]): void => {
+				lines.push({ level, args });
+			};
+		const logger = {
+			trace: at("trace"),
+			debug: at("debug"),
+			info: at("info"),
+			warn: at("warn"),
+			error: at("error"),
+			fatal: at("fatal"),
+			child: () => logger,
+		} as Logger;
+		return { logger, lines };
+	};
+
+	let handleRef: Awaited<ReturnType<typeof createApp>> | undefined;
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	/**
+	 * The shipped config against a Store answering `answer`, booted with the
+	 * production repositories module; then a real browser login — a CSRF pair,
+	 * then the form post.
+	 */
+	const logInAgainst = async (answer: StoreAnswer) => {
+		const { origin, heard } = await recordingStore(answer);
+		const config = resolve({ ...envFor(origin), ...MEMORY_ENV, CLIENT_USER_BEARER_TOKEN: TOKEN });
+		const { logger, lines } = capturingLogger();
+		handleRef = await createApp({
+			modules: buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			bootstrapComponents: { config, pathResolver: (s: string) => s, logger },
+		});
+		const app = express().use(handleRef.router);
+
+		const csrf = await request(app).get("/session/csrf");
+		expect(csrf.status).toBe(200);
+		const login = await request(app)
+			.post("/session/login")
+			.set("Cookie", csrf.headers["set-cookie"] as unknown as string[])
+			.set(csrf.body.header_name as string, csrf.body.csrf_token as string)
+			.type("form")
+			.send({ username: "alice", password: "correct-horse-battery-staple" });
+		const logged = lines.map((line) =>
+			inspect(line, { depth: Number.POSITIVE_INFINITY, showHidden: true }),
+		);
+		return { login, heard, logged };
+	};
+
+	it("answers the login 503 and logs the refused credential by name, never the token", async () => {
+		const { login, heard, logged } = await logInAgainst({
+			status: 401,
+			headers: { "WWW-Authenticate": 'Bearer error="invalid_token"' },
+			body: { error: "invalid_token" },
+		});
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`]);
+		expect(login.status).toBe(503);
+		expect(login.body.error).toBe("temporarily_unavailable");
+		expect(logged.filter((line) => /refused this deployment's credential/.test(line))).toHaveLength(
+			1,
+		);
+		expect(logged.filter((line) => line.includes(TOKEN))).toEqual([]);
+	});
+
+	it("still answers a 401 without the challenge as a wrong password", async () => {
+		const { login, heard, logged } = await logInAgainst({
+			status: 401,
+			body: { error: "invalid_credentials" },
+		});
+
+		expect(heard).toEqual([`Bearer ${TOKEN}`]);
+		expect(login.status).toBe(401);
+		expect(login.body.error).toBe("invalid_credentials");
+		expect(logged.filter((line) => /refused this deployment's credential/.test(line))).toEqual([]);
+	});
+});

package/templates/standalone/src/app.mts

@@ -14,23 +14,18 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import {
-	type AppConfig,
-	AppConfigSchema,
-	createApp,
-	createHealthcheckRouter,
-	createReadinessRouter,
-} from "@o3co/auth-provider-core";
+import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import express from "express";
 import helmet from "helmet";
 import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
+import { listen } from "./listen.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
-import { installGracefulShutdown } from "./shutdown.mjs";
-import { createTerminalErrorHandler } from "./terminalError.mjs";
+import { mountRoutes } from "./routes.mjs";
+import { cleanupAllowanceFor, installGracefulShutdown } from "./shutdown.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
 // ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
@@ -103,8 +98,10 @@ await (async (): Promise<void> => {
 	// `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.
+	// `logger` is where the composition's own notices go (a deprecated config
+	// key), the same logger every module gets through the slot below.
 	const handle = await createApp({
-		modules: buildModules(config, { environment: env }),
+		modules: buildModules(config, { environment: env, logger }),
 		bootstrapComponents: {
 			config,
 			pathResolver: import.meta.resolve,
@@ -112,48 +109,22 @@ await (async (): Promise<void> => {
 		},
 	});
 
-	// Step 4: Wire host-level routes before the auth router so they remain
-	// reachable even when the auth pipeline is degraded — which is exactly when
-	// an operator needs an answer from them.
-	//
-	// 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: handle.readinessProbes,
-			timeoutMs: config.http.readinessTimeoutMs,
-			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(
-		metrics.route(express, {
-			probes: handle.readinessProbes,
-			probeTimeoutMs: config.http.readinessTimeoutMs,
-		}),
-	);
-
-	// Step 5: Mount the composed auth router and start the HTTP server.
-	app.use(handle.router);
-	// Terminal error handler LAST (#293 item 8): Express routes an error only
-	// to handlers registered after the route that threw it. See
-	// `terminalError.mts` for what it catches and why.
-	app.use(createTerminalErrorHandler(logger));
-	const server = app.listen(config.http.port, (): void => {
-		logger.info(`Server is running on http://localhost:${config.http.port}`);
+	// Step 4: the host-level routes (liveness, readiness, metrics) ahead of the
+	// auth router so they remain reachable even when the auth pipeline is
+	// degraded — which is exactly when an operator needs an answer from them —
+	// then the composed auth router, then the terminal error handler. See
+	// `routes.mts` for what each is and why the order is what it is.
+	mountRoutes(app, {
+		router: handle.router,
+		probes: handle.readinessProbes,
+		readinessTimeoutMs: config.http.readinessTimeoutMs,
+		metrics,
+		logger,
 	});
+	// Step 5: start the HTTP server.
+	// Resolves once the socket is bound (`server_listening`); a port that
+	// cannot be bound rejects, and boot fails with that error (`listen.mts`).
+	const server = await listen(app, config.http.port, logger);
 
 	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
 	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain
@@ -164,8 +135,16 @@ await (async (): Promise<void> => {
 	// from the code you deploy. See `shutdown.mts` for the stated guarantees
 	// and for the deadline the previous implementation did not have. Size
 	// `drainTimeoutMs` below your orchestrator's kill grace period.
+	//
+	// #593 slice 7: with federation grants on, cleanup gets the longest refresh
+	// tail the configured budgets allow plus a margin — 45 s under the shipped
+	// ones — rather than inheriting the drain's ten: the dispose is what waits
+	// for a rotated credential's write. The compose files size
+	// `stop_grace_period` to cover the drain, this and an exit margin for the
+	// shipped budgets; a raised budget raises both.
 	installGracefulShutdown(server, {
 		logger,
 		cleanup: () => handle.dispose(),
+		...cleanupAllowanceFor(config),
 	});
 })();

package/templates/standalone/src/buildModules.mts

@@ -15,26 +15,34 @@
  */
 import {
 	type AppConfig,
+	consoleLogger,
 	defaultRefreshTokenFamilyRevocationModule,
 	defaultRefreshTokenFamilyRotationModule,
 	jwksModule,
+	type Logger,
 	type Module,
 	memoryAccessTokenDenylistModule,
 	memoryConsentStoreModule,
+	memoryFederationGrantIntentStoreModule,
+	memoryFederationGrantStoreModule,
 	memoryRateLimiterModule,
 	memoryReplaySeenSetModule,
 } from "@o3co/auth-provider-core";
 import { googleFederationModule } from "@o3co/auth-provider-federation-google";
+import { federationGrantsModules } from "@o3co/auth-provider-federation-grants";
 import { oidcFederationModule, oidcFederationNames } from "@o3co/auth-provider-federation-oidc";
 import {
 	oauthAuthorizationModule,
 	oauthModule,
 	oauthSessionModule,
+	subjectRevocationServiceModule,
 } from "@o3co/auth-provider-oauth";
 import {
 	redisAccessTokenDenylistModule,
 	redisCodeRepositoryModule,
 	redisConsentStoreModule,
+	redisFederationGrantIntentStoreModule,
+	redisFederationGrantStoreModuleFor,
 	redisFederationTokenStoreModuleFor,
 	redisRateLimiterModule,
 	redisRefreshTokenFamilyStoreModule,
@@ -59,10 +67,10 @@ import {
 } from "./modules.mjs";
 
 /**
- * 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.
+ * Overrides for the composition. All but `environment` and `logger` 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 {
 	/**
@@ -74,6 +82,12 @@ export interface BuildModulesOverrides {
 	 * off the config either way).
 	 */
 	readonly environment?: string;
+	/**
+	 * Where the composition's own notices go — a deprecated config key, one
+	 * `config_key_deprecated` line (warn) each. `app.mts` passes the logger it
+	 * hands every module; omitted, `consoleLogger`.
+	 */
+	readonly logger?: Logger;
 	readonly keyStoreModule?: Module;
 	readonly repositoriesModule?: Module;
 	readonly storesModule?: Module;
@@ -141,6 +155,7 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	const googleEnabled =
 		extractFederationSection(config.federations ?? {}, "google")?.type === "google";
 	const oidcFederations = oidcFederationNames(config.federations ?? {});
+	const logger = overrides.logger ?? consoleLogger;
 
 	// Wave 5d (IH-14 + OR-M1 + OR-4) + OR-9: adapter-driven branching for
 	// the OAuth-endpoint rate limiter, the user-session-store family, AND
@@ -174,6 +189,22 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	// 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";
+	// #593 slice 7: federation grants — a user's standing consent that a client
+	// may obtain upstream tokens with no session behind the call. Off by
+	// default, and off installs nothing: no store, no socket, no boot
+	// requirement a deployment that never asked for grants would have to meet.
+	// On, the routes and the background registry the shutdown drains come as a
+	// pair, each store follows its own switch (grants in Redis with acquisition
+	// in memory is a supported single-replica shape), and the subject-revocation
+	// service is installed so a credential change can reach the grants — its
+	// `federationGrantStore` edge is what makes "revoke everything this subject
+	// holds" include them. Enabling the feature is also a statement that the
+	// deployment has a consent page, a callback per connection and a user
+	// repository that covers each connection's registration; the routes module
+	// refuses at boot what is missing, naming it.
+	const federationGrantsEnabled = config.federationGrants?.enabled === true;
+	const federationGrantStoreAdapter = config.federationGrantStore?.adapter ?? "memory";
+	const federationGrantIntentStoreAdapter = config.federationGrantIntentStore?.adapter ?? "memory";
 
 	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
 	// authoritative switch; the legacy `repositories.code.type = "redis"`
@@ -186,9 +217,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	if (oauthCodeAdapter !== undefined) {
 		codeRepositoryAdapter = oauthCodeAdapter;
 	} else if (legacyCodeType === "redis") {
-		console.warn(
-			'[buildModules] `repositories.code.type = "redis"` is deprecated; use ' +
-				'`oauth.code.adapter = "redis"` instead — see CHANGELOG for the removal version.',
+		logger.warn(
+			{
+				key: "repositories.code.type",
+				env: "CLIENT_CODE_TYPE",
+				replacement: "oauth.code.adapter",
+				replacementEnv: "OAUTH_CODE_ADAPTER",
+			},
+			"config_key_deprecated",
 		);
 		codeRepositoryAdapter = "redis";
 	} else {
@@ -208,10 +244,14 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		accessToken.defaultExpiresIn === undefined &&
 		accessToken.expiresIn !== SHIPPED_ACCESS_TOKEN_EXPIRES_IN
 	) {
-		console.warn(
-			"[buildModules] `oauth.accessToken.expiresIn` (OAUTH_ACCESS_TOKEN_EXPIRES_IN) is " +
-				"deprecated; use `oauth.accessToken.defaultExpiresIn` " +
-				"(OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN) instead — see CHANGELOG for the removal version.",
+		logger.warn(
+			{
+				key: "oauth.accessToken.expiresIn",
+				env: "OAUTH_ACCESS_TOKEN_EXPIRES_IN",
+				replacement: "oauth.accessToken.defaultExpiresIn",
+				replacementEnv: "OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN",
+			},
+			"config_key_deprecated",
 		);
 	}
 
@@ -234,7 +274,11 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		accessTokenDenylistAdapter === "redis" ||
 		replaySeenSetAdapter === "redis" ||
 		consentStoreAdapter === "redis" ||
-		federationTokenStoreAdapter === "redis";
+		federationTokenStoreAdapter === "redis" ||
+		// Only while the feature is on: a switch left at "redis" for a feature
+		// that is off must not open a socket.
+		(federationGrantsEnabled &&
+			(federationGrantStoreAdapter === "redis" || federationGrantIntentStoreAdapter === "redis"));
 
 	// The four user-session stores switch on `userSessionStores.adapter`; the
 	// federation-token store is always wired and switches on its own key
@@ -299,6 +343,29 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 			? [redisFederationTokenStoreModuleFor({ environment: overrides.environment })]
 			: [inMemoryFederationTokenStoreModule];
 
+	// #593 slice 7: one module per store, nothing while the feature is off.
+	// The Redis grant store is built for this composition root so its
+	// plaintext guard knows which environment selected the config (#473), as
+	// the federation-token store's is. Both memory modules declare
+	// `replicaSafety`, so `deployment.mode = "multi"` refuses them by name; a
+	// Redis grant store beside memory user-session stores is refused by the
+	// routes module itself, because the grants would outlive the boundary that
+	// ends them (D13).
+	const federationGrantStoreModules: Module[] = !federationGrantsEnabled
+		? []
+		: federationGrantStoreAdapter === "redis"
+			? [
+					overrides.environment === undefined
+						? redisFederationGrantStoreModuleFor()
+						: redisFederationGrantStoreModuleFor({ environment: overrides.environment }),
+				]
+			: [memoryFederationGrantStoreModule];
+	const federationGrantIntentStoreModules: Module[] = !federationGrantsEnabled
+		? []
+		: federationGrantIntentStoreAdapter === "redis"
+			? [redisFederationGrantIntentStoreModule]
+			: [memoryFederationGrantIntentStoreModule];
+
 	return [
 		// D-5: sessionStoreModule wires the express-session middleware into the
 		// boot-planner-managed lifecycle. **Mount order is enforced by this
@@ -310,6 +377,12 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// `session.storage.type = "memory"` declares itself replica-unsafe and
 		// `deployment.mode = "multi"` refuses it by name like the other stores.
 		sessionStoreModuleFor(config),
+		// #593 slice 7: the grants routes mount under `/oauth` beside
+		// `oauthModule`'s router, which parses the bodies of its own routes
+		// only, so each parses its own requests and their place relative to
+		// `oauthModule` does not matter. The browser half sits after the
+		// session middleware by its own `after`, wherever it is listed.
+		...(federationGrantsEnabled ? federationGrantsModules : []),
 		oauthModule({ config }),
 		oauthSessionModule({ config }),
 		oauthAuthorizationModule({ config }),
@@ -343,6 +416,9 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		// bundled into `storesModule` pre-Wave-5d, and the redis session-stores
 		// branch dropped the provider.
 		...federationTokenStoreModules,
+		// #593 slice 7: the grant store and the intent store, when the feature is on.
+		...federationGrantStoreModules,
+		...federationGrantIntentStoreModules,
 		// User-session-store family: redis (multi-replica) or memory (dev).
 		...sessionStoresModules,
 		// OAuth-endpoint rate limiter: redis (shared counters) or memory.
@@ -361,5 +437,11 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 		...refreshTokenFamilyModules,
 		defaultRefreshTokenFamilyRotationModule,
 		defaultRefreshTokenFamilyRevocationModule,
+		// #593 slice 7: the composed "end everything this subject holds" a
+		// credential change calls, reached as `handle.components.subjectRevocationService`.
+		// Installed with the feature, which is what makes it reach the grants;
+		// the template never installed it before, so a deployment without
+		// grants is as it was — a Store there calls core's revokeAllForSubject.
+		...(federationGrantsEnabled ? [subjectRevocationServiceModule] : []),
 	];
 }

package/templates/standalone/src/listen.mts

@@ -0,0 +1,66 @@
+/*
+ * 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 { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { type Logger, loggableError } from "@o3co/auth-provider-core";
+import type { Express } from "express";
+
+/**
+ * Start the HTTP listener, and say so once it is bound.
+ *
+ * Resolves with the server once its socket is bound, after logging
+ * `server_listening` (info) with the port the socket holds — the configured
+ * one, or the one the OS picked for `0`. Rejects with the server's error when
+ * the socket cannot be bound (`EADDRINUSE`, `EACCES`), and logs nothing: the
+ * composition root awaits this, so the error ends boot the way any other boot
+ * failure does.
+ *
+ * The server is built here (`http.createServer(app)`, as `app.listen` itself
+ * does) and its events are wired here, so none of this rests on how a given
+ * Express version wires them. Until the socket is bound, one `error` listener
+ * turns a bind failure into the rejection. Once it is bound, that listener is
+ * removed and the server gets the one it keeps: a later `error` — an `accept`
+ * that fails with EMFILE — is logged as `server_error` (error, `err`: core's
+ * `loggableError` projection) and the process keeps running, the server
+ * accepting what it can. Without a listener of its own, such an error would be
+ * thrown out of the process.
+ *
+ * The standalone used to call `app.listen` with a callback that ignored its
+ * argument: Express 5 hands that callback the bind error too, so it announced
+ * a server on a port another process held and swallowed the error that should
+ * have ended the process.
+ */
+export function listen(app: Express, port: number, logger: Logger): Promise<Server> {
+	const server = createServer(app);
+	return new Promise((resolve, reject) => {
+		const refuse = (err: Error): void => {
+			server.off("listening", bound);
+			reject(err);
+		};
+		const bound = (): void => {
+			server.off("error", refuse);
+			server.on("error", (serverErr: Error) => {
+				logger.error({ err: loggableError(serverErr) }, "server_error");
+			});
+			const address = server.address() as AddressInfo | null;
+			logger.info({ port: address?.port ?? port }, "server_listening");
+			resolve(server);
+		};
+		server.once("error", refuse);
+		server.once("listening", bound);
+		server.listen(port);
+	});
+}