@o3co/create-auth-provider 0.11.0 → 0.12.0

package/templates/standalone/src/modules.mts

@@ -38,7 +38,6 @@ import {
 } from "@o3co/auth-provider-core";
 import type { GoogleProviderConfig } from "@o3co/auth-provider-federation-google";
 import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
-import { redisFederationTokenStoreBuilder } from "@o3co/auth-provider-redis";
 import { makeIoredisClients } 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
@@ -155,6 +154,14 @@ export const repositoriesModule: Module = defineModule({
  */
 export const inMemoryCodeRepositoryModule: Module = defineModule({
 	name: "standalone:in-memory-code-repository",
+	// #455: the replica-safety guard reads this off the manifest. Before it
+	// did, this module booted under `deployment.mode = "multi"` — the guard
+	// keyed on core's module names and had never heard of this one.
+	replicaSafety: {
+		unsafe: true,
+		reason:
+			"authorization codes fork per replica — a code issued by the replica that served /authorize is unknown to the replica that receives the token request, so the exchange fails with invalid_grant everywhere but one replica, and a code redeemed on one replica can be redeemed again on another",
+	},
 	requires: ["config"] as const,
 	optional: ["lifecycleRegistrar"] as const,
 	provides: {
@@ -195,6 +202,15 @@ export const inMemoryCodeRepositoryModule: Module = defineModule({
  */
 export const inMemorySessionStoresModule: Module = defineModule({
 	name: "standalone:in-memory-session-stores",
+	// #455: the replica-safety guard reads this off the manifest. Before it
+	// did, `DEPLOYMENT_MODE=multi` with `USER_SESSION_STORES_ADAPTER=memory`
+	// booted — the guard keyed on core's `memorySessionStores`, and this
+	// module provides the same six slots under a name it had never heard of.
+	replicaSafety: {
+		unsafe: true,
+		reason:
+			"user sessions, RP registrations, family indexes and the subject-level revocation pair fork per replica — back-channel logout reaches only the replica that received it, so a logged-out session stays valid on the others, and a credential change enumerates and watermarks only the replica that handled it (#321)",
+	},
 	provides: {
 		userSessionStore: () => createInMemoryUserSessionStore(),
 		sessionRPRegistry: () => createInMemorySessionRPRegistry(),
@@ -218,27 +234,43 @@ export const inMemorySessionStoresModule: Module = defineModule({
 });
 
 /**
- * Federation token store module — always wired (independent of the
- * `userSessionStores.adapter` switch). Pre-Wave-5d this slot was bundled
- * into the larger `storesModule`; that meant the redis session-stores
- * branch dropped the federation-token-store provider entirely and boot
- * failed on the missing component (Copilot review on PR #121). Splitting
- * the slot out lets both adapters reuse it unchanged.
+ * In-memory federation token store module — wired by `buildModules` only
+ * when `federationTokenStore.type = "memory"` (the default). The redis
+ * branch swaps in `redisFederationTokenStoreModule` from
+ * `@o3co/auth-provider-redis` (mutually exclusive — both provide the same
+ * `federationTokenStore` slot), off the shared ioredis socket.
+ *
+ * Until #455 / #456 this was one module for both adapters
+ * (`standalone:federation-token-store`), choosing at runtime through the
+ * adapter factory. That shape failed twice over: the replica-safety guard
+ * could not tell the memory store from the Redis one by name, so
+ * `deployment.mode = "multi"` booted with the memory store; and the Redis
+ * branch handed the builder no client, so `federationTokenStore.type =
+ * "redis"` — documented in the README — was a boot failure rather than a
+ * Redis-backed store. One module per adapter, like the session stores.
+ *
+ * The slot is always wired, independent of the `userSessionStores.adapter`
+ * switch: pre-Wave-5d it was bundled into the larger `storesModule`, and the
+ * redis session-stores branch dropped the provider entirely (Copilot review
+ * on PR #121).
+ *
+ * The memory adapter still comes through core's factory, unchanged: that is
+ * where its "dev/test only" boot warning lives.
  */
-export const federationTokenStoreModule: Module = defineModule({
-	name: "standalone:federation-token-store",
-	requires: ["config"] as const,
+export const inMemoryFederationTokenStoreModule: Module = defineModule({
+	name: "standalone:in-memory-federation-token-store",
+	// #455: read by the replica-safety guard. Before the split this module
+	// carried one name for both adapters, so no name could have carried it.
+	replicaSafety: {
+		unsafe: true,
+		reason:
+			"upstream federation tokens fork per replica — a token stored by the replica that completed the federation callback is missing on the others, so a session cannot refresh its upstream token from another replica, and logout removes only the tokens the replica it lands on can see",
+	},
 	provides: {
-		federationTokenStore: async ({ config }) => {
+		federationTokenStore: async () => {
 			const factory = createFederationTokenStoreFactory();
 			registerBuiltinFederationTokenStores(factory);
-			factory.register("redis", redisFederationTokenStoreBuilder);
-			const slice = (
-				config as AppConfig & {
-					federationTokenStore?: { type: string } & Record<string, unknown>;
-				}
-			).federationTokenStore;
-			return factory.create(slice ? flattenAdapterConfig(slice) : { type: "memory" });
+			return factory.create({ type: "memory" });
 		},
 	},
 });
@@ -305,16 +337,24 @@ export const auditSinkModule: Module = defineModule({
 
 /**
  * @deprecated since Wave 5d (F4 PR2): split into `inMemorySessionStoresModule`
- * + `federationTokenStoreModule`. Re-exported for backward compatibility
- * with consumers that imported `storesModule` from this file. New code
- * should use the two split modules directly.
+ * + `inMemoryFederationTokenStoreModule`. Re-exported for backward
+ * compatibility with consumers that imported `storesModule` from this file.
+ * New code should use the two split modules directly.
  */
 export const storesModule: Module = defineModule({
 	name: "standalone:stores",
+	// #455: everything this bundle provides lives in process memory, so a
+	// composition still on it is refused under `deployment.mode = "multi"`
+	// like the split modules it stands in for.
+	replicaSafety: {
+		unsafe: true,
+		reason:
+			"user sessions, RP registrations, family indexes, the subject-level revocation pair and upstream federation tokens fork per replica — back-channel logout reaches only the replica that received it, so a logged-out session stays valid on the others",
+	},
 	requires: ["config"] as const,
 	provides: {
 		...inMemorySessionStoresModule.provides,
-		...federationTokenStoreModule.provides,
+		...inMemoryFederationTokenStoreModule.provides,
 	},
 });
 
@@ -445,6 +485,32 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.subjectRevocationClient;
 		},
+		// #433: the device-code store client, off the same shared socket.
+		// `redisDeviceCodeStoreModule` requires it. This template does not
+		// mount the device grant, so nothing in `buildModules` selects that
+		// module today; the slot is provided anyway, because a deployment that
+		// adds `deviceGrantModule` to this manifest and picks the Redis store
+		// must not hit the `missing-required-component` boot failure the
+		// subject-level slots above already paid for (#439) — a Redis-branch
+		// module whose client slot this module did not provide, caught only by
+		// the umbrella e2e.
+		deviceCodeStoreClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.deviceCodeStoreClient;
+		},
+		// #456: the federation-token-store client, off the same shared socket.
+		// `redisFederationTokenStoreModule` requires it, and nothing provided
+		// it — which is why the Redis branch of the federation store could not
+		// boot in this template while the README said it could.
+		federationTokenStoreClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.federationTokenStoreClient;
+		},
 	},
 });
 

package/templates/standalone/src/shutdown.mts

@@ -55,7 +55,8 @@ import type { Logger } from "@o3co/auth-provider-core";
  *    `0` cannot tell a clean drain from one that ran out of time.
  * 5. **`cleanup` runs after draining, before exit**, and its failure is logged
  *    through the app logger and reflected in the exit code. It never wedges the
- *    process: a dispose that throws still exits.
+ *    process: a dispose that throws still exits, and one that never settles is
+ *    cut off at `cleanupTimeoutMs`.
  * 6. **A `close` that fails is not reported as a clean drain.** `server.close`
  *    reports through its callback, and treating that as success would tell an
  *    orchestrator the listener came down when it did not.
@@ -71,7 +72,13 @@ export interface GracefulShutdownOptions {
 	readonly cleanup?: () => void | Promise<void>;
 	/** How long in-flight requests get before connections are cut. Default 10s. */
 	readonly drainTimeoutMs?: number;
-	/** Injected in tests; defaults to `process.exit`. */
+	/**
+	 * How long `cleanup` gets before the shutdown gives up on it. Defaults to
+	 * `drainTimeoutMs`, so the worst-case shutdown is the two budgets in
+	 * sequence — size both against the orchestrator's grace period, not one.
+	 */
+	readonly cleanupTimeoutMs?: number;
+	/** Injected in tests; defaults to {@link deferExit}. */
 	readonly exit?: (code: number) => void;
 	/** Injected in tests; defaults to `process.on`. */
 	readonly onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
@@ -79,6 +86,19 @@ export interface GracefulShutdownOptions {
 	readonly offSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
 }
 
+/**
+ * Exit after yielding the loop once.
+ *
+ * The scaffolded app logs NDJSON through pino, whose default destination is not
+ * synchronous, so calling `process.exit` in the same tick as the last
+ * `logger.error` can drop exactly the lines that say why the shutdown failed.
+ * One turn is a flush window, not a guarantee: a deployment that needs
+ * certainty should pass an `exit` that flushes its own transport first.
+ */
+export function deferExit(code: number, exitProcess: (code: number) => void = process.exit): void {
+	setImmediate(() => exitProcess(code));
+}
+
 const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
 
@@ -87,9 +107,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		logger,
 		cleanup,
 		drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
-		exit = (code: number): void => {
-			process.exit(code);
-		},
+		exit = deferExit,
 		onSignal = (signal, handler): void => {
 			process.on(signal, handler);
 		},
@@ -98,16 +116,54 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		},
 	} = options;
 
+	const cleanupTimeoutMs = options.cleanupTimeoutMs ?? drainTimeoutMs;
+
 	let shuttingDown = false;
 	let finished = false;
 
+	/** Sentinel so a timed-out cleanup is reported as that, not as a throw. */
+	const CLEANUP_TIMED_OUT = Symbol("cleanup-timed-out");
+
+	/**
+	 * Await `cleanup`, but not forever. `cleanup()` is invoked inside the async
+	 * wrapper so a synchronous throw lands in the same rejection path as an
+	 * async one.
+	 */
+	const runCleanup = async (): Promise<typeof CLEANUP_TIMED_OUT | undefined> => {
+		if (!cleanup) return;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		try {
+			return await Promise.race([
+				(async (): Promise<undefined> => {
+					await cleanup();
+					return undefined;
+				})(),
+				new Promise<typeof CLEANUP_TIMED_OUT>((resolve) => {
+					timer = setTimeout(() => resolve(CLEANUP_TIMED_OUT), cleanupTimeoutMs);
+					timer.unref?.();
+				}),
+			]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	};
+
 	/** Run `cleanup` and exit. Called by whichever of drain / deadline wins. */
 	const finish = async (code: number, reason: string): Promise<void> => {
 		if (finished) return;
 		finished = true;
 		let exitCode = code;
+		// `reason` names whatever decided the exit code, so the line an operator
+		// alerts on cannot say "drained" next to a non-zero code. The drain
+		// outcome keeps its own key rather than being overwritten — both facts
+		// are wanted, and a stable shape is what makes the line queryable.
+		let outcome = reason;
 		try {
-			await cleanup?.();
+			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
+				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
+				exitCode = 1;
+				outcome = "cleanup-timeout";
+			}
 		} catch (err) {
 			// Through the app logger, not `console.error`: a shutdown that
 			// failed to release its Redis connections is exactly the line an
@@ -115,8 +171,9 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 			// pipeline drops.
 			logger.error({ err }, "graceful shutdown: cleanup failed");
 			exitCode = 1;
+			outcome = "cleanup-failed";
 		}
-		logger.info({ reason, exitCode }, "graceful shutdown: complete");
+		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
 		exit(exitCode);
 	};
 

package/templates/versions.json

@@ -1,14 +1,15 @@
 {
-	"@o3co/auth-provider-core": "0.11.0",
-	"@o3co/auth-provider-device-grant": "0.11.0",
-	"@o3co/auth-provider-dpop": "0.11.0",
-	"@o3co/auth-provider-mtls": "0.11.0",
-	"@o3co/auth-provider-federation-google": "0.11.0",
-	"@o3co/auth-provider-federation-github": "0.11.0",
-	"@o3co/auth-provider-oauth": "0.11.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.11.0",
-	"@o3co/auth-provider-session": "0.11.0",
-	"@o3co/auth-provider-foundation": "0.11.0",
-	"@o3co/auth-provider-redis": "0.11.0",
-	"@o3co/auth-provider-webauthn": "0.11.0"
+	"@o3co/auth-provider-core": "0.12.0",
+	"@o3co/auth-provider-device-grant": "0.12.0",
+	"@o3co/auth-provider-dpop": "0.12.0",
+	"@o3co/auth-provider-mtls": "0.12.0",
+	"@o3co/auth-provider-federation-apple": "0.12.0",
+	"@o3co/auth-provider-federation-google": "0.12.0",
+	"@o3co/auth-provider-federation-github": "0.12.0",
+	"@o3co/auth-provider-oauth": "0.12.0",
+	"@o3co/auth-provider-oauth-token-exchange": "0.12.0",
+	"@o3co/auth-provider-session": "0.12.0",
+	"@o3co/auth-provider-foundation": "0.12.0",
+	"@o3co/auth-provider-redis": "0.12.0",
+	"@o3co/auth-provider-webauthn": "0.12.0"
 }