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

package/templates/standalone/src/app.mts

@@ -14,61 +14,50 @@
  * limitations under the License.
  */
 import { fileURLToPath } from "node:url";
-import {
-	type AppConfig,
-	AppConfigSchema,
-	createApp,
-	createHealthcheckRouter,
-	createReadinessRouter,
-} 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 {
+	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 { cleanupAllowanceFor, installGracefulShutdown } from "./shutdown.mjs";
-import { createTerminalErrorHandler } from "./terminalError.mjs";
+import { mountRoutes } from "./routes.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 the switches core's reader parses — and for what the composition
+// expects of session admission: the configuration's list, with `mfa` added
+// when the MFA switch installs MFA.
+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: {
@@ -86,94 +75,61 @@ 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.
+	// Phase two: `createApp` parses the configuration as resolved once, with
+	// every loaded module's schema (`configPath.mts`). From here on the
+	// template reads the parsed configuration.
+	const modules = buildModules(switches, { environment: env, logger });
 	const handle = await createApp({
-		modules: buildModules(config, { environment: env }),
+		modules,
 		bootstrapComponents: {
-			config,
+			config: resolveForBoot(own, modules, switches),
 			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: Wire host-level routes before 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.
-	//
-	// 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: handle.readinessProbes,
-			timeoutMs: config.http.readinessTimeoutMs,
-			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(
-		metrics.route(express, {
-			probes: handle.readinessProbes,
-			probeTimeoutMs: config.http.readinessTimeoutMs,
-		}),
-	);
-
-	// Step 5: Mount the composed auth router and start the HTTP server.
-	app.use(handle.router);
-	// Terminal error handler LAST (#293 item 8): Express routes an error only
-	// to handlers registered after the route that threw it. See
-	// `terminalError.mts` for what it catches and why.
-	app.use(createTerminalErrorHandler(logger));
-	const server = app.listen(config.http.port, (): void => {
-		logger.info(`Server is running on http://localhost:${config.http.port}`);
+	// 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: httpHostSettings.readinessTimeoutMs,
+		metrics,
+		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,
 	});
 })();