@o3co/create-auth-provider 0.10.0 → 0.12.0

package/templates/standalone/src/modules.mts

@@ -22,6 +22,8 @@ import {
 	createInMemorySessionFamilyIndex,
 	createInMemorySessionFederationIndex,
 	createInMemorySessionRPRegistry,
+	createInMemorySubjectRevocation,
+	createInMemorySubjectSessionIndex,
 	createInMemoryUserSessionStore,
 	createKeyStoreFactory,
 	createRepositoryFactories,
@@ -36,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
@@ -153,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: {
@@ -193,36 +202,75 @@ 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(),
 		sessionFamilyIndex: () => createInMemorySessionFamilyIndex(),
 		sessionFederationIndex: () => createInMemorySessionFederationIndex(),
+		// #406: the two subject-level revocation slots. They were missing here
+		// on both branches, so a scaffolded deployment got
+		// `subjectRevocation: undefined` — `verifyJwt` skipped the watermark,
+		// the #376 refresh gate was inert, and `revokeAllForSubject` reported
+		// `unavailable`. Nothing failed and nothing warned, which is what #406
+		// is about; the boot guard now refuses that state, and the scaffold's
+		// answer is to wire them rather than to declare the capability absent.
+		//
+		// Single-process only, like every other store on this branch. The
+		// redis branch swaps in `redisSessionStoresModule`, which has provided
+		// both since #321 — before that there was no distributed adapter to
+		// point at, which is why this gap outlived #296.
+		subjectSessionIndex: () => createInMemorySubjectSessionIndex(),
+		subjectRevocation: () => createInMemorySubjectRevocation(),
 	},
 });
 
 /**
- * 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" });
 		},
 	},
 });
@@ -289,25 +337,34 @@ 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,
 	},
 });
 
 /**
  * Shared ioredis clients module — opens ONE long-lived ioredis connection
- * per replica, wraps it via `makeIoredisClients()` (returns 11 typed
+ * per replica, wraps it via `makeIoredisClients()` (returns 13 typed
  * per-purpose clients), and exposes the slots consumed by the standalone's
  * Redis-backed adapters (refresh-token-family + 4 user-session stores +
- * rate limiter + code repository + access-token denylist).
+ * subject-level revocation index + watermark + rate limiter + code
+ * repository + access-token denylist).
  *
  * Per F4 PR1 (D-2 v2) + Wave 5d unification: the previous design opened a
  * separate ioredis socket per Redis-backed module (3+ sockets per replica).
@@ -407,6 +464,53 @@ export const standaloneRedisClientsModule: Module = defineModule({
 			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
 				.accessTokenDenylistClient;
 		},
+		// #321: the two subject-level revocation client slots, off the same
+		// shared socket. `redisSessionStoresModule` requires both — the index
+		// enumerates what a credential change cascades over and the watermark
+		// refuses what the cascade missed — so without them the scaffold's
+		// Redis branch had no provider for the slots and stage-1 boot refused
+		// the manifest with `missing-required-component`. Nothing in the
+		// standalone consumes these slots directly; they exist so the module
+		// that does can be selected.
+		subjectSessionIndexClient: async ({
+			config,
+			lifecycleRegistrar,
+			readinessRegistrar,
+			logger,
+		}) => {
+			return getOrCreateClients(config as AppConfig, lifecycleRegistrar, readinessRegistrar, logger)
+				.subjectSessionIndexClient;
+		},
+		subjectRevocationClient: async ({ config, lifecycleRegistrar, readinessRegistrar, logger }) => {
+			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

@@ -0,0 +1,219 @@
+/*
+ * 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 type { Server } from "node:http";
+import type { Logger } from "@o3co/auth-provider-core";
+
+/**
+ * Graceful shutdown for the scaffolded server (#290).
+ *
+ * ## Why this is in the template rather than a dependency
+ *
+ * It used to be `gracefulShutdown` from `@o3co/auth.utils@0.0.4`. The ops
+ * review's objection was not that the package is bad — it is that for the
+ * component which terminates every user session, "does SIGTERM wait for
+ * in-flight requests, and for how long?" has to be answerable from the code an
+ * operator deploys, and it was answerable only by reading a pre-1.0 package
+ * with no contract pinned here.
+ *
+ * Reading it answered the question, and the answer was the reason to move it:
+ * **there was no deadline**. `server.close()` waits for in-flight requests
+ * indefinitely, so a single stuck request meant the process never exited on
+ * its own and the orchestrator's SIGKILL took it down mid-flight — the
+ * opposite of a graceful shutdown, arriving only under the load that produces
+ * a stuck request. The cleanup-failure path also wrote to `console.error`, one
+ * bare line in a service whose every other line is NDJSON.
+ *
+ * Neither is fixed by documenting or pinning the dependency, which is why this
+ * is ~40 lines here with tests, rather than a version range and a README
+ * paragraph.
+ *
+ * ## The guarantees, stated
+ *
+ * 1. **SIGTERM and SIGINT** both start it; the second signal is ignored rather
+ *    than starting a second dispose over the first one's stores.
+ * 2. **New connections stop immediately** (`server.close`), and idle keep-alive
+ *    sockets are released (`closeIdleConnections`) — they hold the server open
+ *    with no request behind them, so a quiet server would otherwise wait out
+ *    the whole deadline for nothing.
+ * 3. **In-flight requests are given `drainTimeoutMs`** (default 10s) to finish.
+ * 4. **Past the deadline, remaining connections are cut** (`closeAllConnections`)
+ *    and the process exits **non-zero** — an orchestrator that only ever sees
+ *    `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, 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.
+ *
+ * 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.
+ */
+export interface GracefulShutdownOptions {
+	readonly logger: Logger;
+	/** Reverse-topological component cleanup — normally `handle.dispose()`. */
+	readonly cleanup?: () => void | Promise<void>;
+	/** How long in-flight requests get before connections are cut. Default 10s. */
+	readonly drainTimeoutMs?: number;
+	/**
+	 * 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;
+	/** Injected in tests; defaults to `process.removeListener`. */
+	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"];
+
+export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
+	const {
+		logger,
+		cleanup,
+		drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+		exit = deferExit,
+		onSignal = (signal, handler): void => {
+			process.on(signal, handler);
+		},
+		offSignal = (signal, handler): void => {
+			process.removeListener(signal, handler);
+		},
+	} = 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 {
+			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
+			// operator needs to find later, and a bare write is the one their
+			// pipeline drops.
+			logger.error({ err }, "graceful shutdown: cleanup failed");
+			exitCode = 1;
+			outcome = "cleanup-failed";
+		}
+		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
+		exit(exitCode);
+	};
+
+	const handler = (): void => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		for (const signal of SIGNALS) offSignal(signal, handler);
+		logger.info({ drainTimeoutMs }, "graceful shutdown: draining");
+
+		const deadline = setTimeout(() => {
+			logger.error(
+				{ drainTimeoutMs },
+				"graceful shutdown: drain deadline exceeded, closing remaining connections",
+			);
+			server.closeAllConnections();
+			void finish(1, "drain-timeout");
+		}, drainTimeoutMs);
+		// The deadline must not be what keeps the process alive once the drain
+		// has already finished.
+		deadline.unref?.();
+
+		server.close((err) => {
+			clearTimeout(deadline);
+			if (err) {
+				// `close` reports through its callback — "Server is not running"
+				// is the common one, but any listener teardown failure lands
+				// here. Reporting "drained" and exiting 0 on it would tell an
+				// orchestrator the shutdown went cleanly when the listener did
+				// not actually come down.
+				logger.error({ err }, "graceful shutdown: server close failed");
+				void finish(1, "close-failed");
+				return;
+			}
+			void finish(0, "drained");
+		});
+		// Idle keep-alive sockets have no request behind them, so nothing is
+		// lost by releasing them — and without this a quiet server waits out
+		// the whole deadline for connections that will never send anything.
+		server.closeIdleConnections();
+	};
+
+	for (const signal of SIGNALS) onSignal(signal, handler);
+}

package/templates/versions.json

@@ -1,13 +1,15 @@
 {
-	"@o3co/auth-provider-core": "0.10.0",
-	"@o3co/auth-provider-dpop": "0.10.0",
-	"@o3co/auth-provider-mtls": "0.10.0",
-	"@o3co/auth-provider-federation-google": "0.10.0",
-	"@o3co/auth-provider-federation-github": "0.10.0",
-	"@o3co/auth-provider-oauth": "0.10.0",
-	"@o3co/auth-provider-oauth-token-exchange": "0.10.0",
-	"@o3co/auth-provider-session": "0.10.0",
-	"@o3co/auth-provider-foundation": "0.10.0",
-	"@o3co/auth-provider-redis": "0.10.0",
-	"@o3co/auth-provider-webauthn": "0.10.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"
 }