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

package/templates/standalone/src/app.mts

@@ -14,56 +14,49 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
-import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
+import { createApp } from "@o3co/auth-provider-core";
 import express from "express";
 import helmet from "helmet";
 import { buildModules } from "./buildModules.mjs";
-import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
+import {
+	configDefaultsFor,
+	readLogging,
+	readOwnLayers,
+	readSwitches,
+	resolveConfigPaths,
+	resolveForBoot,
+	type Switches,
+} from "./configPath.mjs";
 import { listen } from "./listen.mjs";
 import { createAppLogger } from "./logger.mjs";
 import { createMetrics } from "./metrics.mjs";
 import { mountRoutes } from "./routes.mjs";
-import { cleanupAllowanceFor, installGracefulShutdown } from "./shutdown.mjs";
+import { installGracefulShutdown } from "./shutdown.mjs";
 
-// Step 1: Load and validate application config (HOCON → Zod schema).
+// Step 1: the configuration, in two phases (`configPath.mts`; template
+// README, "Environment-specific config overlay").
 // ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
-//
-// 3-tier HOCON precedence (highest → lowest):
-//   1. {env}.conf         — environment-specific overrides (e.g. production.conf)
-//   2. application.conf   — template-level consumer delta
-//   3. reference.conf     — library defaults shipped in @o3co/auth-provider-core
 const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
 const configDir = new URL("../config/", import.meta.url);
 const configDirPath = fileURLToPath(configDir);
 const { applicationConfPath, envConfPath } = resolveConfigPaths(configDirPath, env);
-const libraryReferencePath = resolveLibraryReferenceConfPath();
-const config: AppConfig = validate(
-	parseFile(envConfPath)
-		.withFallback(parseFile(applicationConfPath))
-		.withFallback(parseFile(libraryReferencePath)),
-	AppConfigSchema,
-);
+// Read once, so both phases read the same thing.
+const own = readOwnLayers([envConfPath, applicationConfPath]);
+// Phase one: what the template reads before it knows its modules, only for
+// those choices — its own `adapters` and MFA switch (`mfaMode`, MFA_MODE),
+// and whether federation grants are installed.
+const switches: Switches = readSwitches(own);
 
-// The logger is built from config so its level is operator-controlled, and it
-// is wired into `bootstrapComponents` so every module that declares
-// `optional: ["logger"]` receives this one rather than falling back to its own
-// default. Without that slot filled, configuring a level here would change
-// nothing about what the modules emit.
-const logger = createAppLogger(config);
+// From the `logging` module's section, so the level holds from the first line;
+// wired into `bootstrapComponents` so every module logs through it (template
+// README, "Logging").
+const logger = createAppLogger(readLogging(own));
 
 await (async (): Promise<void> => {
 	// Step 2: Create the Express app and apply base security middleware.
+	// `trust proxy` is set from the `http` module's `httpSettings` once boot
+	// has it (step 3), before a request can arrive.
 	const app = express();
-	// `false` | `true` | a hop count | a list of IPs / CIDR ranges / named
-	// ranges — the schema hands Express exactly the shapes `trust proxy`
-	// already understands, validated at boot so a typo'd range fails here
-	// rather than becoming a rule that silently never matches (#292). Prefer
-	// naming the proxy: `true` believes a forwarded client address from anyone
-	// who can reach this process, and `req.ip` is what every IP-keyed rate
-	// limit is bucketed on.
-	app.set("trust proxy", config.http.trustProxy);
 	app.use(
 		helmet({
 			contentSecurityPolicy: {
@@ -81,70 +74,63 @@ await (async (): Promise<void> => {
 	const metrics = createMetrics();
 	app.use(metrics.middleware);
 
-	// Step 3: Boot the auth pipeline.
-	// D-5: express-session middleware is now wired by `sessionStoreModule`
-	// inside the boot planner. Mount order is enforced by declarationIndex
-	// tie-breaking — sessionStoreModule MUST come first in `buildModules(...)`
-	// so the middleware initialises `req.session` for every downstream route.
-	// The connect-redis client's lifetime is owned by the planner via
-	// `BuilderContext.lifecycle` and drained on `handle.dispose()`.
-	// bootstrapComponents carries only host-
-	// environment values (config + pathResolver per A2-γ §4 worked example);
-	// every other component flows through composition-root-local modules.
-	// `buildModules` is the single source of truth for the module list — it
-	// gates federation modules on `config.federations.<name>.enabled`, which
-	// the standalone scaffold defaults to false.
+	// Step 3: boot the auth pipeline. `buildModules` is the single source of
+	// truth for the module list and its order; `bootstrapComponents` carries
+	// only host-environment values, every other component comes from the
+	// modules. `environment` is the name the config was selected by: the Redis
+	// federation-token store's plaintext guard reads it as well as NODE_ENV,
+	// so `CONFIG_ENV=production` is production to the guard too.
 	//
-	// `environment` is the name the config above was selected by (#473): the
-	// Redis federation-token store's plaintext guard reads it in addition to
-	// NODE_ENV, so `CONFIG_ENV=production` is production to the guard too.
-	// `logger` is where the composition's own notices go (a deprecated config
-	// key), the same logger every module gets through the slot below.
+	// Phase two: `createApp` parses the configuration as resolved once, with
+	// every loaded module's schema (`configPath.mts`), and names each section
+	// nothing loaded reads by the configuration's defaults. From here on the
+	// template reads the parsed configuration.
+	const modules = buildModules(switches, { environment: env });
 	const handle = await createApp({
-		modules: buildModules(config, { environment: env, logger }),
+		modules,
 		bootstrapComponents: {
-			config,
+			config: resolveForBoot(own, modules, switches),
+			configDefaults: configDefaultsFor(modules),
 			pathResolver: import.meta.resolve,
 			logger,
 		},
 	});
+	// The `http` module's settings: core's slot and the host's own.
+	const { httpSettings, httpHostSettings } = handle.components;
+	if (httpSettings === undefined || httpHostSettings === undefined) {
+		throw new Error("createApp booted without the http module's settings");
+	}
+	// `false` | `true` | a hop count | a list of IPs / CIDR ranges / named
+	// ranges: the shapes `trust proxy` understands, validated at boot so a
+	// typo'd range fails there rather than silently never matching. Prefer
+	// naming the proxy: `true` believes a forwarded client address from anyone
+	// who can reach this process, and every IP-keyed rate limit buckets on
+	// `req.ip`.
+	app.set("trust proxy", httpSettings.trustProxy);
 
-	// Step 4: the host-level routes (liveness, readiness, metrics) ahead of the
-	// auth router so they remain reachable even when the auth pipeline is
-	// degraded — which is exactly when an operator needs an answer from them —
-	// then the composed auth router, then the terminal error handler. See
-	// `routes.mts` for what each is and why the order is what it is.
+	// Step 4: the host routes (liveness, readiness, metrics), then the composed
+	// auth router, then the terminal error handler; `routes.mts` says why in
+	// that order.
 	mountRoutes(app, {
 		router: handle.router,
 		probes: handle.readinessProbes,
-		readinessTimeoutMs: config.http.readinessTimeoutMs,
+		readinessTimeoutMs: httpHostSettings.readinessTimeoutMs,
 		metrics,
 		logger,
 	});
-	// Step 5: start the HTTP server.
-	// Resolves once the socket is bound (`server_listening`); a port that
-	// cannot be bound rejects, and boot fails with that error (`listen.mts`).
-	const server = await listen(app, config.http.port, logger);
+	// Step 5: start the HTTP server. A port that cannot be bound fails boot
+	// with that error (`listen.mts`).
+	const server = await listen(app, httpHostSettings.port, logger);
 
-	// Step 6: Graceful shutdown — handle.dispose() runs reverse-topological
-	// per-component cleanup (per A2-β §8.1) plus D-5 LifecycleRegistrar drain
-	// (Redis clients, interval timers).
-	//
-	// #290: in the template rather than a dependency, because "does SIGTERM
-	// wait for in-flight requests, and for how long?" has to be answerable
-	// from the code you deploy. See `shutdown.mts` for the stated guarantees
-	// and for the deadline the previous implementation did not have. Size
-	// `drainTimeoutMs` below your orchestrator's kill grace period.
-	//
-	// #593 slice 7: with federation grants on, cleanup gets the longest refresh
-	// tail the configured budgets allow plus a margin — 45 s under the shipped
-	// ones — rather than inheriting the drain's ten: the dispose is what waits
-	// for a rotated credential's write. The compose files size
-	// `stop_grace_period` to cover the drain, this and an exit margin for the
-	// shipped budgets; a raised budget raises both.
+	// Step 6: graceful shutdown (`shutdown.mts`). Size `drainTimeoutMs` below
+	// your orchestrator's kill grace period. Cleanup gets at least the
+	// allowance the modules registered with their cleanups (45 s with
+	// federation grants on under the shipped budgets) rather than only the
+	// drain's ten; the template README, "Shutdown guarantees", sizes the grace
+	// period for it.
 	installGracefulShutdown(server, {
 		logger,
 		cleanup: () => handle.dispose(),
-		...cleanupAllowanceFor(config),
+		cleanupAllowanceMs: () => handle.cleanupAllowanceMs,
 	});
 })();

package/templates/standalone/src/bootRefusal.mts

@@ -0,0 +1,117 @@
+/*
+ * 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 refusals before boot, as core's `BootError`: each under the
+ * reason boot raises for the same case, at the stage boot raises it in
+ * (`validateManifests`), so that an alert keyed on a boot error's reason sees
+ * every refusal to start. The template's checks stay its own; only how a
+ * refusal is reported is boot's.
+ *
+ * The details name a module as boot does. A key of the composition root's
+ * own — the `adapters` section, the `mfaMode` switch — is named after itself,
+ * as boot names core's own section "core": a module with a section under
+ * either name is refused (`resolveForBoot`), so the name points at the key.
+ */
+
+import {
+	BootError,
+	type ConfigPathRelocatedDetails,
+	type ConfigValidationFailedDetails,
+	type EnvironmentVariableRenamedDetails,
+} from "@o3co/auth-provider-core";
+
+/** A Zod issue as `config-validation-failed` carries one: its path is the path in the configuration. */
+export type ConfigIssue = ConfigValidationFailedDetails["issues"][number];
+
+/** The stage boot raises the configuration's refusals in. */
+const STAGE = "validateManifests";
+
+/** An issue at `path` of the configuration that no schema raised: what is wrong there, in `message`. */
+export function customIssue(path: readonly string[], message: string): ConfigIssue {
+	return { code: "custom", path: [...path], message } as ConfigIssue;
+}
+
+/** `issues`, each with `prefix`, the path its schema read at, in front of its own path. */
+export function issuesAt(prefix: readonly string[], issues: readonly ConfigIssue[]): ConfigIssue[] {
+	return issues.map((issue) => ({ ...issue, path: [...prefix, ...issue.path] }) as ConfigIssue);
+}
+
+/**
+ * `config-validation-failed`: `issues` at their paths, refused in the
+ * sections `modules` read, each at its `schemaPath`.
+ */
+export function configRefused(
+	message: string,
+	issues: readonly ConfigIssue[],
+	modules: ConfigValidationFailedDetails["modules"],
+): BootError {
+	return new BootError({
+		message,
+		reason: "config-validation-failed",
+		stage: STAGE,
+		details: { reason: "config-validation-failed", issues: [...issues], modules: [...modules] },
+	});
+}
+
+/**
+ * `config-validation-failed` for one key, at `path`, of the section `module`
+ * reads at its own name: `message` is the refusal and the issue's message.
+ */
+export function keyRefused(message: string, module: string, path: readonly string[]): BootError {
+	return configRefused(message, [customIssue(path, message)], [{ module, schemaPath: module }]);
+}
+
+/** `config-path-relocated`: each key still set at a path it moved from. */
+export function pathsRelocated(
+	message: string,
+	relocated: ConfigPathRelocatedDetails["relocated"],
+): BootError {
+	return new BootError({
+		message,
+		reason: "config-path-relocated",
+		stage: STAGE,
+		details: { reason: "config-path-relocated", relocated: [...relocated] },
+	});
+}
+
+/** `environment-variable-renamed`: each old variable name set, with no value. */
+export function variablesRenamed(
+	message: string,
+	renamed: EnvironmentVariableRenamedDetails["renamed"],
+): BootError {
+	return new BootError({
+		message,
+		reason: "environment-variable-renamed",
+		stage: STAGE,
+		details: { reason: "environment-variable-renamed", renamed: [...renamed] },
+	});
+}
+
+/** `module-section-path-invalid`: `module`'s section is read at `at`, which `problem` says it may not be. */
+export function sectionPathRefused(
+	message: string,
+	module: string,
+	at: string,
+	problem: string,
+): BootError {
+	return new BootError({
+		message,
+		reason: "module-section-path-invalid",
+		stage: STAGE,
+		details: { reason: "module-section-path-invalid", module, at, problem },
+	});
+}