@webjsdev/server 0.8.8 → 0.8.10

package/src/headers.js

@@ -0,0 +1,213 @@
+/**
+ * Secure-by-default response headers plus a small declarative per-path
+ * header config (issue #232).
+ *
+ * webjs sets a baseline of standard security headers on every document
+ * and asset response, so a scaffolded app is not clickjackable or
+ * MIME-sniffable out of the box (no reverse proxy required for the
+ * baseline). The defaults are LITERAL HTTP headers, no abstraction.
+ *
+ * An app can ADD, OVERRIDE, or DISABLE any header per path via a
+ * declarative config (`package.json` -> `webjs.headers`), shaped like
+ * Next's: an array of `{ source, headers: [{ key, value }] }` where
+ * `source` is a path pattern matched with the native URLPattern API.
+ *
+ * Precedence, lowest to highest:
+ *   1. secure defaults
+ *   2. path config (webjs.headers)        overrides/adds/removes a default
+ *   3. app middleware (already on the Response when we merge)
+ *
+ * In other words middleware wins over the path config, which wins over
+ * the defaults. We only ever ADD a header the response does not already
+ * carry, so a header an app set (in middleware, a route handler, or via
+ * `expose`) is never clobbered. A path-config entry with a null/empty
+ * value REMOVES a header (e.g. drop a default on a public embed route).
+ *
+ * This is the connective tissue #233 (CSP) and #234 (CORS) plug into
+ * later: the merge seam (applySecurityHeaders) is the single place a
+ * future per-path policy layers onto a Response, so neither needs to
+ * touch the response pipeline again.
+ */
+
+/**
+ * Baseline security headers, as literal name -> value pairs. Set only
+ * when absent, so an app override always wins. HSTS is NOT here: it is
+ * conditional (production + HTTPS) and added separately.
+ *
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const SECURE_DEFAULTS = [
+  ['X-Content-Type-Options', 'nosniff'],
+  ['X-Frame-Options', 'SAMEORIGIN'],
+  ['Referrer-Policy', 'strict-origin-when-cross-origin'],
+  ['Permissions-Policy', 'camera=(), microphone=(), geolocation=()'],
+];
+
+/** The standard HSTS posture: two years, include subdomains. */
+const HSTS_VALUE = 'max-age=63072000; includeSubDomains';
+
+/**
+ * Read the per-path header config from the app's package.json
+ * (`webjs.headers`). Returns a normalized array of compiled rules, each
+ * pairing a URLPattern against the configured header directives. A
+ * malformed or absent config yields an empty array (no per-path rules),
+ * never a throw: a broken config must not take the app down.
+ *
+ * Shape consumed:
+ *   "webjs": { "headers": [ { "source": "/embed/:path*",
+ *     "headers": [ { "key": "X-Frame-Options", "value": null } ] } ] }
+ *
+ * A `value` of null, undefined, or false REMOVES the header on a match
+ * (the disable-a-default escape hatch). Any other value is stringified
+ * and SET (override or add).
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>}
+ */
+export function compileHeaderRules(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.headers;
+  if (!Array.isArray(raw)) return [];
+  /** @type {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>} */
+  const rules = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const source = /** @type {any} */ (entry).source;
+    const list = /** @type {any} */ (entry).headers;
+    if (typeof source !== 'string' || !Array.isArray(list)) continue;
+    let pattern;
+    try {
+      // Match on the pathname only. A bare path string is the common
+      // Next-style usage; URLPattern treats it as the pathname component.
+      pattern = new URLPattern({ pathname: source });
+    } catch {
+      continue; // skip an invalid pattern rather than crash the request
+    }
+    /** @type {Array<{ key: string, value: string | null }>} */
+    const directives = [];
+    for (const d of list) {
+      if (!d || typeof d !== 'object') continue;
+      const key = /** @type {any} */ (d).key;
+      if (typeof key !== 'string' || !key) continue;
+      const v = /** @type {any} */ (d).value;
+      // null / undefined / false means REMOVE the header on a match.
+      const value = v === null || v === undefined || v === false ? null : String(v);
+      // Validate the key/value against the real Headers parser at COMPILE
+      // time (consistent with dropping a bad `source`). A name or value
+      // that Headers rejects (an invalid header name, or a value carrying
+      // CR/LF) would otherwise make `applySecurityHeaders` THROW on every
+      // matching request, a self-inflicted 500, which breaks this file's
+      // "a broken config must not take the app down" guarantee. Probe on a
+      // throwaway Headers and DROP the directive if it throws. For a delete
+      // (value null) only the key needs to be a valid header name, so probe
+      // it with a placeholder value.
+      try {
+        new Headers().set(key, value === null ? 'x' : value);
+      } catch {
+        // eslint-disable-next-line no-console
+        console.warn(`[webjs] dropping invalid webjs.headers directive for key "${key}"`);
+        continue;
+      }
+      directives.push({ key, value });
+    }
+    if (directives.length) rules.push({ pattern, directives });
+  }
+  return rules;
+}
+
+/**
+ * Apply the security defaults and the per-path config to a Response,
+ * returning a Response carrying the merged headers. The input Response
+ * is not mutated; a new Headers is derived from it so the body/status
+ * are preserved by reference (no body copy).
+ *
+ * Headers already on the response (set by app middleware, a route
+ * handler, or `expose`) are treated as authoritative and never
+ * overwritten by a default. The per-path config runs AFTER the defaults
+ * but BEFORE that "already present" rule is consulted for middleware:
+ * the config can override a default freely (it is the app's own
+ * declarative intent), while middleware still wins because its headers
+ * are on the response before we are even called.
+ *
+ * @param {Response} res the response produced by the app pipeline
+ * @param {{
+ *   pathname: string,
+ *   https: boolean,
+ *   prod: boolean,
+ *   rules?: Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>,
+ * }} ctx
+ * @returns {Response}
+ */
+export function applySecurityHeaders(res, ctx) {
+  const headers = new Headers(res.headers);
+  // Snapshot the keys the app already set, so a default never clobbers
+  // them. Captured BEFORE we add anything. Lowercased for compare;
+  // Headers itself is case-insensitive.
+  const appSet = new Set();
+  headers.forEach((_v, k) => appSet.add(k.toLowerCase()));
+
+  // 1. Secure defaults: set only if the app did not already set them.
+  for (const [k, v] of SECURE_DEFAULTS) {
+    if (!appSet.has(k.toLowerCase())) headers.set(k, v);
+  }
+  // HSTS only in production AND only over HTTPS (never on a plain-HTTP
+  // hop). Same "do not clobber" rule.
+  if (ctx.prod && ctx.https && !appSet.has('strict-transport-security')) {
+    headers.set('Strict-Transport-Security', HSTS_VALUE);
+  }
+
+  // 2. Per-path config: override / add / remove. Runs over the merged
+  // set so it can replace a default this same call just added. It does
+  // NOT override a header the app set in middleware (appSet), preserving
+  // the middleware-wins precedence.
+  const rules = ctx.rules || [];
+  for (const rule of rules) {
+    if (!rule.pattern.test({ pathname: ctx.pathname })) continue;
+    for (const { key, value } of rule.directives) {
+      if (appSet.has(key.toLowerCase())) continue; // middleware wins
+      // Belt and suspenders: compileHeaderRules already validated the
+      // key/value, so this never throws in practice, but a surprise from a
+      // directive constructed elsewhere must never throw the response
+      // pipeline. Skip the bad directive instead.
+      try {
+        if (value === null) headers.delete(key);
+        else headers.set(key, value);
+      } catch {
+        /* skip a directive the Headers parser rejects */
+      }
+    }
+  }
+
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
+}
+
+/**
+ * Detect whether the original client request was HTTPS, from a web
+ * `Request` (the shape `handle()` works with). Honors the same
+ * reverse-proxy trust posture as `forwarded.js`: read
+ * `X-Forwarded-Proto` only when proxy trust is on
+ * (`WEBJS_NO_TRUST_PROXY !== '1'`); otherwise fall back to the request
+ * URL's scheme. Never trusts the header blindly.
+ *
+ * @param {Request} req
+ * @returns {boolean}
+ */
+export function webRequestIsHttps(req) {
+  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
+  if (trust) {
+    const proto = req.headers.get('x-forwarded-proto');
+    if (proto) return proto.split(',')[0].trim().toLowerCase() === 'https';
+  }
+  try {
+    return new URL(req.url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}

package/src/json.js

@@ -1,6 +1,7 @@
 import { stringify as wjStringify, parse as wjParse } from '@webjsdev/core';
-import { getRequest } from './context.js';
+import { getRequest, getBodyLimits } from './context.js';
 import { RPC_CONTENT_TYPE } from './actions.js';
+import { readTextBounded, BodyLimitError, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 
 /**
  * Content-negotiated JSON helper for API routes (`route.js` handlers).
@@ -51,11 +52,19 @@ export async function json(data, init = {}) {
  * that accept rich bodies from the `richFetch` helper but plain JSON
  * from everyone else.
  *
+ * Enforces the request body-size limit (issue #237): an over-limit body throws
+ * a `BodyLimitError`, which the API dispatcher (`handleApi`) maps to a 413, so a
+ * `route.{js,ts}` handler doing `await readBody(req)` is protected with no extra
+ * code. The over-limit body is never buffered whole (see `readTextBounded`).
+ *
  * @param {Request} req
  */
 export async function readBody(req) {
   const ct = req.headers.get('content-type') || '';
-  const text = await req.text();
+  const limits = getBodyLimits();
+  const limit = limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
+  const { tooLarge, text } = await readTextBounded(req, limit);
+  if (tooLarge) throw new BodyLimitError();
   if (!text) return null;
   if (ct.includes(RPC_CONTENT_TYPE)) return wjParse(text);
   return JSON.parse(text);

package/src/node-version.js

@@ -0,0 +1,102 @@
+/**
+ * Node-version preflight guard (issue #238).
+ *
+ * webjs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
+ * no-build TypeScript strip) and recursive `fs.watch` (dev live-reload). On an
+ * older Node the failure surfaces late and cryptically (a strip error or a
+ * missing API deep inside a request), not as a clear "you need Node 24+". This
+ * module is the single early preflight that fails fast with an actionable
+ * message naming the exact version found and the version required.
+ *
+ * The check is a PURE function (`checkNodeVersion`) so it unit-tests with
+ * injected version strings, no spawning an old Node. `assertNodeVersion` is the
+ * thin side-effecting wrapper the CLI and the server entry both call: it prints
+ * to stderr + exits non-zero (CLI), or throws a clear Error (embedded server),
+ * depending on the `onFail` mode.
+ *
+ * The minimum is sourced from ONE place, this package's own `engines.node`
+ * field, so it never drifts from what npm enforces on install.
+ */
+import { createRequire } from 'node:module';
+
+/**
+ * Parse the leading major-version integer out of a Node version string.
+ * Handles `'24.1.0'`, `'v24.1.0'`, and prerelease tags like
+ * `'24.0.0-nightly20240101'`. Returns `NaN` when no leading integer is found.
+ * @param {string} version
+ * @returns {number}
+ */
+export function parseMajor(version) {
+  const m = String(version).trim().match(/^v?(\d+)/);
+  return m ? Number(m[1]) : NaN;
+}
+
+/**
+ * Parse the minimum major version out of an `engines.node` range like
+ * `'>=24.0.0'`, `'>= 24'`, or `'24.x'`. Returns `NaN` when no integer is found.
+ * @param {string} engines
+ * @returns {number}
+ */
+export function parseRequiredMajor(engines) {
+  const m = String(engines).match(/(\d+)/);
+  return m ? Number(m[1]) : NaN;
+}
+
+/**
+ * Pure version check. Compares the running Node major against the required
+ * minimum and returns a structured result (no side effects).
+ * @param {string} current the running Node version (e.g. `process.versions.node`)
+ * @param {number} requiredMajor the minimum acceptable major version
+ * @returns {{ ok: boolean, current: string, currentMajor: number, requiredMajor: number, message: string }}
+ */
+export function checkNodeVersion(current, requiredMajor) {
+  const currentMajor = parseMajor(current);
+  // If we cannot parse the running version, fail open: do not block a runtime
+  // that reports an unusual version string. The deep APIs guard themselves.
+  const ok = Number.isNaN(currentMajor) || currentMajor >= requiredMajor;
+  const message = ok
+    ? ''
+    : `webjs requires Node ${requiredMajor}+ but found Node ${current}. ` +
+      `webjs is buildless and relies on Node ${requiredMajor}'s built-in ` +
+      `TypeScript strip (module.stripTypeScriptTypes) and recursive fs.watch, ` +
+      `neither of which exists on Node ${currentMajor}. ` +
+      `Upgrade to Node ${requiredMajor} or newer (see https://nodejs.org).`;
+  return { ok, current, currentMajor, requiredMajor, message };
+}
+
+/**
+ * Read the minimum required Node major from this package's own
+ * `engines.node` field, so the minimum lives in exactly one place. Falls back
+ * to 24 if the field is missing or unparseable (defensive only).
+ * @returns {number}
+ */
+export function requiredNodeMajor() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    const major = parseRequiredMajor(pkg?.engines?.node || '');
+    if (!Number.isNaN(major)) return major;
+  } catch {}
+  return 24;
+}
+
+/**
+ * Side-effecting preflight: assert the running Node satisfies the minimum.
+ * On an unsupported Node, either exits the process non-zero (CLI, `onFail:
+ * 'exit'`) or throws a clear Error (embedded server, `onFail: 'throw'`).
+ * A no-op on a supported Node.
+ * @param {{ current?: string, requiredMajor?: number, onFail?: 'exit'|'throw' }} [opts]
+ * @returns {void}
+ */
+export function assertNodeVersion(opts = {}) {
+  const current = opts.current ?? process.versions.node;
+  const requiredMajor = opts.requiredMajor ?? requiredNodeMajor();
+  const onFail = opts.onFail ?? 'throw';
+  const result = checkNodeVersion(current, requiredMajor);
+  if (result.ok) return;
+  if (onFail === 'exit') {
+    console.error(result.message);
+    process.exit(1);
+  }
+  throw new Error(result.message);
+}

package/src/page-action.js

@@ -0,0 +1,225 @@
+import { isNotFound, isRedirect } from '@webjsdev/core';
+import { ssrPage, ssrNotFound, loadModule } from './ssr.js';
+import { readBytesBounded, payloadTooLarge, DEFAULT_MAX_MULTIPART_BYTES } from './body-limit.js';
+import { getBodyLimits } from './context.js';
+
+/**
+ * Page server actions: a `page.{js,ts}` may export an `action` function that
+ * handles a non-GET/HEAD submission to the page's own URL. This is webjs's
+ * Remix-style page-action path, adapted to the no-build progressive-enhancement
+ * model: a `<form method="POST">` submits with JS disabled, the action runs on
+ * the server, and a validation failure re-renders the SAME page with field
+ * errors and the user's typed values preserved.
+ *
+ * Behavior (see #244):
+ *   - Action throws `redirect(url)` or `notFound()` => honored exactly as a page
+ *     render does (3xx / 404). A thrown `redirect()` may target an external URL
+ *     (it is the explicit nav sentinel, author-controlled).
+ *   - Action returns a SUCCESS result => 303 See Other to `result.redirect` if
+ *     present, else to the page's own path (Post/Redirect/Get, so a reload does
+ *     not resubmit). `result.redirect` MUST be a same-site local path (see
+ *     `sameSiteRedirect`), a non-local value is ignored to avoid an
+ *     open-redirect through a user-controlled action result.
+ *   - Action returns a FAILURE result => re-SSR the SAME page (status 422) with
+ *     the result on `ctx.actionData`, so the page template can read
+ *     `actionData.fieldErrors` / `actionData.values` and repopulate inputs.
+ *
+ * Failure detection is robust (it does not require a literal `success: false`):
+ * see `isFailureResult`.
+ *
+ * @typedef {{
+ *   success?: boolean,
+ *   data?: unknown,
+ *   error?: string,
+ *   fieldErrors?: Record<string,string>,
+ *   values?: Record<string,string>,
+ *   status?: number,
+ *   redirect?: string,
+ * }} ActionResult
+ */
+
+/**
+ * Whether an action result is a FAILURE (re-render the page) rather than a
+ * success (PRG redirect). A result is a failure when ANY of these hold:
+ *   - `result.success === false` (explicit), OR
+ *   - `result.fieldErrors` is present (per-field validation messages), OR
+ *   - `result.error` is present AND `result.success !== true`.
+ *
+ * Success is the explicit `success: true`, or a bare value (or
+ * undefined/null) carrying no error markers. This means an action that returns
+ * `{ error, status }` or `{ fieldErrors }` WITHOUT a literal `success: false`
+ * is still treated as a failure and its error is surfaced, not swallowed.
+ *
+ * @param {ActionResult | null | undefined} result
+ * @returns {boolean}
+ */
+function isFailureResult(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (result.success === false) return true;
+  if (result.fieldErrors != null) return true;
+  if (result.error != null && result.success !== true) return true;
+  return false;
+}
+
+/**
+ * Restrict a page action's `result.redirect` to a SAME-SITE local target.
+ * Allowed: a path beginning with a single `/` (e.g. `/login`, `/a?b=1#c`).
+ * Rejected: a protocol-relative `//host/...` and any absolute `scheme://...`
+ * URL. A user-controlled redirect target is an open-redirect vector, so a
+ * non-local value is dropped and the caller falls back to the page's own path.
+ *
+ * A thrown `redirect(absoluteUrl)` (the nav sentinel) is intentionally NOT
+ * routed through here: that is the author-controlled escape hatch for a
+ * legitimate external redirect.
+ *
+ * @param {unknown} target
+ * @returns {string | null} the safe local path, or null when not same-site
+ */
+function sameSiteRedirect(target) {
+  if (typeof target !== 'string') return null;
+  // Must start with a single slash (a leading `//` is protocol-relative and
+  // would navigate cross-origin).
+  if (!target.startsWith('/') || target.startsWith('//')) return null;
+  // A backslash after the leading slash (`/\evil.com`) is normalized by some
+  // browsers into a protocol-relative URL, so reject it too.
+  if (target.startsWith('/\\')) return null;
+  return target;
+}
+
+/**
+ * Load a page module and return its `action` export, or null if it has none.
+ * Uses ssr.js's shared `loadModule`, so page-action loading is consistent with
+ * the SSR re-render. In prod the URL is stable and Node's module cache serves
+ * one evaluation; in dev a cache-bust forces a fresh evaluation.
+ *
+ * @param {string} file absolute path to the page module
+ * @param {boolean} dev
+ * @returns {Promise<{ action: Function, module: Record<string, unknown> } | null>}
+ */
+export async function loadPageAction(file, dev) {
+  try {
+    const mod = await loadModule(file, dev);
+    return typeof mod.action === 'function'
+      ? { action: /** @type {Function} */ (mod.action), module: mod }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the submitted body ONCE, bounded by the form/multipart limit (issue
+ * #237), and return both a `FormData` (handed to the action as `formData`) and a
+ * rebuilt `Request` carrying the already-read bytes (handed to the action as
+ * `request`, so it can still call `request.json()` / `request.formData()`). The
+ * body is consumed off the ORIGINAL request directly, NOT via `req.clone()`: a
+ * tee'd clone whose reader is cancelled mid-stream (the over-limit case)
+ * deadlocks the untaken branch, hanging the response.
+ *
+ * An over-limit body is reported as `tooLarge` (the caller returns 413) and is
+ * never buffered whole. A form posts more than a JSON RPC call (textarea, small
+ * upload), so it uses the higher `multipart` cap. A non-form content type yields
+ * an empty FormData so the action signature stays stable; the rebuilt request
+ * still carries the raw bytes for the action to parse however it likes.
+ *
+ * @param {Request} req
+ * @returns {Promise<{ tooLarge: boolean, formData: FormData, request: Request }>}
+ */
+async function parseFormBody(req) {
+  const ct = req.headers.get('content-type') || '';
+  const limits = getBodyLimits();
+  const limit = limits ? limits.multipart : DEFAULT_MAX_MULTIPART_BYTES;
+  const { tooLarge, bytes } = await readBytesBounded(req, limit);
+  if (tooLarge) return { tooLarge: true, formData: new FormData(), request: req };
+
+  // Rebuild a fresh Request from the bytes so the action can re-read the body.
+  const headers = new Headers(req.headers);
+  const rebuilt = new Request(req.url, {
+    method: req.method,
+    headers,
+    body: bytes && bytes.byteLength ? bytes : undefined,
+  });
+
+  const isForm = /multipart\/form-data|application\/x-www-form-urlencoded/i.test(ct);
+  let formData = new FormData();
+  if (isForm) {
+    // Parse a SECOND fresh Request (the rebuilt one is reserved for the action).
+    const forParse = new Request(req.url, {
+      method: 'POST',
+      headers: ct ? { 'content-type': ct } : undefined,
+      body: bytes && bytes.byteLength ? bytes : undefined,
+    });
+    formData = await forParse.formData();
+  }
+  return { tooLarge: false, formData, request: rebuilt };
+}
+
+/**
+ * Run a page `action` for a non-GET/HEAD request and produce the HTTP response.
+ * The caller has already confirmed the path matches a page route AND that the
+ * page module exports an `action` (via `loadPageAction`). The action runs inside
+ * the same segment middleware as the page (the caller wraps this).
+ *
+ * The failure re-render reuses the SAME page module instance whose `action` just
+ * ran (passed through as `pageModule`), so the page module is loaded once per
+ * POST rather than evaluated a second time.
+ *
+ * @param {import('./router.js').PageRoute} route
+ * @param {Record<string,string>} params
+ * @param {URL} url
+ * @param {{ action: Function, module: Record<string, unknown> }} loaded the page module's `action` plus the loaded module
+ * @param {Request} req
+ * @param {object} ssrOpts the same opts object `ssrPage` receives in dev.js
+ * @returns {Promise<Response>}
+ */
+export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
+  const { action, module: pageModule } = loaded;
+  const searchParams = Object.fromEntries(url.searchParams.entries());
+  let formData = new FormData();
+  // The body is read ONCE here (bounded). `actionReq` is a rebuilt request the
+  // action can re-read; on a parse failure it falls back to the original `req`.
+  let actionReq = req;
+  try {
+    const parsed = await parseFormBody(req);
+    // Over the form/multipart limit (issue #237): 413 before the action runs.
+    if (parsed.tooLarge) return payloadTooLarge();
+    formData = parsed.formData;
+    actionReq = parsed.request;
+  } catch {
+    formData = new FormData();
+  }
+
+  /** @type {ActionResult | undefined} */
+  let result;
+  try {
+    result = await action({ request: actionReq, params, searchParams, url, formData });
+  } catch (err) {
+    if (isRedirect(err)) {
+      const e = /** @type any */ (err);
+      // A thrown redirect from an action is honored as the page render does.
+      // Use the action's chosen status (307/308) so an explicit redirect()
+      // keeps its semantics; PRG (303) is the SUCCESS-result path below.
+      return new Response(null, { status: e.status || 307, headers: { location: e.url } });
+    }
+    if (isNotFound(err)) {
+      return ssrNotFound(ssrOpts.notFoundFile ?? null, { ...ssrOpts, req, url });
+    }
+    throw err;
+  }
+
+  if (!isFailureResult(result)) {
+    // SUCCESS: Post/Redirect/Get. A user-controlled `result.redirect` is only
+    // honored when it is a same-site local path; otherwise fall back to the
+    // page's own path so a poisoned value cannot become an open redirect.
+    const ownPath = (url.pathname + url.search) || '/';
+    const safe = result ? sameSiteRedirect(result.redirect) : null;
+    return new Response(null, { status: 303, headers: { location: safe || ownPath } });
+  }
+
+  // FAILURE: re-render the SAME page with the action result available on
+  // ctx.actionData, status 422. Repopulation is the page author's job (native
+  // `value=${actionData.values?.field}`). Pass the already-loaded page module so
+  // the re-render shares this POST's single evaluation.
+  const status = typeof result.status === 'number' && result.status >= 400 ? result.status : 422;
+  return ssrPage(route, params, url, { ...ssrOpts, req, actionData: result, status, pageModule });
+}