@webjsdev/server 0.8.8 → 0.8.10

package/src/dev.js

@@ -4,7 +4,16 @@ import { existsSync } from 'node:fs';
 import { digestHex } from './crypto-utils.js';
 import { createGzip, createBrotliCompress, constants as zlibConstants } from 'node:zlib';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
-import { createRequire, stripTypeScriptTypes } from 'node:module';
+import { createRequire } from 'node:module';
+// Namespace import, NOT `import { stripTypeScriptTypes }`. On Node < 22.13 the
+// `stripTypeScriptTypes` named export does not exist, and a NAMED import of a
+// missing builtin export is a LINK-TIME SyntaxError that fires before any
+// module body runs, which would defeat the Node-version preflight (issue #238)
+// by crashing the import of @webjsdev/server itself. A namespace import links
+// on every Node (the property is just `undefined` at runtime on old Node), so
+// importing @webjsdev/server succeeds and `assertNodeVersion()` at the top of
+// createRequestHandler throws the clean "you need Node 24+" message instead.
+import * as nodeModule from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Server-side `.ts` imports are handled natively by Node 24+'s default
@@ -40,6 +49,7 @@ process.emitWarning = function (warning, type, code, ctor) {
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { ssrPage, ssrNotFound } from './ssr.js';
+import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
 import {
   buildActionIndex,
@@ -56,7 +66,10 @@ import {
   hashFile,
 } from './actions.js';
 import { defaultLogger } from './logger.js';
-import { withRequest } from './context.js';
+import { assertNodeVersion } from './node-version.js';
+import { applyEnvValidation } from './env-schema.js';
+import { withRequest, setCspNonce, setBodyLimits } from './context.js';
+import { readCspConfig, mintNonce, buildCspHeader, cspHeaderName } from './csp.js';
 import { attachWebSocket } from './websocket.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
 import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
@@ -69,6 +82,8 @@ function kebab(name) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
 import { urlFromRequest } from './forwarded.js';
+import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
+import { readBodyLimits, computeServerTimeouts } from './body-limit.js';
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -194,6 +209,81 @@ export async function readElideEnabled(appDir) {
   return true;
 }
 
+/**
+ * Read the per-path response-header config (`webjs.headers`) from the
+ * app's package.json and compile it to URLPattern rules. A missing,
+ * malformed, or unreadable config yields an empty rule set (the secure
+ * defaults still apply), never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileHeaderRules>>}
+ */
+export async function readHeaderRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileHeaderRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the CSP config (`webjs.csp`) from the app's package.json and
+ * normalize it (issue #233). A missing, malformed, or unreadable config
+ * yields a disabled config (no nonce minted, no CSP header), never a
+ * throw: a broken security knob must fail closed, not take the app down.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof readCspConfig>>}
+ */
+export async function readCspConfigFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readCspConfig(pkg);
+  } catch {
+    return readCspConfig(undefined);
+  }
+}
+
+/**
+ * Resolve the request body-size limits (issue #237) from the app's package.json
+ * `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env overrides
+ * (`WEBJS_MAX_BODY_BYTES` / `WEBJS_MAX_MULTIPART_BYTES`). A missing or
+ * unreadable package.json falls through to the secure defaults (env still wins),
+ * never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ json: number, multipart: number }>}
+ */
+export async function readBodyLimitsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return readBodyLimits(pkg);
+}
+
+/**
+ * Resolve the node:http server timeouts (issue #237) from the app's
+ * package.json `webjs.requestTimeoutMs` / `webjs.headersTimeoutMs` /
+ * `webjs.keepAliveTimeoutMs` plus the env overrides. A missing or unreadable
+ * package.json falls through to the secure defaults (env still wins).
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }>}
+ */
+export async function readServerTimeoutsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return computeServerTimeouts(pkg);
+}
+
 /**
  * Create a reusable, framework-agnostic request handler for a webjs app.
  * The returned `handle(req)` takes a standard `Request` and resolves to a
@@ -208,6 +298,10 @@ export async function readElideEnabled(appDir) {
  * }} opts
  */
 export async function createRequestHandler(opts) {
+  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Throw a clear Error here so an embedded host (Express/Fastify/Bun/Deno)
+  // gets the actionable message at boot, not a cryptic API failure mid-request.
+  assertNodeVersion({ onFail: 'throw' });
   const appDir = resolve(opts.appDir);
   // Load <appDir>/.env into process.env BEFORE anything else.
   // buildActionIndex below imports server-only files (lib/*.server.ts,
@@ -217,6 +311,14 @@ export async function createRequestHandler(opts) {
   // to boot until the user discovered the missing env-load. See
   // tracker #37.
   loadAppEnv(appDir);
+  // Optional boot-time env validation (#236). If <appDir>/env.{js,ts} exists it
+  // default-exports a typed schema or a custom validator function; we run it
+  // against process.env (now populated by loadAppEnv) BEFORE buildActionIndex
+  // imports any server-only module. A failure throws a clear aggregated Error
+  // here, so an embedded host rejects at boot and the CLI exits non-zero,
+  // failing fast instead of crashing cryptically mid-request. Absent file is a
+  // no-op (opt-in). Coerced + defaulted values are written back to process.env.
+  await applyEnvValidation(appDir, { dev: !!opts.dev });
   const dev = !!opts.dev;
   const logger = opts.logger || defaultLogger({ dev });
   const coreDir = locateCoreDir(appDir);
@@ -285,10 +387,32 @@ export async function createRequestHandler(opts) {
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
 
+  // Per-path response-header rules (issue #232), read once from the
+  // app's package.json `webjs.headers`. Static config, so no rebuild
+  // re-read; the secure defaults need no config and apply regardless.
+  const headerRules = await readHeaderRules(appDir);
+
+  // CSP config (issue #233), read once from the app's package.json
+  // `webjs.csp`. OFF by default: when disabled no nonce is minted and no
+  // Content-Security-Policy header is set, so an unconfigured app is
+  // unchanged. When enabled, `handle()` mints a fresh per-request nonce,
+  // makes it the value `cspNonce()` returns (so the SSR'd inline scripts
+  // carry it), and sets the matching header carrying the same nonce.
+  const cspConfig = await readCspConfigFromApp(appDir);
+
+  // Request body-size limits (issue #237), read once from the app's
+  // package.json `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env
+  // overrides. The secure defaults (1 MiB JSON/RPC, 10 MiB form) apply when
+  // unconfigured. Stamped on every request via `setBodyLimits` so `readBody`
+  // (used inside route handlers) enforces the same cap the RPC and page-action
+  // paths do.
+  const bodyLimits = await readBodyLimitsFromApp(appDir);
+
   const state = {
     routeTable,
     actionIndex: null,
     middleware: null,
+    bodyLimits,
     logger,
     moduleGraph: null,
     elidableComponents: new Set(),
@@ -555,6 +679,59 @@ export async function createRequestHandler(opts) {
   /** @param {Request} req */
   function handle(req) {
     return withRequest(req, async () => {
+      // CSP (issue #233): when enabled, mint a fresh CSPRNG nonce and store
+      // it on the request scope BEFORE producing the response, so the SSR
+      // pipeline's `cspNonce()` reads this exact value and stamps it on the
+      // inline boot script, the importmap, and the modulepreload hints.
+      // Disabled by default, so no nonce is minted and the response is
+      // unchanged. One minted value flows mint -> store -> SSR -> header.
+      const nonce = cspConfig.enabled ? mintNonce() : '';
+      if (nonce) setCspNonce(nonce);
+
+      // Make the resolved body-size limits (issue #237) readable from the
+      // request scope, so `readBody` inside a route handler enforces the same
+      // cap the framework's own RPC / page-action body reads do.
+      setBodyLimits(state.bodyLimits);
+
+      const res = await produce(req);
+      // Merge in the secure-by-default headers plus the per-path config
+      // (issue #232) as the final step, so app middleware, route
+      // handlers, and `expose` headers (already on `res`) always win.
+      // Applied to every served response (documents, assets, the core
+      // runtime, probes), since the defaults are universally safe.
+      let pathname = '/';
+      try { pathname = new URL(req.url).pathname; } catch { /* keep default */ }
+      const merged = applySecurityHeaders(res, {
+        pathname,
+        https: webRequestIsHttps(req),
+        prod: !dev,
+        rules: headerRules,
+      });
+      // Emit the Content-Security-Policy header carrying the SAME minted
+      // nonce the SSR'd scripts got (no drift). Set only when CSP is
+      // enabled; never clobber a CSP header the app already set (in
+      // middleware, a route handler, or via the webjs.headers config), so
+      // an explicit app policy still wins.
+      if (nonce && !merged.headers.has('content-security-policy') &&
+          !merged.headers.has('content-security-policy-report-only')) {
+        // readCspConfig already drops a directive whose name/value carries a
+        // control char, so buildCspHeader produces a Headers-safe value. The
+        // try/catch is a belt-and-suspenders backstop: a surprise value must
+        // never throw the response pipeline (fail closed to no CSP header
+        // rather than a self-inflicted 500 on every request).
+        try {
+          merged.headers.set(cspHeaderName(cspConfig), buildCspHeader(cspConfig, nonce));
+        } catch {
+          /* a malformed policy must not take the request down: serve without CSP */
+        }
+      }
+      return merged;
+    });
+  }
+
+  /** @param {Request} req */
+  function produce(req) {
+    return (async () => {
       // Health and readiness probes are answered BEFORE ensureReady so a probe
       // never blocks on the analysis. `/__webjs/health` is liveness (the
       // process is up and accepting connections). `/__webjs/ready` is 503 until
@@ -623,7 +800,7 @@ export async function createRequestHandler(opts) {
         }
       }
       return next();
-    });
+    })();
   }
 
   /**
@@ -800,6 +977,20 @@ export async function startServer(opts) {
     }
   });
 
+  // Inbound server timeouts (issue #237), node:http built-ins. Defends against
+  // slowloris and hung connections: `requestTimeout` bounds the time to receive
+  // the WHOLE request, `headersTimeout` the time to receive just the headers
+  // (node measures both from the same request start, so it is kept strictly
+  // under requestTimeout to actually fire), and `keepAliveTimeout` the idle
+  // window before a kept-alive socket is closed. Secure production defaults,
+  // overridable via `webjs.requestTimeoutMs` / `headersTimeoutMs` /
+  // `keepAliveTimeoutMs` in package.json or the matching WEBJS_*_MS env vars.
+  // A value of 0 disables that timeout (node's own no-limit sentinel).
+  const timeouts = await readServerTimeoutsFromApp(app.appDir);
+  server.requestTimeout = timeouts.requestTimeout;
+  server.headersTimeout = timeouts.headersTimeout;
+  server.keepAliveTimeout = timeouts.keepAliveTimeout;
+
   // WebSocket upgrade handling: any route.js that exports `WS` becomes a
   // WebSocket endpoint at its URL.
   attachWebSocket(server, () => app.getRouteTable(), { dev, logger });
@@ -1103,17 +1294,31 @@ async function handleCore(req, ctx) {
     return runWithSegmentMiddleware(req, api.route.middlewares, handler, dev);
   }
 
-  // Page route (only for GET/HEAD)
-  if (method === 'GET' || method === 'HEAD') {
+  // Page route. GET/HEAD render the page. A NON-GET/HEAD method (POST/PUT/…)
+  // is only routed here when the page module exports an `action` (#244); the
+  // action runs inside the page's segment middleware, then either PRG-redirects
+  // (303) on success, re-renders the same page (422) with field errors on
+  // failure, or honors a thrown redirect()/notFound(). Without an `action`
+  // export, a non-GET/HEAD request falls through to the 404 below, unchanged.
+  {
     const page = matchPage(state.routeTable, path);
     if (page) {
-      const handler = () => ssrPage(page.route, page.params, url, {
-        dev, appDir, req, moduleGraph: state.moduleGraph,
+      const ssrOpts = {
+        dev, appDir, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
         elidableComponents: state.elidableComponents,
         inertRouteModules: state.inertRouteModules,
-      });
-      return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+        notFoundFile: state.routeTable.notFound,
+      };
+      if (method === 'GET' || method === 'HEAD') {
+        const handler = () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
+        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+      }
+      const loaded = await loadPageAction(page.route.file, dev);
+      if (loaded) {
+        const handler = () => runPageAction(page.route, page.params, url, loaded, req, ssrOpts);
+        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+      }
     }
   }
 
@@ -1440,7 +1645,7 @@ async function exists(p) {
  * @returns {Promise<string>}
  */
 async function stripTs(source, _abs) {
-  return stripTypeScriptTypes(source);
+  return nodeModule.stripTypeScriptTypes(source);
 }
 
 /**

package/src/env-schema.js

@@ -0,0 +1,250 @@
+/**
+ * Startup env-var validation with a typed schema hook (issue #236).
+ *
+ * webjs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
+ * validation, so a missing or misconfigured required var (DATABASE_URL,
+ * AUTH_SECRET, ...) fails late and cryptically (a Prisma connect error
+ * mid-request, an undefined secret signing a token). This module adds an
+ * optional boot-time validation hook that fails fast with one clear message
+ * listing EVERY missing or invalid var at once, before the app serves a
+ * request.
+ *
+ * The hook is an optional `env.{js,ts}` module at the app root (sibling of
+ * `middleware.js` / `readiness.js`), default-exporting either:
+ *   1. a plain SCHEMA object, dependency-free, e.g.
+ *        export default {
+ *          DATABASE_URL: 'string',
+ *          AUTH_SECRET: { type: 'string', required: true, minLength: 16 },
+ *          PORT: { type: 'number', optional: true, default: 3000 },
+ *          NODE_ENV: { type: 'enum', values: ['development','production','test'] },
+ *        };
+ *   2. a FUNCTION `(env) => void | throw` for full custom validation (the
+ *      escape hatch), so an app can use zod or anything it likes without webjs
+ *      depending on it. A thrown Error is surfaced as the boot failure.
+ *
+ * The validator is a PURE function (`validateEnv`) so it unit-tests with an
+ * injected schema + env object, no temp app dir needed. `loadEnvSchema` reads
+ * the app's `env.{js,ts}` (returns `null` when absent, so the feature is fully
+ * opt-in), and `applyEnvValidation` is the side-effecting boot wrapper: it runs
+ * the schema/function against `process.env`, applies coerced + defaulted values
+ * back into `process.env`, and throws a clear aggregated Error on failure (so
+ * `createRequestHandler` rejects and the CLI exits non-zero, consistent with
+ * the Node-version preflight).
+ */
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { stat } from 'node:fs/promises';
+
+/** Field type names a schema may declare. */
+const KNOWN_TYPES = new Set(['string', 'number', 'boolean', 'url', 'enum']);
+
+/**
+ * Normalize a schema field to its object form. A bare string like `'string'`
+ * is shorthand for `{ type: 'string' }`.
+ * @param {string | object} rule
+ * @returns {{ type: string, required?: boolean, optional?: boolean, default?: any, values?: any[], minLength?: number, pattern?: (string|RegExp) }}
+ */
+function normalizeRule(rule) {
+  if (typeof rule === 'string') return { type: rule };
+  return rule && typeof rule === 'object' ? rule : { type: 'string' };
+}
+
+/**
+ * Is a field required? A field is required by default. It is optional when it
+ * declares `optional: true`, `required: false`, or carries a `default`.
+ * @param {object} rule normalized rule
+ */
+function isRequired(rule) {
+  if (rule.required === false) return false;
+  if (rule.optional === true) return false;
+  if ('default' in rule) return false;
+  return true;
+}
+
+/**
+ * Coerce a raw string value to the declared type, enforcing the field's
+ * constraints. Returns `{ value }` on success or `{ error }` (a human string)
+ * on failure.
+ * @param {string} name the env var name (for messages)
+ * @param {object} rule normalized rule
+ * @param {string} raw the raw string from the env
+ * @returns {{ value: any } | { error: string }}
+ */
+function coerce(name, rule, raw) {
+  const type = rule.type || 'string';
+  switch (type) {
+    case 'string': {
+      if (typeof rule.minLength === 'number' && raw.length < rule.minLength) {
+        return { error: `${name} must be at least ${rule.minLength} characters (got ${raw.length})` };
+      }
+      if (rule.pattern != null) {
+        const re = rule.pattern instanceof RegExp ? rule.pattern : new RegExp(rule.pattern);
+        if (!re.test(raw)) return { error: `${name} does not match required pattern ${re}` };
+      }
+      return { value: raw };
+    }
+    case 'number': {
+      const n = Number(raw);
+      if (raw.trim() === '' || Number.isNaN(n)) {
+        // Never echo the value: a secret given the wrong type would leak to logs.
+        return { error: `${name} must be a number` };
+      }
+      return { value: n };
+    }
+    case 'boolean': {
+      const v = raw.trim().toLowerCase();
+      if (['1', 'true', 'yes', 'on'].includes(v)) return { value: true };
+      if (['0', 'false', 'no', 'off'].includes(v)) return { value: false };
+      // Never echo the value: list the accepted spellings, not what was given.
+      return { error: `${name} must be a boolean (one of true/false/1/0/yes/no/on/off)` };
+    }
+    case 'url': {
+      try {
+        // eslint-disable-next-line no-new
+        new URL(raw);
+        return { value: raw };
+      } catch {
+        // Never echo the value: a DSN with embedded credentials must not leak.
+        return { error: `${name} must be a valid URL` };
+      }
+    }
+    case 'enum': {
+      const values = Array.isArray(rule.values) ? rule.values : [];
+      if (!values.includes(raw)) {
+        // Name the ALLOWED values (from the schema, safe), never the provided one.
+        return { error: `${name} must be one of ${values.map((v) => JSON.stringify(v)).join(', ')}` };
+      }
+      return { value: raw };
+    }
+    default:
+      return { error: `${name} has an unknown schema type ${JSON.stringify(type)}` };
+  }
+}
+
+/**
+ * Pure env validator. Validates `env` against `schema`, collecting ALL errors
+ * (never stopping at the first), and computes the coerced + defaulted values to
+ * write back. Does NOT mutate `env` or `process.env`; the caller applies
+ * `coerced` to `process.env`.
+ *
+ * When `schema` is a FUNCTION it is the custom-validator escape hatch: it is
+ * called with the env object and any thrown Error is surfaced as a single
+ * error. A function validator never coerces.
+ *
+ * @param {object | Function} schema the default export of `env.{js,ts}`
+ * @param {Record<string, string|undefined>} env the source env (e.g. process.env)
+ * @returns {{ ok: boolean, errors: string[], coerced: Record<string, string> }}
+ */
+export function validateEnv(schema, env) {
+  // Escape hatch: a function gets the env and validates however it wants.
+  if (typeof schema === 'function') {
+    try {
+      schema(env);
+      return { ok: true, errors: [], coerced: {} };
+    } catch (e) {
+      const msg = e && e.message ? String(e.message) : String(e);
+      return { ok: false, errors: [msg], coerced: {} };
+    }
+  }
+
+  if (!schema || typeof schema !== 'object') {
+    // Nothing to validate against. Treat as a no-op rather than an error so a
+    // stray default export does not brick boot.
+    return { ok: true, errors: [], coerced: {} };
+  }
+
+  const errors = [];
+  /** @type {Record<string, string>} */
+  const coerced = {};
+
+  for (const name of Object.keys(schema)) {
+    const rule = normalizeRule(schema[name]);
+    const type = rule.type || 'string';
+    if (!KNOWN_TYPES.has(type)) {
+      errors.push(`${name} declares an unknown type ${JSON.stringify(type)} (expected one of ${[...KNOWN_TYPES].join(', ')})`);
+      continue;
+    }
+    const present = env[name] != null && env[name] !== '';
+    if (!present) {
+      if (isRequired(rule)) {
+        errors.push(`${name} is required but missing`);
+      } else if ('default' in rule) {
+        // Apply the default, coercing it through the same path so a number
+        // default lands as a string in process.env (env values are strings).
+        coerced[name] = String(rule.default);
+      }
+      continue;
+    }
+    const result = coerce(name, rule, String(env[name]));
+    if ('error' in result) {
+      errors.push(result.error);
+    } else if (typeof result.value !== 'string') {
+      // Re-stringify coerced non-string values so process.env stays string-typed.
+      coerced[name] = String(result.value);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, coerced };
+}
+
+/**
+ * Compose the aggregated, actionable failure message from a list of errors.
+ * @param {string[]} errors
+ * @returns {string}
+ */
+export function formatEnvErrors(errors) {
+  const lines = errors.map((e) => `  - ${e}`);
+  return (
+    `webjs env validation failed (${errors.length} ${errors.length === 1 ? 'error' : 'errors'}):\n` +
+    lines.join('\n') +
+    `\n\nFix the variables above in your .env (or the host environment) and restart. ` +
+    `The schema lives in env.{js,ts} at the app root.`
+  );
+}
+
+/**
+ * Load the optional `env.{js,ts}` schema module from the app root. Returns the
+ * default export (a schema object or a validator function), or `null` when no
+ * such file exists, so env validation is fully opt-in.
+ * @param {string} appDir
+ * @param {{ dev?: boolean }} [opts]
+ * @returns {Promise<object | Function | null>}
+ */
+export async function loadEnvSchema(appDir, opts = {}) {
+  let file = null;
+  for (const name of ['env.ts', 'env.js', 'env.mts', 'env.mjs']) {
+    const p = join(appDir, name);
+    try {
+      await stat(p);
+      file = p;
+      break;
+    } catch {
+      // not this name, try the next
+    }
+  }
+  if (!file) return null;
+  const url = pathToFileURL(file).toString();
+  const bust = opts.dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+  const mod = await import(url + bust);
+  return mod.default ?? null;
+}
+
+/**
+ * Side-effecting boot wrapper: load the app's `env.{js,ts}` (if any), validate
+ * `process.env` against it, apply coerced + defaulted values back into
+ * `process.env`, and THROW a clear aggregated Error on failure. A no-op when
+ * `env.{js,ts}` is absent. Called by `createRequestHandler` right after the
+ * `.env` auto-load and before any server-only module is imported.
+ * @param {string} appDir
+ * @param {{ dev?: boolean, env?: Record<string, string|undefined> }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function applyEnvValidation(appDir, opts = {}) {
+  const schema = await loadEnvSchema(appDir, opts);
+  if (schema == null) return; // opt-in: no env.{js,ts}, nothing to do
+  const env = opts.env ?? process.env;
+  const { ok, errors, coerced } = validateEnv(schema, env);
+  if (!ok) throw new Error(formatEnvErrors(errors));
+  // Apply coerced values + defaults back so the app reads the coerced value.
+  for (const key of Object.keys(coerced)) env[key] = coerced[key];
+}