@o3co/create-auth-provider 0.14.0 → 0.15.0

package/templates/standalone/src/buildModules.mts

@@ -21,20 +21,26 @@ import {
 	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,
@@ -174,6 +180,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"`
@@ -234,7 +256,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 +325,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 +359,13 @@ 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: before `oauthModule`, whose router mounts under the same
+		// `/oauth` prefix with body parsers of its own — mounted after it, a
+		// malformed body would be refused by the OAuth router's parser without
+		// this package's request id, `Cache-Control: no-store` or throttle (the
+		// package README's mounting-order rule). 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 +399,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 +420,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/modules.mts

@@ -39,7 +39,11 @@ import {
 import type { GoogleProviderConfig } from "@o3co/auth-provider-federation-google";
 import { readOidcFederationConfigs } from "@o3co/auth-provider-federation-oidc";
 import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
-import { makeIoredisClients } from "@o3co/auth-provider-redis/ioredis";
+import {
+	makeIoredisClients,
+	makeIoredisFederationGrantIntentStoreClient,
+	makeIoredisFederationGrantStoreClient,
+} from "@o3co/auth-provider-redis/ioredis";
 import { extractFederationSection } from "@o3co/auth-provider-session";
 // Named import is required here, not default. ioredis is CJS and its entry
 // does `module.exports = Redis` with the class re-exported as both `default`
@@ -438,6 +442,28 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.sessionFederationIndexClient;
 		},
+		// #593 slice 7: the grant store and the intent store, off the same
+		// socket. Consumed by the Redis grant modules when their switches say
+		// "redis"; provided whenever this module is installed, as every slot
+		// here is, because a slot is cheap and the socket is the cost.
+		federationGrantStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.federationGrantStoreClient;
+		},
+		federationGrantIntentStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.federationGrantIntentStoreClient;
+		},
 		// #484: the replay seen-set behind private_key_jwt client assertions.
 		replaySeenSetClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
@@ -630,13 +656,26 @@ const SHARED_REDIS_TIMEOUTS = {
 // on PR #121). When `lifecycleRegistrar` is undefined (test scenarios
 // that don't seed it), each call creates a fresh client; tests are
 // isolated and don't need cross-slot sharing.
-const clientsCache = new WeakMap<LifecycleRegistrar, ReturnType<typeof makeIoredisClients>>();
+/**
+ * Every per-purpose client off the one socket: the general bundle, plus the
+ * two the federation-grant stores need (#593 slice 7). Those two have their
+ * own factories in the Redis package, so a Cluster deployment can give the
+ * grants a connection of their own; this template shares the socket, as it
+ * does for every other store.
+ */
+type StandaloneRedisClients = ReturnType<typeof makeIoredisClients> & {
+	readonly federationGrantStoreClient: ReturnType<typeof makeIoredisFederationGrantStoreClient>;
+	readonly federationGrantIntentStoreClient: ReturnType<
+		typeof makeIoredisFederationGrantIntentStoreClient
+	>;
+};
+const clientsCache = new WeakMap<LifecycleRegistrar, StandaloneRedisClients>();
 function getOrCreateClients(
 	config: AppConfig,
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
 	readinessRegistrar?: ReadinessRegistrar,
 	injectedLogger?: Logger,
-): ReturnType<typeof makeIoredisClients> {
+): StandaloneRedisClients {
 	const logger = injectedLogger ?? consoleLogger;
 	const cached = lifecycleRegistrar ? clientsCache.get(lifecycleRegistrar) : undefined;
 	if (cached) return cached;
@@ -676,7 +715,11 @@ function getOrCreateClients(
 	// The wrapper opens its own connections for refresh rotation
 	// (`refreshTokenFamilyClient.duplicate()`), which inherit no listeners from
 	// `io`; passing the logger lets those report through the same channel.
-	const clients = makeIoredisClients(io, { logger });
+	const clients: StandaloneRedisClients = {
+		...makeIoredisClients(io, { logger }),
+		federationGrantStoreClient: makeIoredisFederationGrantStoreClient(io),
+		federationGrantIntentStoreClient: makeIoredisFederationGrantIntentStoreClient(io),
+	};
 	if (lifecycleRegistrar) clientsCache.set(lifecycleRegistrar, clients);
 	return clients;
 }
@@ -703,6 +746,33 @@ function optionalString(
 	return { [field]: value };
 }
 
+/**
+ * An optional boolean from the `federations.google` slice. HOCON gives a
+ * boolean; an environment override (`${?VAR}`) gives the string, in the
+ * spellings core's `coerceBooleanFromEnv` accepts: "true" / "false" / "1" /
+ * "0", trimmed and in any case. One deliberate difference: that coercion reads
+ * an empty value as false, and this refuses it. HOCON substitutes an
+ * exported-but-empty variable as "", and for a security switch that must not
+ * quietly turn the check off. Anything else is refused too — a typo that
+ * silently reads as either value is worse than a boot failure.
+ */
+function optionalBoolean(
+	slice: Record<string, unknown>,
+	field: string,
+): Record<string, boolean> | Record<string, never> {
+	const value = slice[field];
+	if (value === undefined || value === null) return {};
+	if (typeof value === "boolean") return { [field]: value };
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true" || normalized === "1") return { [field]: true };
+		if (normalized === "false" || normalized === "0") return { [field]: false };
+	}
+	throw new Error(
+		`federations.google.${field} must be one of true, false, "true", "false", "1" or "0" when present`,
+	);
+}
+
 /**
  * Google federation config bridge — supplies the typed `googleFederationConfig`
  * ComponentMap slot from the `config.federations.google` slice.
@@ -769,6 +839,8 @@ export const googleFederationConfigModule: Module = defineModule({
 				...optionalString(slice, "sessionDomain"),
 				...optionalString(slice, "authCallbackUrl"),
 				...optionalString(slice, "clientUrl"),
+				// #597: absent means the provider's default, which is to require it.
+				...optionalBoolean(slice, "requireAuthorizationResponseIss"),
 			};
 		},
 	},

package/templates/standalone/src/shutdown.mts

@@ -61,10 +61,11 @@ import type { Logger } from "@o3co/auth-provider-core";
  *    reports through its callback, and treating that as success would tell an
  *    orchestrator the listener came down when it did not.
  *
- * Size `drainTimeoutMs` **below** the orchestrator's own kill grace period
- * (Kubernetes `terminationGracePeriodSeconds`, compose `stop_grace_period`,
- * both 30s by default) — the point is to close on our terms before SIGKILL
- * arrives on someone else's.
+ * Size `drainTimeoutMs` plus `cleanupTimeoutMs` **below** the orchestrator's
+ * own kill grace period (Kubernetes `terminationGracePeriodSeconds` is 30s by
+ * default, compose `stop_grace_period` 10s; with federation grants on the sum
+ * is 55s, so the grace is 60s or more) — the point is to close on our terms
+ * before SIGKILL arrives on someone else's.
  */
 export interface GracefulShutdownOptions {
 	readonly logger: Logger;
@@ -102,6 +103,71 @@ export function deferExit(code: number, exitProcess: (code: number) => void = pr
 const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
 
+/**
+ * The least cleanup allowance federation grants get (#593 slice 7): 45
+ * seconds. The package's background registry drains on dispose — it waits for
+ * a rotated upstream credential's write — and the longest tail one refresh
+ * can have is the upstream hard timeout, the persist budget and the wait for
+ * the grant's lock, back to back. With the shipped budgets (25 s + 3 s + 5 s)
+ * and {@link FEDERATION_GRANTS_CLEANUP_MARGIN_MS} that is exactly this floor;
+ * a deployment that raises a budget raises the allowance with it, below.
+ * The ten-second drain that cleanup would otherwise inherit is shorter than
+ * the tail, and a shutdown under it would abandon exactly the write the drain
+ * exists to wait for, after the IdP had moved on to the new refresh token.
+ *
+ * A host policy, not a grant setting: what it bounds is `handle.dispose()`,
+ * and the orchestrator's grace period has to cover the drain, this and an exit
+ * margin — the compose files ship 60 seconds for the shipped budgets, and an
+ * operator who raises a budget raises the grace to match.
+ */
+export const FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS = 45_000;
+
+/** What the allowance adds to the longest refresh tail: an exit margin. */
+export const FEDERATION_GRANTS_CLEANUP_MARGIN_MS = 12_000;
+
+/**
+ * The most a timer can be asked for: Node's `setTimeout` takes a 32-bit signed
+ * delay, and a larger one fires after ~1 ms instead. A sum of budgets an
+ * operator set high enough to reach it would otherwise turn the allowance
+ * into no allowance at all (Copilot, #614).
+ */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * The `cleanupTimeoutMs` to hand {@link installGracefulShutdown}, from the
+ * config: while the feature is on, the longer of the floor above and the
+ * configured refresh tail plus the margin; while it is off, nothing — the
+ * drain's own budget, as before. A fragment to spread, so an absent allowance
+ * is absent rather than `undefined`. A config that carries no budgets (one
+ * built by hand, without `reference.conf`) gets the floor.
+ */
+export function cleanupAllowanceFor(config: {
+	readonly federationGrants?:
+		| {
+				readonly enabled?: boolean | undefined;
+				readonly upstreamHardTimeoutMs?: number | undefined;
+				readonly persistRetryBudgetMs?: number | undefined;
+				readonly lockWaitMs?: number | undefined;
+		  }
+		| undefined;
+}): { readonly cleanupTimeoutMs: number } | Record<string, never> {
+	const grants = config.federationGrants;
+	if (grants?.enabled !== true) return {};
+	const budgets = [grants.upstreamHardTimeoutMs, grants.persistRetryBudgetMs, grants.lockWaitMs];
+	const tail = budgets.every((budget) => typeof budget === "number" && Number.isFinite(budget))
+		? (budgets as number[]).reduce(
+				(sum, budget) => sum + budget,
+				FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
+			)
+		: 0;
+	return {
+		cleanupTimeoutMs: Math.min(
+			Math.max(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS, tail),
+			MAX_TIMER_MS,
+		),
+	};
+}
+
 export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
 	const {
 		logger,

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

@@ -37,13 +37,24 @@
  * 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 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.
+ * 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.
  *
  * 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
@@ -160,8 +171,8 @@ function patch(proto: TestPrototype): void {
 		const protocol = app instanceof TlsServer ? "https" : "http";
 		let ready = binding.get(app);
 		if (!ready) {
-			// supertest closes `_server` after the response, as it does for the
-			// server it would have started itself.
+			// 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
@@ -188,6 +199,14 @@ function patch(proto: TestPrototype): void {
 		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;
+			}
 			fn?.(err, res);
 		};
 		// Unpatched, whatever `end` throws while building the request (a header

package/templates/versions.json

@@ -1,16 +1,17 @@
 {
-	"@o3co/auth-provider-core": "0.14.0",
-	"@o3co/auth-provider-device-grant": "0.14.0",
-	"@o3co/auth-provider-dpop": "0.14.0",
-	"@o3co/auth-provider-mtls": "0.14.0",
-	"@o3co/auth-provider-federation-apple": "0.14.0",
-	"@o3co/auth-provider-federation-google": "0.14.0",
-	"@o3co/auth-provider-federation-github": "0.14.0",
-	"@o3co/auth-provider-federation-oidc": "0.14.0",
-	"@o3co/auth-provider-oauth": "0.14.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.14.0",
-	"@o3co/auth-provider-session": "0.14.0",
-	"@o3co/auth-provider-foundation": "0.14.0",
-	"@o3co/auth-provider-redis": "0.14.0",
-	"@o3co/auth-provider-webauthn": "0.14.0"
+	"@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"
 }