@o3co/create-auth-provider 0.17.0-rc.2 → 0.17.0-rc.3

package/templates/standalone/src/__tests__/startup-log-lines.test.mts

@@ -0,0 +1,148 @@
+/*
+ * 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.
+ */
+
+/**
+ * What the template writes while it starts: `src/app.mts` in a process of its
+ * own, in development on the memory stores, until it listens and then until
+ * it has shut down. Every line on stdout and on stderr is one JSON object from
+ * the structured logger — a warning a store gives at boot included.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import { generateKeyPairSync } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const templateRoot = fileURLToPath(new URL("../..", import.meta.url));
+const tsxCli = createRequire(import.meta.url).resolve("tsx/cli");
+
+const keyPair = generateKeyPairSync("ed25519", {
+	publicKeyEncoding: { type: "spki", format: "pem" },
+	privateKeyEncoding: { type: "pkcs8", format: "pem" },
+});
+
+/** An empty client registry: a scaffolded project's clone has no `config/clients.yaml`. */
+const clientsFile = (() => {
+	const file = join(mkdtempSync(join(tmpdir(), "startup-log-lines-")), "clients.yaml");
+	writeFileSync(file, "");
+	return file;
+})();
+
+/**
+ * Development, with every store the `adapters` section selects in memory.
+ * The refresh-token family store has no memory choice in the template; its
+ * shared Redis socket points at a port nothing answers, so the run reaches no
+ * real server. Nothing is inherited from the test runner's environment but
+ * PATH, so its NODE_ENV and LOGGING_LEVEL do not reach the child.
+ */
+const ENV: Readonly<Record<string, string>> = {
+	PATH: process.env.PATH ?? "",
+	CONFIG_ENV: "development",
+	NODE_ENV: "development",
+	LOGGING_LEVEL: "info",
+	HTTP_PORT: "0",
+	OAUTH_JWT_ISSUER: "http://localhost:3000",
+	KEY_STORE_LOCAL_PRIVATE_KEY: keyPair.privateKey,
+	KEY_STORE_LOCAL_PUBLIC_KEY: keyPair.publicKey,
+	SESSION_STORE_SECRET: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+	SESSION_STORE_SECURE: "false",
+	SESSION_STORE_NAME: "auth.sid",
+	SESSION_STORE_STORAGE_TYPE: "memory",
+	ADAPTERS_RATE_LIMITER: "memory",
+	ADAPTERS_ATTEMPT_COUNTER: "memory",
+	ADAPTERS_USER_SESSION_STORES: "memory",
+	ADAPTERS_ACCESS_TOKEN_DENYLIST: "memory",
+	ADAPTERS_REPLAY_SEEN_SET: "memory",
+	ADAPTERS_CODE_REPOSITORY: "memory",
+	ADAPTERS_FEDERATION_TOKEN_STORE: "memory",
+	ADAPTERS_MFA_FACTOR_STORE: "memory",
+	ADAPTERS_MFA_TRANSACTION_STORE: "memory",
+	REDIS_CLIENTS_URL: "redis://127.0.0.1:9",
+	REPOSITORIES_CLIENT_YAML_PATH: clientsFile,
+	REPOSITORIES_USER_HTTP_AUTHENTICATE_URL: "http://127.0.0.1:9/authenticate",
+	REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL: "http://127.0.0.1:9/authenticate-by-token",
+};
+
+interface Run {
+	readonly stdout: string;
+	readonly stderr: string;
+	readonly listened: boolean;
+}
+
+/** Starts the template, stops it once it listens (or gives up), and returns what it wrote. */
+function startAndStop(timeoutMs: number): Promise<Run> {
+	return new Promise((resolve, reject) => {
+		const child: ChildProcess = spawn(process.execPath, [tsxCli, "src/app.mts"], {
+			cwd: templateRoot,
+			env: ENV,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		let listened = false;
+		const stop = (): void => {
+			if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+		};
+		const deadline = setTimeout(stop, timeoutMs);
+		child.stdout?.setEncoding("utf8").on("data", (chunk: string) => {
+			stdout += chunk;
+			if (!listened && stdout.includes('"msg":"server_listening"')) {
+				listened = true;
+				stop();
+			}
+		});
+		child.stderr?.setEncoding("utf8").on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		child.on("error", (err) => {
+			clearTimeout(deadline);
+			reject(err);
+		});
+		child.on("close", () => {
+			clearTimeout(deadline);
+			resolve({ stdout, stderr, listened });
+		});
+	});
+}
+
+/** Each line of `text` that is not one JSON object. */
+function linesThatAreNotJsonObjects(text: string): string[] {
+	return text
+		.split("\n")
+		.filter((line) => line.trim() !== "")
+		.filter((line) => {
+			try {
+				const parsed: unknown = JSON.parse(line);
+				return typeof parsed !== "object" || parsed === null || Array.isArray(parsed);
+			} catch {
+				return true;
+			}
+		});
+}
+
+describe("the template's startup output", () => {
+	it("is one JSON object per line on stdout and stderr, in development on the memory stores", async () => {
+		const run = await startAndStop(15_000);
+
+		expect(run.listened, `the template did not listen; stderr:\n${run.stderr}`).toBe(true);
+		expect(linesThatAreNotJsonObjects(run.stdout)).toEqual([]);
+		expect(linesThatAreNotJsonObjects(run.stderr)).toEqual([]);
+	}, 30_000);
+});

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

@@ -29,6 +29,7 @@ import {
 	type Switches,
 } from "../configPath.mjs";
 import { templateReference } from "../modules.mjs";
+import { configuredMfaMode } from "./configured-mfa-mode.fixture.mjs";
 import { type BothPhases, withSwitches } from "./library-references.fixture.mjs";
 
 // config/ is two levels above this test file:
@@ -109,15 +110,18 @@ describe("three-tier HOCON resolution (env → application.conf → reference.co
 		expect(grants(config).authorizationCode?.enabled).toBe("false");
 	});
 
-	it("reads the MFA switch, mfaMode, as required where MFA_MODE is unset, and installs no MFA module under MFA_MODE=off", () => {
-		// The template's reference.conf ships the switch required and binds MFA_MODE.
+	it("reads the MFA switch, mfaMode, as the files write it where MFA_MODE is unset, and installs no MFA module under MFA_MODE=off", () => {
+		// The template's reference.conf ships the switch required and binds
+		// MFA_MODE; a project's application.conf may write it over that.
 		const mfaNames = (config: Switches) =>
 			buildModules(config)
 				.map((m) => m.name)
 				.filter((name) => /mfa/i.test(name));
 		const shipped = buildResolvedConfig("development");
-		expect(shipped.mfaMode).toBe("required");
-		expect(mfaNames(shipped)).toContain("mfa");
+		const configured = configuredMfaMode("development");
+		expect(shipped.mfaMode).toBe(configured);
+		if (configured === "off") expect(mfaNames(shipped)).toEqual([]);
+		else expect(mfaNames(shipped)).toContain("mfa");
 		const off = buildResolvedConfig("development", { MFA_MODE: "off" });
 		expect(off.mfaMode).toBe("off");
 		expect(mfaNames(off)).toEqual([]);

package/templates/standalone/src/__tests__/two-phase-config.test.mts

@@ -69,6 +69,7 @@ import {
 	type Switches,
 } from "../configPath.mjs";
 import { MFA_SWITCH } from "../mfaSwitch.mjs";
+import { configuredMfaMode } from "./configured-mfa-mode.fixture.mjs";
 
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
@@ -270,7 +271,7 @@ describe("phase one reads federation-grants.enabled as the federation-grants mod
 	it("reads the MFA switch as its own mfaMode, as the environment sets it, and no key of the MFA module's", () => {
 		for (const [name, env] of Object.entries(ENVIRONMENTS)) {
 			const switches = readSwitches(readOwnLayers(ownFiles("production"), { env }));
-			expect(switches.mfaMode, name).toBe(env.MFA_MODE ?? "required");
+			expect(switches.mfaMode, name).toBe(env.MFA_MODE ?? configuredMfaMode("production"));
 			expect(switches, name).not.toHaveProperty("mfa");
 		}
 	});

package/templates/standalone/src/adapters.mts

@@ -21,7 +21,7 @@
  * moved from, and the variables renamed with them, are refused here, before
  * any module is chosen, in the words and under the reasons boot refuses a
  * module's with (`config-path-relocated`, `environment-variable-renamed`): a
- * renamed variable set alone, or beside its new name at a different value, is
+ * renamed variable set, alone or beside its new name at any value, is
  * refused, naming the variables and never a value.
  */
 
@@ -128,7 +128,7 @@ export function readAdapters(
 			`Configuration sets ${moved.length} path(s) that moved: ${moved
 				.map(
 					({ from, to, environmentVariable }) =>
-						`${from} has moved to ${to}; see CHANGELOG. Write it there (environment variable ${environmentVariable}) and remove this field from your config (or unset the environment variable that sets it).`,
+						`${from} has moved to ${to}; see the upgrade guide (docs/upgrading-from-v0.16.0.md). Write it there (environment variable ${environmentVariable}) and remove this field from your config (or unset the environment variable that sets it).`,
 				)
 				.join(" ")}`,
 			moved,

package/templates/standalone/src/mfaSwitch.mts

@@ -38,6 +38,7 @@
  */
 
 import {
+	isDevelopmentEnvironment,
 	type Module,
 	memoryMfaFactorStoreModule,
 	memoryMfaTransactionStoreModule,
@@ -96,13 +97,11 @@ export function readMfaSwitch(
 	return result.data;
 }
 
-/** The names the memory MFA stores are let in under. */
-const DEVELOPMENT_NAMES: ReadonlySet<string> = new Set(["development", "test"]);
-
 /**
  * Why the MFA stores may not be kept in memory under `environment` and
- * `CONFIG_ENV` and `NODE_ENV` wherever they are set: each name that is not
- * development or test, or that nothing is named. None lifts another's.
+ * `CONFIG_ENV` and `NODE_ENV` wherever they are set, as core's
+ * `isDevelopmentEnvironment` reads them: each name that is not development
+ * or test, or that nothing is named. None lifts another's.
  */
 function memoryRefusals(environment: string | undefined): string[] {
 	const named: [string, string][] =
@@ -113,10 +112,10 @@ function memoryRefusals(environment: string | undefined): string[] {
 	}
 	if (named.length === 0) return ["no environment is named"];
 	return named.flatMap(([label, value]) => {
+		if (isDevelopmentEnvironment([value])) return [];
 		const production = productionEnvironmentIn([value]);
 		if (production !== undefined) return [`${label} is "${production}"`];
-		const name = readEnvironmentName(value) ?? "";
-		return DEVELOPMENT_NAMES.has(name) ? [] : [`${label} "${name}" is not development or test`];
+		return [`${label} "${readEnvironmentName(value)}" is not development or test`];
 	});
 }
 

package/templates/standalone/src/modules.mts

@@ -338,7 +338,7 @@ export const inMemorySessionStoresModule: Module = defineModule({
  * the `adapters.userSessionStores` selection.
  *
  * The memory adapter comes through core's factory: that is where its
- * "dev/test only" boot warning lives.
+ * "dev/test only" boot warning lives, said on the composition's `logger`.
  */
 export const inMemoryFederationTokenStoreModule: Module = defineModule({
 	name: "standalone-in-memory-federation-token-store",
@@ -347,10 +347,11 @@ export const inMemoryFederationTokenStoreModule: Module = defineModule({
 		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",
 	},
+	optional: ["logger"] as const,
 	provides: {
-		federationTokenStore: async () => {
+		federationTokenStore: async ({ logger }) => {
 			const factory = createFederationTokenStoreFactory();
-			registerBuiltinFederationTokenStores(factory);
+			registerBuiltinFederationTokenStores(factory, logger);
 			return factory.create({ type: "memory" });
 		},
 	},
@@ -408,7 +409,8 @@ export function auditSinkModuleFor(sink: string): Module {
  * `redis-clients`, which moved from `refreshTokenFamilyStore.redis` with its
  * variables (`REDIS_CLIENTS_*`). Per-store Redis instances belong in a
  * custom composition root. An empty URL throws rather than falling back to
- * localhost. `io.quit()` is registered once with `lifecycleRegistrar`, so
+ * localhost. `assumeNoEviction` is handed to every client, for the Redis
+ * stores' eviction gate. `io.quit()` is registered once with `lifecycleRegistrar`, so
  * `handle.dispose()` closes the connection.
  *
  * `buildModules` adds this module only when some composed module needs a
@@ -639,7 +641,11 @@ type StandaloneRedisClients = ReturnType<typeof makeIoredisClients> & {
 // registrar (tests that seed none), each call creates a fresh client.
 const clientsCache = new WeakMap<LifecycleRegistrar, StandaloneRedisClients>();
 function getOrCreateClients(
-	section: { readonly url: string; readonly password?: string | undefined },
+	section: {
+		readonly url: string;
+		readonly password?: string | undefined;
+		readonly assumeNoEviction: boolean;
+	},
 	lifecycleRegistrar: LifecycleRegistrar | undefined,
 	readinessRegistrar?: ReadinessRegistrar,
 	injectedLogger?: Logger,
@@ -684,7 +690,7 @@ function getOrCreateClients(
 	// (`refreshTokenFamilyClient.duplicate()`), which inherit no listeners from
 	// `io`; passing the logger lets those report through the same channel.
 	const clients: StandaloneRedisClients = {
-		...makeIoredisClients(io, { logger }),
+		...makeIoredisClients(io, { logger, assumeNoEviction: section.assumeNoEviction }),
 		federationGrantStoreClient: makeIoredisFederationGrantStoreClient(io),
 		federationGrantIntentStoreClient: makeIoredisFederationGrantIntentStoreClient(io),
 	};

package/templates/standalone/src/rootRenames.mts

@@ -17,12 +17,12 @@
 /**
  * The variables renamed with a path of the composition root's own layers,
  * which no module declares: the adapter selections and the federations the
- * template ships. Phase one refuses an old name set alone, or beside its new
- * name at a different value, before any module is chosen, as boot refuses a
- * variable a module declares renamed (`environment-variable-renamed`); the
- * two at one value are accepted. Boot's own check cannot hold these: an
- * adapter selection decides which modules are chosen before boot, and a
- * federation's key sits in core's section, whose renames core alone declares.
+ * template ships. Phase one refuses an old name set, alone or beside its new
+ * name at any value, before any module is chosen, as boot refuses a
+ * variable a module declares renamed (`environment-variable-renamed`).
+ * Boot's own check cannot hold these: an adapter selection decides which
+ * modules are chosen before boot, and a federation's key sits in core's
+ * section, whose renames core alone declares.
  */
 
 import { variablesRenamed } from "./bootRefusal.mjs";
@@ -41,9 +41,9 @@ export interface RootRename {
 
 /**
  * Refuses, with an `environment-variable-renamed` `BootError`, an old name in
- * `env` set alone (`unset`), or beside its new name at a different value
- * (`different`); the two at one value are accepted. Every such rename is
- * named at once; no value is quoted or carried.
+ * `env` set alone (`unset`), or beside its new name (`different`, whatever
+ * either holds), in the words core refuses a module's rename in. Every such
+ * rename is named at once; no value is compared, quoted or carried.
  */
 export function refuseRenamedVariables(
 	env: Readonly<Record<string, string>>,
@@ -51,18 +51,17 @@ export function refuseRenamedVariables(
 ): void {
 	const refused = renames.flatMap((rename) => {
 		const { from, to } = rename;
-		const old = env[from];
-		if (old === undefined || env[to] === old) return [];
+		if (env[from] === undefined) return [];
 		return [
 			{ ...rename, state: env[to] === undefined ? ("unset" as const) : ("different" as const) },
 		];
 	});
 	if (refused.length === 0) return;
 	const named = refused.map(({ from, to, path, state }) => {
-		const renamed = `${from} was renamed ${to}, the variable ${path} is bound to; see CHANGELOG.`;
+		const renamed = `${from} was renamed ${to}, the variable ${path} is bound to; see the upgrade guide (docs/upgrading-from-v0.16.0.md).`;
 		return state === "unset"
 			? `${renamed} Set ${to} instead and unset ${from}.`
-			: `${renamed} ${to} is set to a different value: keep the one you mean in ${to} and unset ${from}.`;
+			: `${renamed} ${to} is set as well: keep the value you mean in ${to} and unset ${from}.`;
 	});
 	throw variablesRenamed(
 		`The environment sets ${refused.length} variable(s) that were renamed: ${named.join(" ")}`,

package/templates/standalone/src/sections.mts

@@ -29,6 +29,7 @@
 import {
 	checkSerializedOrigin,
 	checkTrustedProxyEntry,
+	coerceBooleanFromEnv,
 	describeSerializedOriginRejection,
 	describeTrustedProxyEntryRejection,
 	isWellFormedKid,
@@ -239,9 +240,18 @@ export const keyStoreSectionSchema = z
 	})
 	.strict();
 
-/** `redis-clients`: the one Redis connection every Redis-backed store shares. */
+/**
+ * `redis-clients`: the one Redis connection every Redis-backed store shares.
+ * `assumeNoEviction` is the operator's assertion that the server runs
+ * `maxmemory-policy noeviction`, read by the Redis stores' eviction gate only
+ * where the server will not report its policy.
+ */
 export const redisClientsSectionSchema = z
-	.object({ url: z.string(), password: z.string().optional() })
+	.object({
+		url: z.string(),
+		password: z.string().optional(),
+		assumeNoEviction: coerceBooleanFromEnv.default(false),
+	})
 	.strict();
 
 /**

package/templates/versions.json

@@ -1,20 +1,20 @@
 {
-	"@o3co/auth-provider-core": "0.17.0-rc.2",
-	"@o3co/auth-provider-device-grant": "0.17.0-rc.2",
-	"@o3co/auth-provider-dpop": "0.17.0-rc.2",
-	"@o3co/auth-provider-mtls": "0.17.0-rc.2",
-	"@o3co/auth-provider-federation-apple": "0.17.0-rc.2",
-	"@o3co/auth-provider-federation-google": "0.17.0-rc.2",
-	"@o3co/auth-provider-federation-github": "0.17.0-rc.2",
-	"@o3co/auth-provider-federation-grants": "0.17.0-rc.2",
-	"@o3co/auth-provider-federation-oidc": "0.17.0-rc.2",
-	"@o3co/auth-provider-oauth": "0.17.0-rc.2",
-	"@o3co/auth-provider-oauth-token-exchange": "0.17.0-rc.2",
-	"@o3co/auth-provider-session": "0.17.0-rc.2",
-	"@o3co/auth-provider-foundation": "0.17.0-rc.2",
-	"@o3co/auth-provider-mfa": "0.17.0-rc.2",
-	"@o3co/auth-provider-redis": "0.17.0-rc.2",
-	"@o3co/auth-provider-standard": "0.17.0-rc.2",
-	"@o3co/auth-provider-test-kit": "0.17.0-rc.2",
-	"@o3co/auth-provider-webauthn": "0.17.0-rc.2"
+	"@o3co/auth-provider-core": "0.17.0-rc.3",
+	"@o3co/auth-provider-device-grant": "0.17.0-rc.3",
+	"@o3co/auth-provider-dpop": "0.17.0-rc.3",
+	"@o3co/auth-provider-mtls": "0.17.0-rc.3",
+	"@o3co/auth-provider-federation-apple": "0.17.0-rc.3",
+	"@o3co/auth-provider-federation-google": "0.17.0-rc.3",
+	"@o3co/auth-provider-federation-github": "0.17.0-rc.3",
+	"@o3co/auth-provider-federation-grants": "0.17.0-rc.3",
+	"@o3co/auth-provider-federation-oidc": "0.17.0-rc.3",
+	"@o3co/auth-provider-oauth": "0.17.0-rc.3",
+	"@o3co/auth-provider-oauth-token-exchange": "0.17.0-rc.3",
+	"@o3co/auth-provider-session": "0.17.0-rc.3",
+	"@o3co/auth-provider-foundation": "0.17.0-rc.3",
+	"@o3co/auth-provider-mfa": "0.17.0-rc.3",
+	"@o3co/auth-provider-redis": "0.17.0-rc.3",
+	"@o3co/auth-provider-standard": "0.17.0-rc.3",
+	"@o3co/auth-provider-test-kit": "0.17.0-rc.3",
+	"@o3co/auth-provider-webauthn": "0.17.0-rc.3"
 }