@webjsdev/server 0.8.58 → 0.8.60

package/src/forwarded.js

@@ -12,13 +12,38 @@
  * breaks OG / og:image tags, OAuth callback URLs, and any user code
  * that builds absolute URLs.
  *
- * Threat model: in webjs's typical deployment topology, the
- * container's HTTP port is only reachable through the trusted edge
- * proxy. There's no path for an attacker to inject these headers
- * without going through that proxy. For self-hosted bare-VM deploys
- * where the container is somehow directly exposed, set
- * `WEBJS_NO_TRUST_PROXY=1` to fall back to the raw `Host` header and
- * `http://` default.
+ * Threat model: the two headers have DIFFERENT trust properties, so do
+ * not reason about them as one.
+ *
+ * `X-Forwarded-Proto` is written by the proxy that terminates TLS, which
+ * OVERWRITES whatever the client sent. In WebJs's typical deployment
+ * topology the container's HTTP port is only reachable through that
+ * trusted edge, so the value this code reads is the edge's, not the
+ * client's. The guarantee is the overwrite, not the topology: an edge
+ * that APPENDS instead would put the client's entry first in the chain,
+ * and the comma rule below takes the first entry.
+ *
+ * `X-Forwarded-Host` is NOT covered by that argument. Cloudflare and
+ * Railway FORWARD a client-supplied `X-Forwarded-Host` rather than
+ * overwriting it, so going through the trusted proxy is exactly how a
+ * hostile value arrives. Treat a forged forwarded host as reachable in
+ * the NORMAL topology, not just on a directly-exposed container.
+ * Consequence, and the rule to apply to your own code: anything SHARED
+ * that is derived from the resulting origin must be KEYED by that origin
+ * rather than assumed constant. That is what `html-cache.js` does, folding
+ * `url.origin` into every cache key (#1097), after a single request
+ * carrying a hostile host could poison a `revalidate` page for every
+ * later visitor.
+ *
+ * `WEBJS_NO_TRUST_PROXY=1` makes THIS module ignore both headers and
+ * fall back to the raw `Host` header and the `http://` default. It is
+ * the remedy for a directly-exposed container, and it also narrows the
+ * forwarded-host exposure above, so it is not only a bare-VM concern.
+ * That switch is `trustProxy()` below, and it is now the ONE place the
+ * posture is decided: `csrf.js`'s `requestHost` used to read
+ * `x-forwarded-host` without consulting it, which is what #1104
+ * centralized. See `trustProxy()` for the full consumer list and for the
+ * direction rule that resolves it against the per-call `trustProxy` option.
  *
  * Header semantics:
  * - `X-Forwarded-Host` / `X-Forwarded-Proto` can be a comma-separated
@@ -163,16 +188,49 @@ export function applyForwarded(url, headers) {
   return origin;
 }
 
+/**
+ * Is a reverse proxy in front of this process trusted to speak for the client?
+ *
+ * The ONE place the ORIGIN posture is decided (#1104): every reader of the
+ * forwarded HOST and PROTO goes through this, namely the URL rewrite here, the
+ * HSTS scheme gate in `headers.js`, and the CSRF host resolution in `csrf.js`.
+ * It used to be three separate reads with two different answers, so
+ * `WEBJS_NO_TRUST_PROXY=1` turned off two of them and an operator could not
+ * tell from any single file whether their app trusted forwarded headers.
+ *
+ * SCOPE: `clientIp` in `rate-limit.js` is a consumer too (#1254), so the switch
+ * now covers every forwarded-header read in the package, the client-IP ones
+ * (`x-forwarded-for` / `cf-connecting-ip` / `x-real-ip`) included. The name
+ * collision is still real: `trustProxy()` here is env-backed and package-wide,
+ * `trustProxy` there is a per-call boolean. They point the same direction, and
+ * the DIRECTION RULE is what resolves them. This switch only ever SUBTRACTS
+ * trust; the per-call option can only add it while this switch is unset. So
+ * `rateLimit({ trustProxy: true })` under `WEBJS_NO_TRUST_PROXY=1` resolves to
+ * the framework-stamped peer, because an env switch that two subsystems honour
+ * and one ignores cannot tell an operator their posture, and because the
+ * failure mode of an over-firing override is a shared bucket (visible,
+ * self-inflicted) rather than a limiter keyed on a header the client chooses.
+ *
+ * Read from `process.env` at CALL time, never cached at boot, so a test (and a
+ * runtime that mutates its own env) can toggle it per case.
+ *
+ * @returns {boolean}
+ */
+export function trustProxy() {
+  return process.env.WEBJS_NO_TRUST_PROXY !== '1';
+}
+
 /**
  * Read the forwarded host / proto through a header getter, honoring the
- * `WEBJS_NO_TRUST_PROXY=1` opt-out. The one place the trust decision and the
- * comma-chain rule live, shared by the node and Bun entry points above.
+ * `trustProxy()` opt-out. The one place the HEADER SHAPE rules (the
+ * comma-chain, the scheme allowlist) live, shared by the node and Bun entry
+ * points above.
  *
  * @param {(name: string) => string | string[] | undefined | null} getHeader
  * @returns {{ host: string | null, proto: string | null }}
  */
 function readForwarded(getHeader) {
-  if (process.env.WEBJS_NO_TRUST_PROXY === '1') return { host: null, proto: null };
+  if (!trustProxy()) return { host: null, proto: null };
   return {
     host: firstHeaderValue(getHeader('x-forwarded-host')),
     proto: normalizeProto(firstHeaderValue(getHeader('x-forwarded-proto'))),

package/src/headers.js

@@ -29,6 +29,8 @@
  * touch the response pipeline again.
  */
 
+import { trustProxy } from './forwarded.js';
+
 /**
  * Baseline security headers, as literal name -> value pairs. Set only
  * when absent, so an app override always wins. HSTS is NOT here: it is
@@ -190,18 +192,18 @@ export function applySecurityHeaders(res, ctx) {
 
 /**
  * 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.
+ * `Request` (the shape `handle()` works with). Reads `X-Forwarded-Proto`
+ * only when `trustProxy()` says a proxy speaks for the client; otherwise
+ * falls back to the request URL's scheme. Never trusts the header blindly.
+ *
+ * The posture comes from `forwarded.js` rather than an inline `process.env`
+ * read (#1104), so this gate cannot drift from the URL rewrite it shadows.
  *
  * @param {Request} req
  * @returns {boolean}
  */
 export function webRequestIsHttps(req) {
-  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
-  if (trust) {
+  if (trustProxy()) {
     const proto = req.headers.get('x-forwarded-proto');
     if (proto) return proto.split(',')[0].trim().toLowerCase() === 'https';
   }

package/src/html-cache.js

@@ -27,8 +27,9 @@
 import { getStore } from './cache.js';
 import { STREAM_MARKER } from './conditional-get.js';
 import { createHash } from 'node:crypto';
-import { publishedBuildId } from './importmap.js';
-import { dynamicAccessed } from './context.js';
+import { publishedBuildId, basePath } from './importmap.js';
+import { stripBasePath } from './base-path.js';
+import { dynamicAccessed, getRequest } from './context.js';
 
 /** Namespace prefix for every cached-HTML key, so a flush can target it. */
 const KEY_PREFIX = 'webjs:html:';
@@ -109,11 +110,37 @@ export function readRevalidate(pageModule) {
 }
 
 /**
- * The cache key for a request: the FULL URL (path + search string), since
- * `searchParams` change page output. Normalized to path + sorted query so
- * `?a=1&b=2` and `?b=2&a=1` share an entry. Two more discriminators are
- * folded into the namespace:
+ * The origin component of a cache key. `url.origin` is already the normalized
+ * lowercase `scheme://host[:port]` form for an http(s) URL; a non-special
+ * scheme serializes to the literal string `null`, which is a fine constant key
+ * component (such a URL never reaches a cacheable page render anyway).
  *
+ * @param {URL} url
+ * @returns {string}
+ */
+function originKey(url) {
+  return url.origin;
+}
+
+/**
+ * The cache key for a request: the ORIGIN plus the full path + search string,
+ * since both `ctx.url.origin` and `searchParams` change page output.
+ * Normalized to path + sorted query so `?a=1&b=2` and `?b=2&a=1` share an
+ * entry. Four discriminators are folded into the namespace:
+ *
+ *  - the origin (#1097). This cache is SHARED across visitors, and `ctx.url`
+ *    is built from `X-Forwarded-Host` / `X-Forwarded-Proto`, which neither
+ *    Cloudflare nor Railway strips from a client request. Without the origin
+ *    in the key, one request carrying `X-Forwarded-Host: evil.example` baked
+ *    an attacker-chosen origin into the shared body, and every later visitor
+ *    to that path was served it until the entry expired: a poisoned
+ *    `og:image`, canonical link, OAuth callback URL, or absolute asset URL.
+ *    With the origin in the key, a clean request resolves its origin from the
+ *    proxy-set `Host` and reads its OWN entry, so the hostile body is
+ *    unreachable from any origin an attacker does not already control. A
+ *    single-host deploy has exactly one origin and so exactly one key per URL,
+ *    unchanged hit rate; a genuine multi-host deploy gets correctly separated
+ *    entries instead of cross-serving one host's HTML to another;
  *  - the in-process generation, so `revalidateAll()` (a generation bump)
  *    makes every prior key unreachable in one step;
  *  - the published build id (the importmap fingerprint), so a NEW DEPLOY
@@ -143,7 +170,7 @@ export function htmlCacheKey(url) {
   // the importmap-only build id misses. Empty (dev / no fingerprint) collapses
   // to the prior key shape, so an unconfigured app is byte-identical.
   const appfp = _appSourceFp ? `${_appSourceFp}:` : '';
-  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${url.pathname}${search}`;
+  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${originKey(url)}:${url.pathname}${search}`;
 }
 
 /**
@@ -221,17 +248,59 @@ export function isCacheableResponse(res, guards = {}) {
  * ONLY the no-query entry; pass the exact `path?query` to target a
  * specific query variant, or call `revalidateAll()` to clear everything.
  *
- * @param {string} path  e.g. '/blog' or '/blog?page=2'
+ * ORIGIN RESOLUTION (#1097). Cache keys carry the request's origin, so a bare
+ * path does not name one entry, it names one per origin the path was cached
+ * under. Two forms resolve it:
+ *
+ *  1. The CURRENT request's origin, when one is ambient. A mutation runs inside
+ *     the request of the user who triggered it, and that user is on the same
+ *     origin as the pages being evicted, so a bare path is exact for the
+ *     ordinary "server action writes, then evicts" flow, which is every
+ *     in-repo example and everything the docs show.
+ *  2. An ABSOLUTE url (`https://app.example/blog`) names its origin outright.
+ *     This is the form for a caller with NO ambient request: a cron job, a
+ *     queue worker, an `instrumentation.js` timer. Under `webjs.basePath` pass
+ *     the PUBLIC url and the mount prefix is stripped for you, so it keys the
+ *     same entry the write stored.
+ *
+ * A bare path with no ambient request cannot be resolved and WARNS ONCE naming
+ * the path, rather than silently evicting nothing.
+ *
+ * There is deliberately no process-local registry of "origins seen so far"
+ * standing in for case 2. The origin comes from `X-Forwarded-Host`, which is
+ * client-supplied and forwarded rather than stripped (the whole premise of
+ * #1097), so such a registry is attacker-writable: a flood of hostile hosts
+ * against a cold process either fills a bounded registry before the real origin
+ * is ever seen, or grows an unbounded one. Either way eviction silently stops
+ * working, which is worse than the explicit contract above.
+ *
+ * @param {string} path  e.g. '/blog', '/blog?page=2', or 'https://app.example/blog'
  * @returns {Promise<void>}
  */
 export async function revalidatePath(path) {
   if (typeof path !== 'string' || !path) return;
-  // Build the same normalized key readHtmlCache / writeHtmlCache produce.
   let url;
-  try {
-    url = new URL(path, 'http://internal.invalid');
-  } catch {
-    return;
+  if (/^https?:\/\//i.test(path)) {
+    try { url = new URL(path); } catch { return; }
+    // An absolute url is the PUBLIC one, so under `webjs.basePath` it carries
+    // the mount prefix. Cache entries key on the app-root-relative path (the
+    // write strips it in dev.js for exactly this reason), so strip it here too
+    // or the caller who was told to use this form, the one with no ambient
+    // request, computes a key nothing was ever stored under. A path that is
+    // not under the base path is left alone, matching the write's behaviour.
+    const base = basePath();
+    if (base) {
+      const stripped = stripBasePath(url.pathname, base);
+      if (stripped !== null) url.pathname = stripped;
+    }
+  } else {
+    const origin = ambientOrigin();
+    if (!origin) {
+      warnUnresolvedOriginOnce(path);
+      return;
+    }
+    // Build the same normalized key readHtmlCache / writeHtmlCache produce.
+    try { url = new URL(path, origin); } catch { return; }
   }
   try {
     await getStore().delete(htmlCacheKey(url));
@@ -240,6 +309,41 @@ export async function revalidatePath(path) {
   }
 }
 
+/**
+ * The current request's origin, or '' when there is no ambient request. Never
+ * throws: an eviction helper must not take down the mutation that called it.
+ *
+ * @returns {string}
+ */
+function ambientOrigin() {
+  try {
+    const req = getRequest();
+    return req ? new URL(req.url).origin : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Paths already warned about an unresolvable bare-path eviction, so the warning
+ * fires once per offending path rather than once per invocation.
+ * @type {Set<string>}
+ */
+const _warnedUnresolvedPaths = new Set();
+
+/** @param {string} path */
+function warnUnresolvedOriginOnce(path) {
+  if (_warnedUnresolvedPaths.has(path)) return;
+  _warnedUnresolvedPaths.add(path);
+  console.warn(
+    `[webjs] revalidatePath(${JSON.stringify(path)}) evicted nothing: HTML cache ` +
+    `keys carry the request origin, and this call has no ambient request to take ` +
+    `one from (a cron job, a queue worker, a boot-time timer). Pass an absolute ` +
+    `url instead, e.g. revalidatePath('https://your-host${path.startsWith('/') ? path : '/' + path}'), ` +
+    `or call it from a server action, where the triggering request supplies the origin.`
+  );
+}
+
 /**
  * Response-funnel step (#241): if the response carries the HTML_CACHE_MARKER
  * (the SSR opted it into caching), re-check every guard against the FINAL

package/src/js-scan.js

@@ -632,28 +632,46 @@ export function matchClosingParenthesis(s, start) {
  * `}` inside `'…'`, `"…"`, or backtick templates don't decrement depth.
  * Returns -1 if no balanced brace is found.
  *
+ * A template hole is a CODE context nested inside a template, not a brace in
+ * the enclosing block, so it gets its own frame on the stack: `${` pushes,
+ * and the `}` that returns that frame to depth zero pops back into the
+ * template rather than counting toward the block being matched. An earlier
+ * version incremented the outer depth at `${` and then never decremented it
+ * (the closing `}` arrived while still in template state), so depth could
+ * never return to zero and a class body holding `` html`…${x}…` `` was
+ * unmatchable. Every caller passes a masked source in which holes are already
+ * blanked, so the bug is invisible until one passes raw source.
+ *
  * @param {string} s
  * @param {number} start
  */
 export function matchClosingBrace(s, start) {
-  let depth = 1;
+  // Innermost first. `tpl` frames are template literals (no brace counting);
+  // `!tpl` frames are code, each with its own depth.
+  /** @type {Array<{ tpl: boolean, depth: number }>} */
+  const stack = [{ tpl: false, depth: 1 }];
   let i = start;
-  let str = ''; // '', "'", '"', or backtick
   while (i < s.length) {
+    const top = stack[stack.length - 1];
     const c = s[i];
-    if (str) {
+    if (top.tpl) {
       if (c === '\\') { i += 2; continue; }
-      if (c === str) str = '';
-      else if (str === '`' && c === '$' && s[i + 1] === '{') {
-        // template hole, count its closing `}` toward our brace depth.
-        depth++;
-        i += 2;
-        continue;
-      }
+      if (c === '`') { stack.pop(); i++; continue; }
+      if (c === '$' && s[i + 1] === '{') { stack.push({ tpl: false, depth: 1 }); i += 2; continue; }
       i++;
       continue;
     }
-    if (c === "'" || c === '"' || c === '`') { str = c; i++; continue; }
+    if (c === "'" || c === '"') {
+      i++;
+      while (i < s.length) {
+        if (s[i] === '\\') { i += 2; continue; }
+        const d = s[i];
+        i++;
+        if (d === c || d === '\n') break;   // closed, or unterminated at EOL
+      }
+      continue;
+    }
+    if (c === '`') { stack.push({ tpl: true, depth: 0 }); i++; continue; }
     if (c === '/' && s[i + 1] === '/') { // line comment
       while (i < s.length && s[i] !== '\n') i++;
       continue;
@@ -664,8 +682,18 @@ export function matchClosingBrace(s, start) {
       i += 2;
       continue;
     }
-    if (c === '{') depth++;
-    else if (c === '}') { depth--; if (depth === 0) return i; }
+    if (c === '{') { top.depth++; i++; continue; }
+    if (c === '}') {
+      top.depth--;
+      // Depth zero closes this frame: the outermost one is the answer, an inner
+      // one is a template hole ending and hands control back to its template.
+      if (top.depth === 0) {
+        if (stack.length === 1) return i;
+        stack.pop();
+      }
+      i++;
+      continue;
+    }
     i++;
   }
   return -1;

package/src/listener-bun.js

@@ -154,7 +154,7 @@ export function startBunListener(ctx) {
   const shutdown = makeShutdown({ closeServer, hub, logger });
   process.once('SIGINT', () => shutdown('SIGINT'));
   process.once('SIGTERM', () => shutdown('SIGTERM'));
-  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
 
   return {
     server,

package/src/listener-core.js

@@ -383,7 +383,7 @@ export class SseHub {
  * Install once-only process error handlers. Idempotent across multiple
  * `startServer` calls in the same process. Runtime-neutral (plain `process.on`).
  * @param {import('./logger.js').Logger} logger
- * @param {() => void} onFatal
+ * @param {() => void} onFatal Starts the FATAL shutdown, which exits non-zero.
  */
 export function installProcessHandlers(logger, onFatal) {
   if (/** @type any */ (globalThis).__webjsProcHandlers) return;
@@ -405,12 +405,37 @@ export function installProcessHandlers(logger, onFatal) {
  * `closeServer()` thunk that resolves once the server has stopped accepting
  * connections (node `server.close`, Bun `server.stop(true)`). Closes the SSE hub,
  * then drains, then exits; hard-exits after 10s if the drain hangs.
+ *
+ * Exit code, in full. Three things can force a 1, and only their absence
+ * leaves a 0:
+ *   - a drain that FAILS, so a rejected `closeServer()` and a drain still
+ *     hanging at the 10s deadline both exit 1 whatever started them;
+ *   - a FATAL start (the `uncaughtException` handler calling `onFatal`), which
+ *     exits 1 even when the drain is perfectly clean;
+ *   - a FATAL arriving MID-DRAIN, which upgrades a shutdown an operator signal
+ *     had already begun (see the upgrade-only note on `code` below).
+ * So 0 does NOT mean "a signal started it", it means an operator asked for the
+ * stop AND it drained cleanly AND nothing crashed on the way out. A supervisor
+ * reads only this code (systemd `Restart=on-failure`, Docker, Railway, and a CI
+ * step running a `test/bun/*.mjs` proof script, whose failed top-level assertion
+ * arrives here as an uncaught exception, #1092), so every one of those has to
+ * come back non-zero.
  * @param {{ closeServer: () => Promise<unknown>, hub: SseHub, logger: import('./logger.js').Logger }} opts
- * @returns {(signal: string) => void}
+ * @returns {(signal: string, opts?: { fatal?: boolean }) => void}
  */
 export function makeShutdown({ closeServer, hub, logger }) {
   let shuttingDown = false;
-  return (signal) => {
+  // Read at EXIT time, not at entry, so a fatal arriving mid-drain still counts.
+  // The drain window is up to 10s wide and in-flight requests are still running
+  // in it, so an uncaught exception landing there is an ordinary event, not an
+  // exotic race. Because the re-entrancy guard below drops that second call, a
+  // code captured at entry would stay 0 and the crashed process would report a
+  // successful stop, which is the exact failure this whole mechanism exists to
+  // prevent. Upgrade only (1 never falls back to 0), so a signal arriving during
+  // a fatal shutdown cannot launder the crash into a success either.
+  let code = 0;
+  return (signal, { fatal = false } = {}) => {
+    if (fatal) code = 1;
     if (shuttingDown) return;
     shuttingDown = true;
     logger.info(`received ${signal}, shutting down`);
@@ -420,11 +445,16 @@ export function makeShutdown({ closeServer, hub, logger }) {
       process.exit(1);
     }, 10_000);
     if (typeof hard.unref === 'function') hard.unref();
+    // Disarm before exiting. In production `process.exit` ends everything so this
+    // is redundant, but it keeps the deadline from outliving the decision it was
+    // guarding, which is what let a stubbed-exit test leave a live timer armed to
+    // kill an unrelated process 10s later.
+    const done = (c) => { clearTimeout(hard); process.exit(c); };
     Promise.resolve()
       .then(closeServer)
       .then(
-        () => { logger.info('bye'); process.exit(0); },
-        (err) => { logger.error('server close error', { err: String(err) }); process.exit(1); },
+        () => { logger.info('bye'); done(code); },
+        (err) => { logger.error('server close error', { err: String(err) }); done(1); },
       );
   };
 }

package/src/rate-limit.js

@@ -23,6 +23,14 @@
  */
 
 import { getStore } from './cache.js';
+// Aliased on purpose. `rateLimit()` binds a local `const trustProxy` from its
+// own options, which would shadow a same-named import inside that function and
+// leave the middleware path on the pre-override behaviour while the direct
+// `clientIp` path changed. `forwarded.js` imports nothing, so this adds no cycle.
+import { trustProxy as proxyIsTrusted } from './forwarded.js';
+
+/** Module-scope latch so the override warns once per process, never per request. */
+let warnedProxyOverride = false;
 
 /**
  * @param {{
@@ -126,8 +134,8 @@ function trustedRemoteIp(req) {
 
 /**
  * Carry the trusted remote IP from `src` to a freshly-rebuilt `dst` Request
- * (#756). When the framework re-wraps a request (the page-action body rebuild in
- * `page-action.js`), the out-of-band WeakMap key is a new object, so the trusted
+ * (#756). When the framework re-wraps a request (the form-submission body rebuild
+ * in `form-dispatch.js`), the out-of-band WeakMap key is a new object, so the trusted
  * IP would be lost and `clientIp(dst)` would fall back to the (spoofable) header
  * the rebuild copied over. Propagating the trusted value via the WeakMap keeps
  * `dst` authoritative on BOTH runtimes (it reads `trustedRemoteIp(src)`, which is
@@ -167,12 +175,32 @@ export function propagateTrustedRemoteIp(src, dst) {
  * trust-proxy reintroduces the spoofability this option exists to
  * defend against.
  *
+ * `WEBJS_NO_TRUST_PROXY=1` OVERRIDES `trustProxy: true` (#1254). The env
+ * switch is the operator's statement about the deployment topology and it can
+ * only ever SUBTRACT trust, so when it is set this call falls back to the
+ * default path above: the framework-stamped peer, or `_anon_` when there is
+ * none, and never a forwarded-IP header. The override logs once per process.
+ * An app that genuinely sits behind a trusted proxy must unset the flag; the
+ * two settings answer the same question about one socket and one topology, so
+ * leaving them in disagreement buckets every visitor behind that proxy onto
+ * one key.
+ *
  * @param {Request} req
  * @param {{ trustProxy?: boolean }} [opts]
  * @returns {string}
  */
 export function clientIp(req, opts = {}) {
-  if (opts.trustProxy === true) {
+  if (opts.trustProxy === true && !proxyIsTrusted() && !warnedProxyOverride) {
+    warnedProxyOverride = true;
+    // No request data in this line, ever. It must not become a log of
+    // client-supplied header values.
+    console.warn(
+      '[webjs] WEBJS_NO_TRUST_PROXY=1 overrides trustProxy: true; ' +
+        'forwarded-IP headers are ignored and the framework-stamped peer is used. ' +
+        'Unset the env var if a trusted proxy really is in front of this process.',
+    );
+  }
+  if (opts.trustProxy === true && proxyIsTrusted()) {
     return (
       req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
       req.headers.get('cf-connecting-ip') ||

package/src/route-types.js

@@ -11,7 +11,7 @@
  * Design choices:
  *   - PAGES ONLY. A `route.{js,ts}` handler is an API endpoint, not a
  *     navigable HTML page, so its path is excluded from the navigable `Route`
- *     union. Pages (including page-action pages) are what a valid href points
+ *     union. Pages (including ones hosting a bound form) are what a valid href points
  *     at.
  *   - The route KEY is the literal pattern (`/blog/[slug]`), derived from the
  *     page's directory with route groups `(group)` stripped and `_private`