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

package/templates/standalone/src/rootRenames.mts

@@ -0,0 +1,79 @@
+/*
+ * 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 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; the two at one
+ * value are accepted.
+ */
+
+/** A variable renamed with a path of the composition root's own: its old name, its new one, and the path the new one binds. */
+export interface RootRename {
+	readonly from: string;
+	readonly to: string;
+	readonly path: string;
+}
+
+/**
+ * Refuses, with a `RangeError`, an old name in `env` set alone, or beside its
+ * new name at a different value; the two at one value are accepted. Every
+ * such rename is named at once; no value is quoted.
+ */
+export function refuseRenamedVariables(
+	env: Readonly<Record<string, string>>,
+	renames: readonly RootRename[],
+): void {
+	const refused = renames.flatMap(({ from, to, path }) => {
+		const old = env[from];
+		if (old === undefined || env[to] === old) return [];
+		const renamed = `${from} was renamed ${to}, the variable ${path} is bound to; see CHANGELOG.`;
+		return env[to] === undefined
+			? [`${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}.`,
+				];
+	});
+	if (refused.length > 0) {
+		throw new RangeError(
+			`The environment sets ${refused.length} variable(s) that were renamed: ${refused.join(" ")}`,
+		);
+	}
+}
+
+/**
+ * The variables `config/application.conf` binds for the two federations the
+ * template ships, each renamed after its path under `core.federations`.
+ */
+export const SHIPPED_FEDERATION_RENAMES: readonly RootRename[] = (
+	[
+		["GOOGLE", "google", ["ENABLED", "enabled"]],
+		["GOOGLE", "google", ["CLIENT_ID", "clientId"]],
+		["GOOGLE", "google", ["CLIENT_SECRET", "clientSecret"]],
+		["GOOGLE", "google", ["CALLBACK_URL", "callbackURL"]],
+		["GOOGLE", "google", ["ACCESS_TYPE", "accessType"]],
+		["OIDC", "oidc", ["ENABLED", "enabled"]],
+		["OIDC", "oidc", ["ISSUER", "issuer"]],
+		["OIDC", "oidc", ["CLIENT_ID", "clientId"]],
+		["OIDC", "oidc", ["CLIENT_SECRET", "clientSecret"]],
+		["OIDC", "oidc", ["CALLBACK_URL", "callbackURL"]],
+	] as const
+).map(([federation, name, [key, path]]) => ({
+	from: `FEDERATIONS_${federation}_${key}`,
+	to: `CORE_FEDERATIONS_${federation}_${key}`,
+	path: `core.federations.${name}.${path}`,
+}));

package/templates/standalone/src/routes.mts

@@ -0,0 +1,89 @@
+/*
+ * 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 host's routes, in the order `app.mts` mounts them: liveness, readiness
+ * and the metrics scrape ahead of the composed auth router, so they keep
+ * answering while the auth pipeline is degraded (which is when an operator
+ * needs them); then that router; then core's terminal error handler, last,
+ * because Express hands an error only to handlers mounted after the route
+ * that raised it. A function rather than inline in `app.mts`, so the order
+ * and the handler can be tested as the process mounts them.
+ *
+ * The handler is core's `terminalErrorHandler`, the one that already ends the
+ * composed router, so an error a host route lets through is answered as every
+ * other route's is (see core's `middleware/terminalError.mts`).
+ */
+
+import {
+	createHealthcheckRouter,
+	createReadinessRouter,
+	type Logger,
+	type ReadinessProbe,
+	terminalErrorHandler,
+} from "@o3co/auth-provider-core";
+import express, { type Express, type Router } from "express";
+import type { Metrics } from "./metrics.mjs";
+
+export interface MountRoutesOptions {
+	/** The router `createApp` composed (`handle.router`). */
+	readonly router: Router;
+	/** The readiness probes the builders registered (`handle.readinessProbes`). */
+	readonly probes: readonly ReadinessProbe[];
+	/** Per-probe deadline, in milliseconds: the `http` module's `readinessTimeoutMs`. */
+	readonly readinessTimeoutMs: number;
+	readonly metrics: Metrics;
+	readonly logger: Logger;
+}
+
+/** Mount the host's routes, the composed router and the terminal error handler on `app`. */
+export function mountRoutes(app: Express, options: MountRoutesOptions): void {
+	// Liveness: the process is up and its event loop is turning. Deliberately
+	// static — restarting the process would not bring Redis back, so a Redis
+	// outage must not read as "this container is broken, kill it".
+	app.use(createHealthcheckRouter(express));
+
+	// Readiness: can this replica serve right now? Redis backs sessions,
+	// authorization codes and refresh-token families in the deployable
+	// defaults, so a replica that has lost it answers 503 here and should be
+	// taken out of rotation. Probes are contributed by the builders that own
+	// each connection; a memory-only deployment registers none and is always
+	// ready.
+	app.use(
+		createReadinessRouter(express, {
+			probes: options.probes,
+			timeoutMs: options.readinessTimeoutMs,
+			logger: options.logger,
+		}),
+	);
+
+	// Prometheus scrape endpoint. Same reasoning as the probes above: it has to
+	// keep answering while the auth pipeline is degraded, because that is when
+	// the series matter.
+	app.use(
+		options.metrics.route(express, {
+			probes: options.probes,
+			probeTimeoutMs: options.readinessTimeoutMs,
+		}),
+	);
+
+	// The composed auth router, which ends in core's terminal handler.
+	app.use(options.router);
+	// Core's terminal handler again, LAST, for the host routes
+	// above: Express routes an error only to handlers registered after the
+	// route that threw it. See the file header.
+	app.use(terminalErrorHandler(options.logger));
+}

package/templates/standalone/src/sections.mts

@@ -0,0 +1,366 @@
+/*
+ * 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 schemas of the template's own sections: its modules' — `logging`,
+ * `http` (with its CORS list), `key-store`, `redis-clients`, `repositories`,
+ * the in-process code repository's and `audit-sink` — and the composition
+ * root's own `adapters` and `mfaMode`. Each is strict, a key it does not
+ * declare refused;
+ * each reads the strings an environment variable carries; none holds a
+ * default, which lives in `config/reference.conf`. The rules a value is held
+ * to are core's shared vocabulary (trusted-proxy entries, serialized origins,
+ * key ids), applied here, never restated.
+ */
+
+import {
+	checkSerializedOrigin,
+	checkTrustedProxyEntry,
+	describeSerializedOriginRejection,
+	describeTrustedProxyEntryRejection,
+	isWellFormedKid,
+	MAX_KID_LENGTH,
+	MAX_TRUST_PROXY_HOPS,
+	normalizeAllowedOrigins,
+	wholeNumberFromEnv,
+	wholeNumberInRangeFromEnv,
+} from "@o3co/auth-provider-core";
+import { mfaConfigSchema } from "@o3co/auth-provider-mfa";
+import { z } from "zod";
+
+/** `logging`: the level the process logs at. `silent` is a threshold, not a level. */
+export const loggingSectionSchema = z
+	.object({ level: z.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"]) })
+	.strict();
+
+/** What the logger is built from: the `logging` module's section. */
+export type LoggingSettings = z.output<typeof loggingSectionSchema>;
+
+/**
+ * A decimal, optionally signed or fractional: the variable's shapes meant as a
+ * hop count, so `-1` and `1.5` fail as hop counts instead of reading as
+ * one-entry address lists.
+ */
+const NUMERIC_STRING = /^-?[0-9]+(\.[0-9]+)?$/;
+
+/**
+ * A `trust proxy` value in one of Express's shapes: the variable's string read
+ * as `true` / `false` / a hop count / a comma-separated list, a list's entries
+ * trimmed. `1` and `0` are hop counts here, not booleans. An exported-but-empty
+ * variable is `false`: trust nothing.
+ */
+const normalizeTrustProxy = (raw: unknown): unknown => {
+	if (Array.isArray(raw)) {
+		return raw.map((entry) => (typeof entry === "string" ? entry.trim() : entry));
+	}
+	if (typeof raw !== "string") return raw;
+	const value = raw.trim();
+	if (value === "") return false;
+	const lower = value.toLowerCase();
+	if (lower === "true") return true;
+	if (lower === "false") return false;
+	if (NUMERIC_STRING.test(value)) return Number(value);
+	return value
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry) => entry !== "");
+};
+
+/**
+ * `http.trustProxy`, handed to Express's `trust proxy`: `false` (trust
+ * nothing), `true` (trust every hop), a hop count up to
+ * `MAX_TRUST_PROXY_HOPS`, or a non-empty list of IP literals, CIDR ranges and
+ * named ranges, each held to core's trusted-proxy vocabulary so a typo fails
+ * at boot, naming its index, instead of never matching.
+ */
+const trustProxySchema = z
+	.preprocess(
+		normalizeTrustProxy,
+		z.union([
+			z.boolean(),
+			z.number().int().min(0).max(MAX_TRUST_PROXY_HOPS),
+			z
+				.array(z.string())
+				.min(
+					1,
+					"must list at least one address, CIDR range, or named range — use `false` to trust no forwarding hop",
+				),
+		]),
+	)
+	.superRefine((value, ctx) => {
+		if (!Array.isArray(value)) return;
+		value.forEach((entry, index) => {
+			const rejection = checkTrustedProxyEntry(entry);
+			if (rejection !== null) {
+				ctx.addIssue({
+					code: "custom",
+					message: `http.trustProxy[${index}] ${describeTrustedProxyEntryRejection(rejection)}`,
+					path: [index],
+				});
+			}
+		});
+	});
+
+/**
+ * `http.cors.allowedOrigins`: the browser origins allowed to read the token,
+ * userinfo, revocation and discovery/JWKS responses; empty is CORS off. A list,
+ * or the one comma-separated string `HTTP_CORS_ALLOWED_ORIGINS` carries
+ * (`normalizeAllowedOrigins`, core's reading of an origin list);
+ * `null` reads as no origins, any other shape is refused. Each entry must be a
+ * serialized origin, matched by exact string equality: one that could never
+ * match is refused, naming its index.
+ */
+const allowedOriginsSchema = z
+	.preprocess((raw, ctx) => {
+		if (raw === undefined) return raw;
+		if (raw !== null && typeof raw !== "string" && !Array.isArray(raw)) {
+			ctx.addIssue({
+				code: "custom",
+				message: `http.cors.allowedOrigins must be a list of origins, or one comma-separated string of them (HTTP_CORS_ALLOWED_ORIGINS); got ${typeof raw === "object" ? "an object" : `a ${typeof raw}`}`,
+			});
+			return raw;
+		}
+		return normalizeAllowedOrigins(raw);
+	}, z.array(z.string()))
+	.superRefine((value, ctx) => {
+		value.forEach((entry, index) => {
+			const rejection = checkSerializedOrigin(entry);
+			if (rejection !== null) {
+				ctx.addIssue({
+					code: "custom",
+					message: `http.cors.allowedOrigins[${index}] ${describeSerializedOriginRejection(rejection)}`,
+					path: [index],
+				});
+			}
+		});
+	});
+
+const PORT_RULE =
+	"http.port must be a port number from 0 to 65535 in decimal digits, 0 letting the OS choose a free port (HTTP_PORT); an exported-but-empty HTTP_PORT is not one";
+
+/**
+ * `http.port`, read strictly: an empty or non-decimal value fails boot instead
+ * of reading as 0, which would listen on a port the OS picks at random.
+ */
+const portSchema = wholeNumberFromEnv(
+	z
+		.number({ error: PORT_RULE })
+		.int({ error: PORT_RULE })
+		.min(0, { error: PORT_RULE })
+		.max(65_535, { error: PORT_RULE }),
+);
+
+/**
+ * `http`: the listener's port, the trusted forwarding hops, the readiness
+ * deadline, and the CORS list. The deadline is bounded both ways, because
+ * `setTimeout` turns 0 and anything above 2^31-1 into 1 ms: every probe would
+ * time out.
+ */
+export const httpSectionSchema = z
+	.object({
+		port: portSchema,
+		trustProxy: trustProxySchema,
+		readinessTimeoutMs: wholeNumberInRangeFromEnv(1, 2_147_483_647),
+		cors: z.object({ allowedOrigins: allowedOriginsSchema }).strict(),
+	})
+	.strict();
+
+/** A key id `verifyJwt` accepts: one it would refuse would fail every token signed under it. */
+const kidSchema = z.string().refine(isWellFormedKid, {
+	message: `must be a key id: a string of 1 to ${MAX_KID_LENGTH} characters with no control character`,
+});
+
+/** HS256: a shared secret, rotated through `previousSecrets`. */
+const hs256LocalSchema = z
+	.object({
+		algorithm: z.literal("HS256"),
+		kid: kidSchema,
+		secret: z.string().optional(),
+		previousSecrets: z
+			.array(z.object({ kid: kidSchema, secret: z.string(), expiresAt: z.string() }).strict())
+			.optional(),
+	})
+	.strict();
+
+/**
+ * RS256, ES256, EdDSA: a key pair, rotated through `previousKeys`. `secret`,
+ * which the reference binds for every algorithm, and `previousSecrets` are
+ * accepted and left to the key store, which names what an asymmetric key
+ * cannot use them for.
+ */
+const asymmetricLocalSchema = z
+	.object({
+		algorithm: z.enum(["RS256", "ES256", "EdDSA"]),
+		kid: kidSchema,
+		privateKey: z.string().optional(),
+		privateKeyPath: z.string().optional(),
+		publicKey: z.string().optional(),
+		publicKeyPath: z.string().optional(),
+		previousKeys: z
+			.array(
+				z
+					.object({
+						kid: kidSchema,
+						publicKey: z.string().optional(),
+						publicKeyPath: z.string().optional(),
+						expiresAt: z.string(),
+					})
+					.strict(),
+			)
+			.optional(),
+		secret: z.string().optional(),
+		previousSecrets: z.unknown().optional(),
+	})
+	.strict();
+
+/**
+ * `key-store`: which key store builds the signing key (`provider`, `local` the
+ * one this template registers) and the local store's settings, shape only:
+ * whether the key material is there is the key store's check, when it is
+ * built.
+ */
+export const keyStoreSectionSchema = z
+	.object({
+		provider: z.string(),
+		local: z.discriminatedUnion("algorithm", [hs256LocalSchema, asymmetricLocalSchema]).optional(),
+	})
+	.strict();
+
+/** `redis-clients`: the one Redis connection every Redis-backed store shares. */
+export const redisClientsSectionSchema = z
+	.object({ url: z.string(), password: z.string().optional() })
+	.strict();
+
+/**
+ * `adapters`: which adapter fills each slot, the composition root's own
+ * choice. `userSessionStores` switches the four user-session stores and the
+ * subject-level revocation pair together; the repositories take core's
+ * `static`, an alias of `yaml` with a block of its own; `mfaFactorStore` and
+ * `mfaTransactionStore` are read by a composition that installs MFA;
+ * `auditSink` names a sink the audit-sink module's factory registers.
+ */
+export const adaptersSchema = z
+	.object({
+		rateLimiter: z.enum(["memory", "redis"]),
+		userSessionStores: z.enum(["memory", "redis"]),
+		accessTokenDenylist: z.enum(["memory", "redis"]),
+		replaySeenSet: z.enum(["memory", "redis"]),
+		consentStore: z.enum(["none", "memory", "redis"]),
+		federationTokenStore: z.enum(["memory", "redis"]),
+		federationGrantStore: z.enum(["none", "memory", "redis"]),
+		federationGrantIntentStore: z.enum(["none", "memory", "redis"]),
+		mfaFactorStore: z.enum(["memory", "redis", "store"]),
+		mfaTransactionStore: z.enum(["memory", "redis"]),
+		codeRepository: z.enum(["memory", "redis"]),
+		clientRepository: z.enum(["yaml", "static"]),
+		userRepository: z.enum(["yaml", "static", "http"]),
+		auditSink: z.string().min(1),
+	})
+	.strict();
+
+/** The composition root's adapter selections, as `adaptersSchema` reads them. */
+export type Adapters = z.output<typeof adaptersSchema>;
+
+/** A section of keys: an object whose prototype is `Object.prototype` or none. */
+export function isPlainSection(value: unknown): value is Readonly<Record<string, unknown>> {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype: unknown = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * `mfaMode`: whether the composition root installs MFA, its own choice — the
+ * MFA package's mode, read with that package's schema for `mfa.mode`. `off`
+ * installs nothing of MFA; `optional` and `required` install it and are
+ * written to `mfa.mode`.
+ */
+export const mfaSwitchSchema = mfaConfigSchema.shape.mode;
+
+/** The composition root's MFA switch, as `mfaSwitchSchema` reads it. */
+export type MfaSwitch = z.output<typeof mfaSwitchSchema>;
+
+/** A YAML file's path: a repository reads its entries from it when it is built. */
+const yamlSchema = z.object({ path: z.string() }).strict();
+
+/**
+ * `repositories`: the YAML client registry, and the user repository's
+ * settings for each adapter it may be — the YAML file, or the Store's HTTP
+ * endpoints. `static`, core's alias of `yaml`, reads the same shape from a
+ * block of its own, which has no default. The HTTP settings are shape only: the repository holds each
+ * value to its rules (https or loopback, a credential's strength, positive
+ * whole numbers) when it is built, and names what it refuses.
+ */
+export const repositoriesSectionSchema = z
+	.object({
+		client: z.object({ yaml: yamlSchema, static: yamlSchema.optional() }).strict(),
+		user: z
+			.object({
+				yaml: yamlSchema,
+				static: yamlSchema.optional(),
+				http: z
+					.object({
+						authenticateUrl: z.unknown().optional(),
+						authenticateByTokenUrl: z.unknown().optional(),
+						linkFederatedIdentityUrl: z.unknown().optional(),
+						findSubjectByFederatedIdentityUrl: z.unknown().optional(),
+						markMfaEnrolledUrl: z.unknown().optional(),
+						federatedIdentityLookupCoverage: z.unknown().optional(),
+						bearerToken: z.unknown().optional(),
+						timeout: z.unknown().optional(),
+						maxResponseBytes: z.unknown().optional(),
+					})
+					.strict(),
+			})
+			.strict(),
+	})
+	.strict();
+
+/**
+ * `repositories` for the adapters `selection` names: `repositoriesSectionSchema`,
+ * and the `static` block's path required for a repository that selects
+ * `static`, since the block has no default. Refused at the section's parse,
+ * naming the path, before any repository is built.
+ */
+export function repositoriesSectionSchemaFor(selection: {
+	readonly client: Adapters["clientRepository"];
+	readonly user: Adapters["userRepository"];
+}) {
+	return repositoriesSectionSchema.superRefine((section, ctx) => {
+		for (const repository of ["client", "user"] as const) {
+			if (selection[repository] === "static" && section[repository].static === undefined) {
+				ctx.addIssue({
+					code: "custom",
+					path: [repository, "static", "path"],
+					message: `required when adapters.${repository}Repository is "static": the static block has no default`,
+				});
+			}
+		}
+	});
+}
+
+/** The in-process code repository's section: the default lifetime, in positive whole seconds. */
+export const inMemoryCodeRepositorySectionSchema = z
+	.object({ defaultExpiresIn: wholeNumberInRangeFromEnv(1) })
+	.strict();
+
+/**
+ * `audit-sink`: each sink's options, keyed by the sink's name, for the sink
+ * `adapters.auditSink` selects. Open: the sinks are the factory's, and each
+ * builder holds its own options to its rules.
+ */
+export const auditSinkSectionSchema = z
+	.record(z.string(), z.record(z.string(), z.unknown()))
+	.optional();