@o3co/create-auth-provider 0.15.0 → 0.17.0-rc.1

package/templates/standalone/src/metrics.mts

@@ -20,23 +20,12 @@ import type { NextFunction, Request, RequestHandler, Response, Router } from "ex
 import { collectDefaultMetrics, Gauge, Histogram, Registry } from "prom-client";
 
 /**
- * Route label for a request.
- *
- * Express only fills `req.route` once a handler has matched, and the label has
- * to be **bounded**: labelling by `req.path` would mint a new time series per
- * distinct URL, and this server's paths carry opaque values (`/oauth/authorize`
- * query state, 404 probes from the internet). An unbounded label set is the
- * classic way to take Prometheus down with the thing that was supposed to
- * watch it. Unmatched requests collapse to a single `unmatched` bucket.
- */
-/**
- * Method label, bounded to the methods this server can actually serve.
- *
- * `req.method` is attacker-controlled: Node's HTTP parser accepts any valid
- * token, so `FOO` and `M000001` reach here as readily as `GET`. Each distinct
- * value would mint a fresh histogram child carrying every bucket — the same
- * unbounded-cardinality failure {@link routeLabel} guards against, one label
- * over, and reachable without any access to `/metrics` itself.
+ * Method label, bounded to the methods this server can serve. `req.method` is
+ * attacker-controlled (Node's HTTP parser accepts any valid token, so `FOO`
+ * reaches here as readily as `GET`), and each distinct value would mint a
+ * histogram child carrying every bucket: the unbounded cardinality
+ * {@link routeLabel} guards against, reachable without any access to
+ * `/metrics`.
  */
 const KNOWN_METHODS = new Set([
 	"GET",
@@ -54,6 +43,13 @@ function methodLabel(req: Request): string {
 	return KNOWN_METHODS.has(req.method) ? req.method : "other";
 }
 
+/**
+ * Route label for a request, which must be **bounded**: labelling by
+ * `req.path` would mint a time series per distinct URL, and this server's
+ * paths carry opaque values (`/oauth/authorize` query state, 404 probes from
+ * the internet). Express fills `req.route` only once a handler has matched;
+ * unmatched requests collapse to a single `unmatched` bucket.
+ */
 function routeLabel(req: Request): string {
 	const route = (req as Request & { route?: { path?: string } }).route?.path;
 	if (typeof route === "string" && route.length > 0) {
@@ -68,7 +64,7 @@ export interface MetricsRouteOptions {
 	 * up/down gauge. Pass `handle.readinessProbes`.
 	 */
 	readonly probes: readonly ReadinessProbe[];
-	/** Per-probe deadline, in milliseconds. Use `config.http.readinessTimeoutMs`. */
+	/** Per-probe deadline, in milliseconds. Use the `http` module's `readinessTimeoutMs`. */
 	readonly probeTimeoutMs: number;
 	/** Route path. Defaults to `/metrics`. */
 	readonly path?: string;
@@ -92,29 +88,11 @@ export interface Metrics {
 }
 
 /**
- * Prometheus metrics for the standalone provider.
- *
- * What this publishes is chosen from what an operator cannot otherwise see.
- * Before it, a degraded provider offered stderr lines and the load balancer's
- * 5xx graph — no way to distinguish "rate limiter is failing closed" from
- * "Redis-backed code repository is gone" without grepping container logs, and
- * no latency series to alert on at all.
- *
- * - `http_request_duration_seconds` — histogram by method, bounded route, and
- *   status. Carries request rate, error rate and latency in one series, which
- *   is the whole RED method.
- * - `auth_dependency_up` — 1/0 per readiness probe, sampled at scrape time.
- *   This is the series that separates "Redis is gone" from "the app is slow",
- *   and it reuses the probes the builders already registered rather than
- *   inventing a second notion of what this deployment depends on.
- * - Node process defaults (event-loop lag, heap, GC, handles) under the
- *   `auth_provider_` prefix.
- *
- * Deliberately not here yet: rate-limiter fail-closed counts and audit-sink
- * drops. Both happen inside `@o3co/auth-provider-core` and neither is
- * observable from the composition root today; counting them needs a metrics
- * hook in core (`BuilderContext` already reserves `metrics`) rather than
- * something this file can reach.
+ * Prometheus metrics for the standalone provider: the request-duration
+ * histogram (request rate, error rate and latency in one series),
+ * `auth_dependency_up` per readiness probe, sampled at scrape time, and Node
+ * process defaults under the `auth_provider_` prefix. What each answers, and
+ * what is not published yet, is in the template README, "Metrics".
  */
 export function createMetrics(): Metrics {
 	const registry = new Registry();
@@ -134,12 +112,11 @@ export function createMetrics(): Metrics {
 		const endTimer = requestDuration.startTimer();
 		let observed = false;
 		// Both terminal events, with a guard, rather than `finish` alone.
-		// `finish` covers every response the server completes — including ones
-		// produced by an error handler, and `req.route` is populated by then. But
-		// a client or proxy that disconnects mid-handler emits `close` WITHOUT
-		// `finish`, and those are disproportionately the slow and failing requests
-		// that RED metrics exist to surface; counting only `finish` would drop
-		// them from both the rate and the latency series.
+		// `finish` covers every response the server completes, an error
+		// handler's included, with `req.route` populated by then; but a client or
+		// proxy that disconnects mid-handler emits `close` WITHOUT `finish`, and
+		// those are disproportionately the slow and failing requests RED metrics
+		// exist to surface.
 		const observe = () => {
 			if (observed) return;
 			observed = true;

package/templates/standalone/src/mfaSwitch.mts

@@ -0,0 +1,262 @@
+/*
+ * 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 template's MFA switch, the composition root's own key `mfaMode`
+ * (`MFA_MODE`), `required` unless set otherwise: reading it before the
+ * modules are chosen, the modules it installs, and what it hands boot of the
+ * MFA module's section. Off installs nothing of MFA and hands boot nothing of
+ * it; on installs the MFA package's modules over the two MFA stores
+ * `adapters` selects.
+ *
+ * Refuses, each with a `RangeError` before boot that names the keys and
+ * variables and quotes no value of a mode, a timeout or a key:
+ * - a switch outside its three values, or a file's `mfaMode` that `MFA_MODE`
+ *   contradicts (`readMfaSwitch`);
+ * - an MFA store kept in memory with MFA on, unless every environment name
+ *   it reads says development or test (`mfaModulesFor`) — the first refusal a
+ *   deployment that sets nothing about MFA meets outside development, so it
+ *   also names what MFA needs there and `MFA_MODE=off`;
+ * - an `mfa.mode` the configuration writes that the switch does not say;
+ *   `MFA_ENCRYPTION_KEY` set beside a ring that holds the development sample
+ *   key in its place; and `mfa.storeTimeoutMs` below the user directory's
+ *   timeout where the Store is called (`mfaSectionForBoot`).
+ */
+
+import {
+	type Module,
+	memoryMfaFactorStoreModule,
+	memoryMfaTransactionStoreModule,
+	productionEnvironmentIn,
+	readEnvironmentName,
+} from "@o3co/auth-provider-core";
+import { foundationMfaFactorStoreModule } from "@o3co/auth-provider-foundation";
+import { MFA_DEVELOPMENT_SAMPLE_KEY, mfaModules, mfaResetModule } from "@o3co/auth-provider-mfa";
+import {
+	redisMfaFactorStoreModule,
+	redisMfaTransactionStoreModule,
+} from "@o3co/auth-provider-redis";
+import { loginCompletionModule } from "@o3co/auth-provider-session";
+import { type Adapters, isPlainSection, type MfaSwitch, mfaSwitchSchema } from "./sections.mjs";
+
+/** The composition root's MFA switch, a key of its own. No module may be named after it. */
+export const MFA_SWITCH = "mfaMode";
+
+/** The MFA module's section, which the switch decides. */
+const MFA_SECTION = "mfa";
+
+/** The `acr` the template advertises while MFA is on, met by a verified second factor. */
+const MFA_ACR = "urn:o3co:acr:mfa";
+
+/**
+ * `mfaMode` from `resolved` — the template's own layers over its
+ * `config/reference.conf` — parsed with the template's schema, under `env`,
+ * the environment the layers were substituted with. A value the schema
+ * refuses, or `MFA_MODE` set to other than what a file writes over it, is a
+ * `RangeError` naming `mfaMode` and `MFA_MODE`.
+ */
+export function readMfaSwitch(
+	resolved: Readonly<Record<string, unknown>>,
+	env: Readonly<Record<string, string>>,
+): MfaSwitch {
+	const result = mfaSwitchSchema.safeParse(resolved[MFA_SWITCH]);
+	if (!result.success) {
+		throw new RangeError(
+			`Config validation failed — ${MFA_SWITCH} (MFA_MODE): ${result.error.issues
+				.map((issue) => issue.message)
+				.join("; ")}`,
+			{ cause: result.error },
+		);
+	}
+	const variable = env.MFA_MODE;
+	if (variable !== undefined && variable !== result.data) {
+		throw new RangeError(
+			`MFA_MODE is set and differs from ${MFA_SWITCH}, which a configuration file writes over it: the file, not the variable, would decide whether MFA is installed. Remove ${MFA_SWITCH} from the file, or set MFA_MODE to what it says`,
+		);
+	}
+	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.
+ */
+function memoryRefusals(environment: string | undefined): string[] {
+	const named: [string, string][] =
+		environment === undefined ? [] : [["the environment", environment]];
+	for (const variable of ["CONFIG_ENV", "NODE_ENV"] as const) {
+		const value = process.env[variable];
+		if (readEnvironmentName(value) !== undefined) named.push([variable, value as string]);
+	}
+	if (named.length === 0) return ["no environment is named"];
+	return named.flatMap(([label, value]) => {
+		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`];
+	});
+}
+
+/**
+ * The modules the switch installs: none under `off`; otherwise the MFA
+ * package's (`mfaModules`, `mfaResetModule`), the session package's
+ * `loginCompletionModule`, and the two MFA stores `adapters` selects — on
+ * Redis, in the Store over `storeTransport` (the factors only), or in memory.
+ * A store in memory loses every factor, lock, hold and recorded email proof
+ * at a restart, after which whoever holds a password can bind a factor of
+ * their own: it is refused, naming each such setting and its variable,
+ * unless `environment`, and `CONFIG_ENV` and `NODE_ENV` where set, each say
+ * development or test. Under `core.deployment.mode = "multi"` core refuses
+ * the memory stores by name as well.
+ */
+export function mfaModulesFor(options: {
+	readonly mode: MfaSwitch;
+	readonly adapters: Pick<Adapters, "mfaFactorStore" | "mfaTransactionStore">;
+	readonly storeTransport: unknown;
+	readonly environment: string | undefined;
+}): Module[] {
+	if (options.mode === "off") return [];
+	const { adapters, environment } = options;
+	const inMemory = [
+		...(adapters.mfaFactorStore === "memory"
+			? ["adapters.mfaFactorStore (ADAPTERS_MFA_FACTOR_STORE)"]
+			: []),
+		...(adapters.mfaTransactionStore === "memory"
+			? ["adapters.mfaTransactionStore (ADAPTERS_MFA_TRANSACTION_STORE)"]
+			: []),
+	];
+	const reasons = inMemory.length === 0 ? [] : memoryRefusals(environment);
+	if (reasons.length > 0) {
+		throw new RangeError(
+			`MFA is on (${MFA_SWITCH}, MFA_MODE, which installs it unless set to off) and ${inMemory.join(" and ")} ${inMemory.length === 1 ? "is" : "are"} "memory", refused because ${reasons.join(" and ")}: a store in memory loses every factor, lock and recorded email proof at a restart, after which whoever holds a password can bind a factor of their own. Select "redis" (or, for the factors, "store"); memory is for development and test alone. Outside development MFA also needs MFA_ENCRYPTION_KEY, the SMTP relay (STANDARD_SMTP_MAIL_SENDER_HOST and STANDARD_SMTP_MAIL_SENDER_FROM) or your own mail sender, and an MFA page served at MFA_PAGE_URL. A deployment that wants no MFA sets MFA_MODE=off`,
+		);
+	}
+	return [
+		adapters.mfaFactorStore === "redis"
+			? redisMfaFactorStoreModule
+			: adapters.mfaFactorStore === "store"
+				? foundationMfaFactorStoreModule({ storeTransport: options.storeTransport })
+				: memoryMfaFactorStoreModule,
+		adapters.mfaTransactionStore === "redis"
+			? redisMfaTransactionStoreModule
+			: memoryMfaTransactionStoreModule,
+		...mfaModules(environment === undefined ? {} : { environment }),
+		mfaResetModule,
+		loginCompletionModule,
+	];
+}
+
+/** A whole number as configuration carries one: a number, or an environment variable's digits. */
+function wholeNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isInteger(value)) return value;
+	return typeof value === "string" && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+
+/** The value at `path` of `tree`, through sections of keys alone. */
+function valueAt(tree: unknown, path: readonly string[]): unknown {
+	let cursor: unknown = tree;
+	for (const key of path) {
+		if (!isPlainSection(cursor)) return undefined;
+		cursor = cursor[key];
+	}
+	return cursor;
+}
+
+/**
+ * What boot is handed of the `mfa` section under the switch `mode`;
+ * `undefined` hands none. None unless a loaded module owns it (`owned`):
+ * what the configuration writes there — `config/development.conf`'s key ring
+ * included — sets nothing while the switch installs no MFA. Owned, it is
+ * `resolved`'s section, with `mfa.mode` written from the switch when the
+ * switch installs MFA. Refuses (see the file header), whatever the switch, an
+ * `mfa.mode` the composition's own layers (`written`, their `mfa`) write that
+ * the switch does not say, or an `mfa` written as a value; with MFA on, a
+ * ring holding the development sample key while `MFA_ENCRYPTION_KEY` names
+ * another, and, where the Store is called (`storeCalled`), `mfa.storeTimeoutMs`
+ * below `repositories.user.http.timeout`.
+ */
+export function mfaSectionForBoot(options: {
+	readonly mode: MfaSwitch;
+	readonly written: unknown;
+	readonly resolved: Readonly<Record<string, unknown>>;
+	readonly owned: boolean;
+	readonly storeCalled: boolean;
+	readonly env: Readonly<Record<string, string>>;
+}): unknown {
+	const { mode, written, resolved } = options;
+	if (written !== undefined && !isPlainSection(written)) {
+		throw new RangeError(
+			`mfa is written as a value in the configuration; it is the MFA package's section, and ${MFA_SWITCH} (MFA_MODE) decides whether the template installs MFA. Remove mfa, and set MFA_MODE or ${MFA_SWITCH}`,
+		);
+	}
+	const writtenMode = written === undefined ? undefined : written.mode;
+	if (writtenMode !== undefined && writtenMode !== mode) {
+		throw new RangeError(
+			`mfa.mode is written in the configuration and differs from ${MFA_SWITCH} (MFA_MODE), which decides whether the template installs MFA and writes mfa.mode from it. Set MFA_MODE or ${MFA_SWITCH}, and remove mfa.mode`,
+		);
+	}
+	if (!options.owned) return undefined;
+	const section = resolved[MFA_SECTION];
+	if (mode === "off" || !isPlainSection(section)) return section;
+	// Exported but blank names no key.
+	const variableKey = options.env.MFA_ENCRYPTION_KEY?.trim() ?? "";
+	const ring = Array.isArray(section.encryptionKeys) ? section.encryptionKeys : [];
+	if (
+		variableKey !== "" &&
+		variableKey !== MFA_DEVELOPMENT_SAMPLE_KEY &&
+		ring.some((entry) => valueAt(entry, ["key"]) === MFA_DEVELOPMENT_SAMPLE_KEY)
+	) {
+		throw new RangeError(
+			"MFA_ENCRYPTION_KEY is set, and mfa.encryptionKeys holds the development sample key in its place: a ring a configuration file writes (config/development.conf's) wins over the variable, so the key you set would seal nothing. Write your key in place of the sample key in that ring, or unset MFA_ENCRYPTION_KEY",
+		);
+	}
+	const storeTimeout = wholeNumber(section.storeTimeoutMs);
+	const userTimeout = wholeNumber(valueAt(resolved, ["repositories", "user", "http", "timeout"]));
+	if (
+		options.storeCalled &&
+		storeTimeout !== undefined &&
+		userTimeout !== undefined &&
+		storeTimeout < userTimeout
+	) {
+		throw new RangeError(
+			"mfa.storeTimeoutMs (MFA_STORE_TIMEOUT_MS) is below repositories.user.http.timeout (REPOSITORIES_USER_HTTP_TIMEOUT): one MFA Store call's time must cover the Store's own per-call timeout, or a factor-set write's lease can lapse while a Store call is still running. Raise MFA_STORE_TIMEOUT_MS to at least the user directory's timeout",
+		);
+	}
+	return { ...section, mode };
+}
+
+/**
+ * `oauth` with `urn:o3co:acr:mfa = ["mfa"]` added to its `acr` table while
+ * the switch installs MFA, unless the configuration writes that entry
+ * itself; as it is otherwise, so a composition without MFA advertises
+ * exactly what it would without the switch.
+ */
+export function oauthForBoot(mode: MfaSwitch, oauth: unknown): unknown {
+	if (mode === "off" || !isPlainSection(oauth)) return oauth;
+	const authorize = oauth.authorize ?? {};
+	const acrValues = isPlainSection(authorize) ? (authorize.acrValues ?? {}) : undefined;
+	// A shape the oauth module's schema refuses is left for it to name.
+	if (!isPlainSection(authorize) || !isPlainSection(acrValues)) return oauth;
+	if (Object.hasOwn(acrValues, MFA_ACR)) return oauth;
+	return {
+		...oauth,
+		authorize: { ...authorize, acrValues: { ...acrValues, [MFA_ACR]: ["mfa"] } },
+	};
+}