@webjsdev/server 0.8.56 → 0.8.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.56",
+  "version": "0.8.58",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/core": "^0.7.1",
+    "@webjsdev/core": "^0.7.46",
     "ws": "^8.20.0"
   },
   "publishConfig": {

package/src/actions.js

@@ -267,7 +267,7 @@ export function serveServerOnlyStub(relPath) {
     `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
     `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
     `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead. ` +
-    `Docs: https://docs.webjs.dev/docs/server-actions`;
+    `Docs: https://webjs.dev/docs/server-actions`;
   return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
 throw new Error(${JSON.stringify(msg)});
 `;
@@ -563,8 +563,10 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
  * Build a GET action's response (#488): the serialized body plus a weak ETag
  * (content hash), the `Cache-Control` from the `cache` config (else `no-store`),
  * and `X-Webjs-Tags`. Answers `If-None-Match` with a 304 itself rather than
- * relying on the conditional-GET funnel, which EXCLUDES `private` responses (the
- * default here); a per-user browser cache may still revalidate to a 304.
+ * deferring to the conditional-GET funnel: this branch already hashed the
+ * serialized body, so it can answer without the funnel re-reading it. (The
+ * funnel would now accept these too, since #1140 stopped excluding `private`,
+ * but the short-circuit here still runs first and is cheaper.)
  * @param {unknown} result
  * @param {Record<string, unknown>} mod
  * @param {unknown[]} args

package/src/asset-hash.js

@@ -159,10 +159,32 @@ export function assetHashFor(absPath) {
     const bytes = readFileSync(absPath);
     const h = createHash('sha256').update(bytes);
     // An app module's served body is elision-transformed, so fold the verdict
-    // fingerprint in (see `_elisionFp`). Core / public files are never
-    // transformed, so they hash over their bytes alone. Empty fp leaves an app
-    // module's hash at exactly `sha256(bytes)`.
-    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)) {
+    // fingerprint in (see `_elisionFp`). Core and `public/` files are never
+    // transformed, so they hash over their bytes alone, which the two
+    // exclusions below enforce rather than merely assume. Empty fp leaves an
+    // app module's hash at exactly `sha256(bytes)`.
+    //
+    // Both exclusions are EXPLICIT because the containment test alone admits
+    // them, and the intent above is otherwise silently false:
+    //
+    //   - `public/` sits under `_appDir`. Inert while only module specifiers
+    //     reached here, but `asset()` (#1194) routes public paths through this
+    //     function.
+    //   - `_coreDir` sits under `_appDir` too in a REAL install, where it
+    //     resolves to `<appDir>/node_modules/@webjsdev/core`. It escapes only
+    //     in this monorepo, where the workspace symlink lands outside, which
+    //     is exactly why no in-repo test ever caught it.
+    //
+    // Neither file set is elision-transformed (core is served verbatim by
+    // `fileResponse`), so folding the verdict in buys nothing and costs
+    // correctness: any deploy that merely flips an UNRELATED component between
+    // elidable and interactive would move their urls, re-downloading the whole
+    // core runtime plus every marked stylesheet, image, and script even though
+    // not one of those bytes changed. That is the precise cost a content hash
+    // exists to avoid.
+    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)
+        && !absPath.startsWith(join(_appDir, 'public') + sep)
+        && !(_coreDir && absPath.startsWith(_coreDir + sep))) {
       h.update('\0');
       h.update(_elisionFp);
     }
@@ -267,6 +289,46 @@ export function withAssetHash(url, basePath = '') {
   return `${url}${sepChar}v=${hash}`;
 }
 
+/**
+ * Resolve one author-marked asset path to its fingerprinted url. This is the
+ * body behind the isomorphic `asset()` helper (#1194); `dev.js` installs it
+ * via `setAssetUrlProvider` at boot.
+ *
+ * The `public/` gate is defensive, not decorative. `resolveUrlToFile` maps any
+ * same-origin path under the PROJECT ROOT, so an app that passed request- or
+ * user-derived data in (`asset(user.avatarPath)`) would otherwise read and
+ * publish a content hash for `/.env`, `/db/app.db`, or a `.server.ts`, leaking
+ * both that the file exists and a fingerprint of its exact bytes for files the
+ * serve path deliberately 404s. Mirror the static-asset route instead: under
+ * `public/`, no traversal. Anything else returns unchanged WITHOUT touching
+ * the disk, so a rejected path costs nothing and reveals nothing.
+ *
+ * A fragment is split before hashing. `withAssetHash` appends the query, so
+ * passing the whole thing would emit `/x.svg#icon?v=H`: the browser then
+ * requests `/x.svg` with no query (losing the immutable caching this exists
+ * for) and the fragment becomes `icon?v=H`, matching no element id.
+ *
+ * @param {string} p          the author-supplied path
+ * @param {string} [bp]       the active base path
+ * @returns {string}          the fingerprinted url, or `p` unchanged
+ */
+export function resolveAssetUrl(p, bp = '') {
+  if (typeof p !== 'string' || p[0] !== '/' || p[1] === '/') return p;
+  let probe = p;
+  if (bp && probe.startsWith(bp + '/')) probe = probe.slice(bp.length);
+  const cuts = [probe.indexOf('?'), probe.indexOf('#')].filter((i) => i !== -1);
+  let decoded = probe.slice(0, cuts.length ? Math.min(...cuts) : probe.length);
+  try { decoded = decodeURIComponent(decoded); } catch { /* keep raw */ }
+  if (decoded.includes('..') || !decoded.startsWith('/public/')) return p;
+  const h = p.indexOf('#');
+  const path = h === -1 ? p : p.slice(0, h);
+  const frag = h === -1 ? '' : p.slice(h);
+  // An author-supplied query is left alone: it may carry meaning we do not
+  // own, and appending would merge with `&`.
+  if (path.includes('?')) return p;
+  return withAssetHash(path, bp) + frag;
+}
+
 /**
  * Static `import` specifier with positional indices. Mirrors module-graph.js's
  * `IMPORT_RE` (side-effect / default / namespace / named imports), but captures

package/src/conditional-get.js

@@ -10,9 +10,15 @@
  * uniformly.
  *
  * What is EXCLUDED, and why:
- *   - `no-store` / `private` responses (the default for dynamic, per-user
- *     pages). Never enable a cross-session 304 on private content: a shared
- *     cache keyed on the URL could serve one user's validator to another.
+ *   - `no-store` responses (the default for a dynamic page), which forbid
+ *     storage outright, so there is nothing to validate. `private` is NOT
+ *     excluded: it forbids SHARED storage, not validation, and the ETag hashes
+ *     THIS response's body, so two users with different bodies get different
+ *     ETags and neither can match the other's, while two users with identical
+ *     bodies are asking about identical bytes, where a 304 discloses nothing
+ *     (#1140).
+ *     That is what lets the client router's partial responses stay `private`
+ *     without losing their 304s.
  *   - Any body the framework did not positively mark as fully buffered. The
  *     funnel only hashes a response that ALREADY carries an `ETag` (a serve
  *     branch hashed its own bytes) OR carries the internal `X-Webjs-Buffered`
@@ -77,11 +83,28 @@ const STRIP_ON_304 = ['content-length', 'content-encoding', 'content-type'];
 
 /**
  * Is this response cacheable enough to carry a validator?  Cacheable means a
- * 200 whose `Cache-Control` is present and does not forbid storage. A
- * `no-store` or `private` response is excluded (private / per-user content
- * must never get a cross-session 304). `no-cache` is INCLUDED: it means
- * "revalidate before reuse", and a 304 is exactly that revalidation answer,
- * so dev's `no-cache` assets still benefit.
+ * 200 whose `Cache-Control` is present and does not forbid STORAGE. Only
+ * `no-store` is excluded. `no-cache` is INCLUDED: it means "revalidate before
+ * reuse", and a 304 is exactly that revalidation answer, so dev's `no-cache`
+ * assets still benefit.
+ *
+ * `private` is INCLUDED too (#1140). It was excluded on the theory that
+ * per-user content must never get a "cross-session" 304, but that cannot
+ * happen: the ETag is a hash of THIS response's body, and a 304 is returned
+ * only when the client's own `If-None-Match` matches it. Two users with
+ * different bodies get different ETags, so neither can ever match the other's;
+ * two users with identical bodies are asking about identical bytes, where a
+ * 304 is the correct answer and carries no body either way. `private` already
+ * forbids the one real hazard, a SHARED cache storing the response.
+ *
+ * Widening this is what makes #1140's fragment downgrade safe to ship. Before
+ * that change a reduced fragment INHERITED the page's public header, so it
+ * already passed this check and already carried a validator; marking fragments
+ * `private` would have taken that away, and since the router fetches them with
+ * `cache: 'no-cache'` (#1131), every prefetch and soft navigation would have
+ * re-downloaded the whole fragment. The exclusion is dropped rather than
+ * special-cased because it was never justified on its own terms either, per
+ * the reasoning above.
  *
  * @param {Response} res
  * @returns {boolean}
@@ -90,7 +113,7 @@ function isCacheable(res) {
   if (res.status !== 200) return false;
   const cc = res.headers.get('cache-control');
   if (!cc) return false;
-  return !/(?:^|,)\s*(?:no-store|private)\s*(?:,|$)/i.test(cc);
+  return !/(?:^|,)\s*no-store\s*(?:,|$)/i.test(cc);
 }
 
 /**

package/src/dev.js

@@ -93,7 +93,8 @@ import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBa
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
-import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
+import { setAssetUrlProvider } from '@webjsdev/core';
+import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports, resolveAssetUrl } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import {
@@ -624,6 +625,21 @@ export async function createRequestHandler(opts) {
   // id is a stable deploy fingerprint independent of per-file content hashes.
   setAssetRoots({ appDir, coreDir, enabled: !dev });
 
+  // Install the resolver behind the isomorphic `asset()` helper (#1194), the
+  // same provider seam `cspNonce()` uses. An author writes
+  // `href=${asset('/public/app.css')}` and gets the fingerprinted url on the
+  // server; the browser has no provider and returns the path unchanged.
+  //
+  // The `public/` gate is defensive rather than decorative. `resolveUrlToFile`
+  // maps any same-origin path under the PROJECT ROOT, so an app that passed
+  // request- or user-derived data here (`asset(user.avatarPath)`) would
+  // otherwise read and publish a content hash for `/.env`, `/db/app.db`, or a
+  // `.server.ts`, leaking both existence and a fingerprint of the bytes for
+  // files the serve path deliberately 404s. Mirror the static-asset route:
+  // under `public/`, no traversal. Everything else returns unchanged, having
+  // never touched the disk.
+  setAssetUrlProvider((p) => resolveAssetUrl(p, basePath()));
+
   // SSR action-result seeding (#472). Install the process-global module load
   // hook NOW, at boot, before any `'use server'` action module is imported (ESM
   // caches by URL, so a module loaded before the hook would never be faceted).
@@ -1263,8 +1279,9 @@ export async function createRequestHandler(opts) {
       // into a 304 Not Modified with no body. Applied LAST, after every header
       // (X-Webjs-Build, X-Request-Id, Set-Cookie, CSP) is on the response, so a
       // 304 carries the validators a shared cache and the client router need.
-      // A no-store / per-user response, a non-GET/HEAD, and a streaming Suspense
-      // body are all skipped (see conditional-get.js). Logged with the final
+      // A no-store response, a non-GET/HEAD, and a streaming Suspense body are
+      // all skipped (see conditional-get.js). A `private` response is NOT
+      // skipped: private forbids shared storage, not validation (#1140). Logged with the final
       // (possibly 304) status. Best-effort: a failure leaves the 200 untouched.
       let conditioned = merged;
       try {
@@ -2259,21 +2276,40 @@ async function runWithSegmentMiddleware(req, files, terminal, dev) {
 }
 
 /**
- * Load the optional top-level `middleware.js`.
+ * Root-middleware filename candidates, in resolution order.
+ *
+ * Every other routing convention accepts all four extensions (the router
+ * matches on the STEM, so `app/<segment>/middleware.ts` has always worked),
+ * and both the scaffold and the dev supervisor write / watch `middleware.ts`.
+ * This lookup used to be the single literal `middleware.js`, so a root
+ * `middleware.ts` was silently never loaded: no error, no warning, the app
+ * just ran with no global middleware. TypeScript is the documented default
+ * for an app, so that was the common case, and it went unnoticed because the
+ * failure is invisible (a missing middleware looks exactly like an app that
+ * has none). `.ts` is tried first to match the dev supervisor's order.
+ */
+const ROOT_MIDDLEWARE_FILES = ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs'];
+
+/**
+ * Load the optional top-level `middleware.{ts,js,mts,mjs}`.
  * @param {string} appDir
  * @param {boolean} dev
  * @param {import('./logger.js').Logger} logger
  */
 async function loadMiddleware(appDir, dev, logger) {
-  const file = join(appDir, 'middleware.js');
-  if (!(await exists(file))) return null;
+  let file = null;
+  for (const name of ROOT_MIDDLEWARE_FILES) {
+    const candidate = join(appDir, name);
+    if (await exists(candidate)) { file = candidate; break; }
+  }
+  if (!file) return null;
   const url = pathToFileURL(file).toString();
   const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
   try {
     const mod = await import(url + bust);
     return typeof mod.default === 'function' ? mod.default : null;
   } catch (e) {
-    logger.error('failed to load middleware.js', { err: String(e) });
+    logger.error('failed to load root middleware', { file, err: String(e) });
     return null;
   }
 }
@@ -2575,7 +2611,7 @@ async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDevError)
           `Replace enum / namespace / parameter-property / legacy-decorator / ` +
           `import = require constructs with their erasable equivalents. ` +
           `Run \`webjs check\` for guidance (no-non-erasable-typescript rule). ` +
-          `Docs: https://docs.webjs.dev/docs/typescript`
+          `Docs: https://webjs.dev/docs/typescript`
         // Prod: terse, no path leak, no Node-message leak (Node's
         // message can include source snippets). Operators get the
         // detail in server logs above.

package/src/forwarded.js

@@ -32,23 +32,178 @@
  * @returns {URL}
  */
 export function urlFromRequest(req) {
-  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
-  let host = null;
-  let proto = null;
-  if (trust) {
-    host = firstHeaderValue(req.headers['x-forwarded-host']);
-    proto = firstHeaderValue(req.headers['x-forwarded-proto']);
+  const { host, proto } = readForwarded((n) => /** @type {any} */ (req.headers)[n]);
+  const rawHost = /** @type {string|undefined} */ (req.headers.host) || '';
+  const u = resolveOrigin(proto || 'http', host, rawHost);
+  // Assign the request target's parts rather than RESOLVING it against `u`.
+  // Resolving is unsafe: a request line may carry `//evil.com/x`, a
+  // scheme-relative reference, so `new URL('//evil.com/x', 'https://real-host')`
+  // resolves to `https://evil.com/x`, handing over the origin AND silently
+  // rewriting the path to `/x` so a different route matches. A request target
+  // is a path, never a full reference, so it is assigned as one.
+  const m = /^([^?#]*)(\?[^#]*)?(#.*)?$/.exec(req.url || '/');
+  u.pathname = (m && m[1]) || '/';
+  u.search = (m && m[2]) || '';
+  u.hash = (m && m[3]) || '';
+  return u;
+}
+
+/**
+ * Build the origin both entry points agree on, as an origin-only URL.
+ *
+ * Sharing this is what keeps the ORIGIN decision identical across the two
+ * shells rather than a coincidence of two similar-looking expressions. The
+ * layering matters: start from a known-good placeholder, apply the raw `Host`,
+ * then let the forwarded host override it. Each assignment goes through
+ * `setHost`, which ignores a value it cannot parse, so a junk header falls back
+ * to the previous layer rather than 500ing the request or collapsing to
+ * localhost.
+ *
+ * @param {string} proto  http / https. `normalizeProto` guarantees it for a
+ *   forwarded value; the callers' fallbacks pass the url's own scheme, which is
+ *   http or https for any request a listener shell can receive.
+ * @param {string | null} forwardedHost
+ * @param {string} rawHost  the `Host` header
+ * @returns {URL} an origin-only URL
+ */
+function resolveOrigin(proto, forwardedHost, rawHost) {
+  const u = new URL(`${proto}://localhost`);
+  if (rawHost) setHost(u, rawHost);
+  if (forwardedHost) setHost(u, forwardedHost);
+  return u;
+}
+
+/**
+ * Assign an authority, clearing any port the previous layer left behind.
+ *
+ * The `host` setter only updates the port when the new value CARRIES one, so
+ * layering `X-Forwarded-Host: docs.webjs.dev` over `Host: container:3000`
+ * otherwise yields `docs.webjs.dev:3000`: the public hostname wearing the
+ * internal port. Clearing first makes each layer a full replacement.
+ *
+ * @param {URL} u
+ * @param {string} value
+ */
+function setHost(u, value) {
+  let probe;
+  try {
+    probe = new URL(`${u.protocol}//${value}`);
+  } catch {
+    // Not a parseable authority (`a b`, `[`, a port over 65535). Leave the
+    // previous layer in place rather than throwing, so a junk header is never a
+    // 500 on the fetch path or a failed WS handshake.
+    return;
   }
-  const finalHost = host || /** @type {string|undefined} */ (req.headers.host) || 'localhost';
-  const finalProto = proto || 'http';
-  return new URL(req.url || '/', `${finalProto}://${finalHost}`);
+  u.hostname = probe.hostname;
+  // Assign the port unconditionally, including the empty string, so a value
+  // carrying no port clears one the previous layer left behind.
+  u.port = probe.port;
+}
+
+/**
+ * Apply the forwarded headers to an ALREADY-PARSED url, for a shell whose
+ * request is a web `Request` (Bun) rather than a node `IncomingMessage`.
+ *
+ * `urlFromRequest` above cannot be reused directly: it reads `req.headers` as a
+ * plain node object, while a web `Request` exposes a `Headers` instance whose
+ * values come from `.get()`. Reusing it against a `Request` silently reads
+ * `undefined` for every header, so it LOOKS wired up while changing nothing.
+ * Both entry points funnel through `readForwarded` (the trust switch, the
+ * allowed schemes, the comma-chain rule) and `resolveOrigin` (the host
+ * layering), so the HEADER and ORIGIN decisions cannot drift. What each shell
+ * RECEIVES still differs: node gets an origin-form request target it treats as
+ * a path, Bun gets a url its own parser already resolved, so an absolute-form
+ * request line routes differently between them. The security-relevant part, the
+ * origin, is decided here for both.
+ *
+ * Returns the SAME URL instance when nothing changes, so the caller can use
+ * identity to skip rebuilding a request on the hot path. That fast path also
+ * requires the url's own authority to already AGREE with the `Host` header:
+ * `Bun.serve` reports an absolute-form request line (`GET http://evil/x`) as
+ * the request's url, so returning early on "no forwarded headers" would let an
+ * unproxied app hand a client full control of `ctx.url.origin`. When they
+ * disagree the origin is rebuilt from `Host` and the client's authority is
+ * discarded. A normal request has `url.host === Host`, so the optimization is
+ * intact for every real request.
+ *
+ * The origin is rebuilt through the shared `resolveOrigin`, and the path parts
+ * are COPIED onto it rather than re-parsed against it. Re-parsing is unsafe:
+ * `url.pathname` for `GET //evil.com/x` is `//evil.com/x`, a scheme-relative
+ * reference, so `new URL('//evil.com/x', 'https://real-host')` resolves to
+ * `https://evil.com/x`. An attacker needed only the `X-Forwarded-Proto` every
+ * TLS-terminating proxy already sets to take over the origin AND silently
+ * change which route matched.
+ *
+ * The host FALLBACK is the `Host` header, not `url.host`, to match
+ * `urlFromRequest` exactly: node builds from the raw header string, so with
+ * `Host: webjs.dev:80` + `X-Forwarded-Proto: https` it judges the `:80` against
+ * https and keeps it. Falling back to the already-normalized `url.host` dropped
+ * it (port 80 is http's default), which made the two shells disagree on the
+ * exact proto-only shape this helper exists for.
+ *
+ * @param {URL} url  the url as the local listener saw it
+ * @param {Headers} headers  the web `Request` headers
+ * @returns {URL} the corrected url, or `url` itself when unchanged
+ */
+export function applyForwarded(url, headers) {
+  const { host, proto } = readForwarded((n) => headers.get(n));
+  const rawHost = headers.get('host') || url.host;
+  if (!host && !proto && url.host === rawHost) return url;
+  // `url.protocol` carries its trailing colon; the forwarded header does not.
+  const origin = resolveOrigin(proto || url.protocol.slice(0, -1), host, rawHost);
+  if (origin.host === url.host && origin.protocol === url.protocol) return url;
+  // Copy the path across verbatim. Never re-parse it against the new origin:
+  // `url.pathname` for `GET //evil.com/x` is `//evil.com/x`, a scheme-relative
+  // reference, so resolving would resolve the authority out of the PATH and
+  // hand an attacker the origin (plus a different matched route) using only the
+  // `X-Forwarded-Proto` every TLS-terminating proxy already sets.
+  origin.pathname = url.pathname;
+  origin.search = url.search;
+  origin.hash = url.hash;
+  return origin;
+}
+
+/**
+ * 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.
+ *
+ * @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 };
+  return {
+    host: firstHeaderValue(getHeader('x-forwarded-host')),
+    proto: normalizeProto(firstHeaderValue(getHeader('x-forwarded-proto'))),
+  };
+}
+
+/**
+ * Accept only `http` / `https` as a forwarded scheme (case-insensitively; the
+ * URL normal form is lowercase, and comparing a raw `HTTPS` against
+ * `url.protocol` otherwise misses the no-op case).
+ *
+ * Anything else is dropped rather than honored. A non-special scheme is the
+ * damaging shape: `X-Forwarded-Proto: javascript` produced
+ * `javascript://host/path`, whose `origin` is the literal string `null`, so
+ * every absolute URL the app derived became `null/...`. A proxy in front of an
+ * HTTP server only ever forwards http or https, so an allowlist costs nothing.
+ *
+ * @param {string | null} p
+ * @returns {string | null}
+ */
+function normalizeProto(p) {
+  if (!p) return null;
+  const v = p.toLowerCase();
+  return v === 'http' || v === 'https' ? v : null;
 }
 
 /**
  * Pick the first comma-separated value from a header that may be a
  * string, an array of strings, or undefined.
  *
- * @param {string | string[] | undefined} h
+ * @param {string | string[] | undefined | null} h
  * @returns {string | null}
  */
 function firstHeaderValue(h) {

package/src/listener-bun.js

@@ -45,7 +45,8 @@ import { EventEmitter } from 'node:events';
 import { Readable, pipeline } from 'node:stream';
 import { matchApi } from './router.js';
 import { registerClient } from './broadcast.js';
-import { setTrustedRemoteIp } from './rate-limit.js';
+import { setTrustedRemoteIp, propagateTrustedRemoteIp } from './rate-limit.js';
+import { applyForwarded } from './forwarded.js';
 import {
   isCompressible,
   isEventsPath,
@@ -104,7 +105,7 @@ export function startBunListener(ctx) {
         // head-start during SSR compute, not the preloads themselves.
 
         stampRemoteIp(req, srv);
-        const resp = await app.handle(req);
+        const resp = await app.handle(forwardedRequest(req, url));
         return compress ? await maybeCompress(resp, req) : resp;
       } catch (e) {
         logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
@@ -237,7 +238,11 @@ async function bunUpgrade(req, srv, ctx) {
   }
 
   const wrapper = new BunWsAdapter();
-  const handlerReq = upgradeRequest(req, url);
+  // Behind a proxy the handshake arrives as plain http on the internal hop, so
+  // the handler request carries the ORIGINAL scheme + host too (the node WS path
+  // gets this from `urlFromRequest` in `buildRequestFromUpgrade`). Routing above
+  // keyed on `url.pathname`, which the origin swap leaves untouched.
+  const handlerReq = upgradeRequest(req, applyForwarded(url, req.headers));
   // Stamp the framework-trusted socket IP on the handler request so a `WS`
   // handler's `clientIp(req)` returns the real peer, not a spoofed inbound
   // `x-webjs-remote-ip` (#778). `srv.requestIP` must be queried with Bun's
@@ -317,6 +322,78 @@ function bunSseResponse(req, hub, app) {
   });
 }
 
+/**
+ * Rebuild the request behind a TLS-terminating reverse proxy so `req.url`
+ * carries the ORIGINAL scheme + host (`X-Forwarded-Proto` / `X-Forwarded-Host`).
+ *
+ * Why the request itself and not just a threaded url: everything downstream
+ * (the framework's own `new URL(req.url)` reads AND a user's `route.ts` doing
+ * `new URL(req.url).origin`) derives from `req.url`, so correcting only a side
+ * channel would fix the framework's absolute URLs and leave app code broken.
+ * The node shell gets this for free, since `toWebRequest` builds its `Request`
+ * FROM the already-corrected `urlFromRequest(req)`; Bun hands us a `Request`
+ * whose url reflects the internal `http://container` view, so the correction
+ * has to be applied here for the two shells to agree.
+ *
+ * Hot path: `applyForwarded` returns the SAME url instance when nothing
+ * changes, so an app with no proxy in front (local dev, direct exposure,
+ * `WEBJS_NO_TRUST_PROXY=1`) does ZERO extra work and keeps the #756 no-clone
+ * behaviour. Behind a proxy this costs one `Request` construction per request,
+ * which is still strictly less than the node shell, which constructs one
+ * unconditionally. The trusted IP is carried across the rebuild the same way
+ * the base-path rewrite in `dev.js` does it (#773), so `clientIp` stays
+ * authoritative and the inbound spoofable header is never consulted.
+ *
+ * @param {Request} req
+ * @param {URL} url  the url as `Bun.serve` saw it
+ * @returns {Request} `req` itself when unchanged, else the corrected request
+ */
+function forwardedRequest(req, url) {
+  const fwd = applyForwarded(url, req.headers);
+  if (fwd === url) return req;
+  // SECURITY (#778): drop any client-supplied `x-webjs-remote-ip` before it
+  // rides onto the rebuilt request. `trustedRemoteIp` reads the WeakMap first,
+  // so the header cannot win today, but every other rebuild site strips it
+  // (`dev.js`'s base-path rewrite, `upgradeRequest` below) and leaving it
+  // attached would re-arm the spoof the moment any later code path rebuilds
+  // this request without carrying the WeakMap across.
+  const headers = new Headers(req.headers);
+  headers.delete('x-webjs-remote-ip');
+  const next = new Request(fwd, { ...requestInitFrom(req), headers });
+  propagateTrustedRemoteIp(req, next);
+  return next;
+}
+
+/**
+ * The parts of a `Request` that must survive the rebuild, spelled out because
+ * the header strip above needs its own `Headers` and passing the `Request` as
+ * the init would ignore them.
+ *
+ * `duplex: 'half'` is required by the spec whenever a body is present, and
+ * `mode: 'navigate'` cannot be passed to the constructor, so it is dropped.
+ *
+ * @param {Request} req
+ */
+function requestInitFrom(req) {
+  /** @type {any} */
+  const init = {
+    method: req.method,
+    signal: req.signal,
+    credentials: req.credentials,
+    cache: req.cache,
+    redirect: req.redirect,
+    referrer: req.referrer,
+    referrerPolicy: req.referrerPolicy,
+    integrity: req.integrity,
+  };
+  if (req.mode && req.mode !== 'navigate') init.mode = req.mode;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    init.body = req.body;
+    init.duplex = 'half';
+  }
+  return init;
+}
+
 /**
  * Stamp the framework-trusted remote IP from Bun's `server.requestIP`,
  * out-of-band via `setTrustedRemoteIp` (#756). The previous implementation

package/src/ssr.js

@@ -164,6 +164,11 @@ export async function ssrPage(route, params, url, opts) {
         frameRes.headers.append('vary', 'X-Webjs-Frame');
         // #1009: a subtree sliced from a REDUCED render inherits its variance.
         if (reduced) frameRes.headers.append('vary', 'X-Webjs-Have');
+        // No privateFragment call here on purpose: this response is built
+        // WITHOUT page metadata, so it is already `no-store` and the call
+        // would be dead code with nothing to assert against. The property is
+        // locked by a test instead, which fails if the frame response ever
+        // starts carrying the page's cacheControl.
         return frameRes;
       }
     }
@@ -304,15 +309,25 @@ export async function ssrPage(route, params, url, opts) {
     );
     // REDUCED response (#1009): the X-Webjs-Have short-circuit omitted the
     // outer-layout chrome, so these bytes are only valid for a request that
-    // sent a matching `have`. Without `Vary: X-Webjs-Have`, a shared cache
-    // (CDN edge) could store the reduced body under the URL and serve a
-    // chrome-less fragment to a fresh full-page navigation (measured live:
-    // GET / was 73,534 bytes, GET / + have was 57,035, byte-identical headers
-    // otherwise). Scoped to genuinely reduced responses so a normal page's
-    // cache key is unchanged. The internal #241 revalidate cache is already
-    // safe by construction: `cacheEligible` excludes any request that carries
-    // x-webjs-have, so a reduced body is never stored under the URL-only key.
-    if (reduced) res.headers.append('vary', 'X-Webjs-Have');
+    // sent a matching `have`. Left shared-cacheable, a CDN edge could store the
+    // reduced body under the URL and serve a chrome-less fragment to a fresh
+    // full-page navigation (measured live: GET / was 73,534 bytes, GET / + have
+    // was 57,035, byte-identical headers otherwise).
+    //
+    // TWO markings, and the order of trust matters (#1140). `privateFragment`
+    // is the guarantee: it forbids SHARED storage outright, so no CDN can hold
+    // this body at all. `Vary` is belt-and-braces for caches that honour it,
+    // NOT the protection, because Cloudflare and others honour only
+    // `Accept-Encoding`. Both are scoped to genuinely reduced responses, so a
+    // normal page's headers and cache key are unchanged.
+    //
+    // The internal #241 revalidate cache is already safe by construction:
+    // `cacheEligible` excludes any request that carries x-webjs-have, so a
+    // reduced body is never stored under the URL-only key.
+    if (reduced) {
+      res.headers.append('vary', 'X-Webjs-Have');
+      privateFragment(res);
+    }
     // Server HTML cache write (#241). The page opted in via `revalidate`, so
     // FLAG this candidate for the response funnel rather than writing here: the
     // store decision must see the FINAL response (after segment middleware,
@@ -465,6 +480,82 @@ export async function ssrUnauthorized(route, opts) {
   return htmlResponse(html, 401, opts.req, opts.url);
 }
 
+/**
+ * Downgrade a PARTIAL response so no shared cache can store it (#1140).
+ *
+ * A reduced `X-Webjs-Have` body is sliced by a REQUEST header, so it is valid
+ * only for a client that sent it. It is marked `Vary` for that header, but
+ * `Vary` is not a guarantee in practice: Cloudflare honours only
+ * `Accept-Encoding` and several other shared caches are just as selective.
+ * Since a reduced body otherwise INHERITS the page's `Cache-Control`, a page
+ * that opted into public caching was handing CDNs a chrome-less fragment under
+ * the full page's URL, to be served to whoever navigated there next. Measured
+ * on webjs.dev: 71,759 bytes for the document versus 47,375 for the fragment,
+ * identical `Cache-Control` on both.
+ *
+ * The reduced path is the ONLY caller. A `<webjs-frame>` subtree is sliced by a
+ * request header too, but its response is built without page metadata, so it is
+ * already `no-store` and needs no downgrade; that property is locked by a test
+ * rather than by a call here. A NEW partial-response shape does not get this
+ * treatment for free: call this from its response site.
+ *
+ * `private` fixes that at the source instead of relying on `Vary` being
+ * respected: no shared cache may store it, while the browser that asked for it
+ * still may. The freshness directives are preserved, so a returning client
+ * keeps whatever reuse the page declared. `Vary` stays too, as belt-and-braces
+ * for caches that do honour it.
+ *
+ * The response KEEPS its validator. `private` forbids shared storage, not
+ * validation, so the funnel still attaches an ETag (see conditional-get.js,
+ * which stopped excluding `private` for exactly this reason). That matters:
+ * the router fetches partials with `cache: 'no-cache'` (#1131), so without a
+ * validator every prefetch and soft navigation would re-download the whole
+ * fragment instead of being answered 304.
+ *
+ * @param {Response} res
+ */
+export function privateFragment(res) {
+  const cc = res.headers.get('cache-control') || '';
+  // No header at all is not "nothing to do": a response with no Cache-Control
+  // is heuristically storable by a shared cache (RFC 9111), which is precisely
+  // the hazard here. Fail CLOSED.
+  if (!cc) {
+    res.headers.set('cache-control', 'private');
+    return;
+  }
+  // Split on commas that are NOT inside a quoted argument: a directive may
+  // carry one (`no-cache="Set-Cookie, X-Foo"`, `private="x-user"`), and a naive
+  // split tears those apart.
+  const directives = [];
+  let buf = '';
+  let inQuotes = false;
+  for (const ch of cc) {
+    if (ch === '"') inQuotes = !inQuotes;
+    if (ch === ',' && !inQuotes) { directives.push(buf.trim()); buf = ''; continue; }
+    buf += ch;
+  }
+  directives.push(buf.trim());
+
+  // `name` is everything before the first `=`, trimmed, so `s-maxage = 600`
+  // and `private="x-user"` are recognised as the directives they are.
+  const nameOf = (d) => d.split('=')[0].trim().toLowerCase();
+  // Already unshareable: leave it exactly as the author wrote it. Only a BARE
+  // `private` counts. The qualified form (`private="x-user"`) marks just the
+  // NAMED header fields private per RFC 9111, leaving the response itself
+  // storable by a shared cache, so it must still be downgraded.
+  const isBare = (d) => !d.includes('=');
+  if (directives.some((d) => nameOf(d) === 'no-store' || (nameOf(d) === 'private' && isBare(d)))) return;
+
+  // `private` joins the drop list because a bare one is prepended below: a
+  // qualified `private="x-user"` left in place would emit the directive twice,
+  // and a cache that resolves a repeat by taking the last occurrence would read
+  // the qualified form, which per RFC 9111 leaves the response shared-storable.
+  const SHARED_ONLY = new Set(['public', 's-maxage', 'proxy-revalidate', 'private']);
+  const kept = directives.filter((d) => d && !SHARED_ONLY.has(nameOf(d)));
+  kept.unshift('private');
+  res.headers.set('cache-control', kept.join(', '));
+}
+
 /**
  * Build an HTML Response. Sets no cookie: action CSRF is an Origin /
  * Sec-Fetch-Site check, so the page response is cookieless (CDN-cacheable).
@@ -476,8 +567,10 @@ export async function ssrUnauthorized(route, opts) {
  */
 function htmlResponse(html, status, req, url, metadata) {
   const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' });
-  // Default: no caching. Pages are dynamic by default: the developer
-  // opts in to caching explicitly via metadata.cacheControl.
+  // Default: no caching. Pages are dynamic by default: the developer opts in
+  // explicitly via metadata.cacheControl. No non-200 guard here, unlike
+  // streamingHtmlResponse: every caller of THIS builder passes no metadata, so
+  // the value is already the no-store default and a guard would be dead code.
   headers.set('cache-control', metadata?.cacheControl || 'no-store');
   // X-Webjs-Build carries the published build id so the client
   // router can detect post-deploy importmap changes on EVERY
@@ -487,10 +580,11 @@ function htmlResponse(html, status, req, url, metadata) {
   // applySwap and publishedBuildId() in importmap.js.
   headers.set('x-webjs-build', publishedBuildId());
   headers.set('x-webjs-src', appSourceId());
-  // Buffered (string) body: opt into the conditional-GET funnel so a
-  // PUBLIC-cacheable page (metadata.cacheControl) gets a weak ETag + 304.
-  // The funnel still excludes the no-store default, so a private page is
-  // never ETagged. See conditional-get.js.
+  // Buffered (string) body: opt into the conditional-GET funnel.
+  // A cacheable page (metadata.cacheControl) gets a weak ETag + 304. The
+  // funnel excludes only the no-store default; a `private` page IS validated,
+  // which is what keeps the router's partial responses cheap (#1140).
+  // See conditional-get.js.
   headers.set(BUFFERED_MARKER, '1');
   return new Response(html, { status, headers });
 }
@@ -650,8 +744,10 @@ async function renderChain(route, ctx, dev, suspenseCtx, have, pageModule) {
       const body = await renderToString(tree, { ssr: true, suspenseCtx });
       // REDUCED response (#1009): the outer layouts were skipped, so these
       // bytes are only valid for a client that already HAS them. The caller
-      // marks the response `Vary: X-Webjs-Have` so no shared cache can serve
-      // this fragment to a fresh full-page navigation.
+      // marks the response `private` so no shared cache can store it, and
+      // additionally `Vary: X-Webjs-Have` for caches that honour it. The
+      // `private` is the guarantee, not the Vary: Cloudflare and others honour
+      // only `Accept-Encoding` (#1140).
       return { html: body + (await loadingTemplates(route, ctx, dev)), reduced: true };
     }
     const mod = await loadModule(route.layouts[i], dev);
@@ -1955,8 +2051,11 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   const encoder = new TextEncoder();
   const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' });
   // Default: no caching. Pages are dynamic by default: the developer
-  // opts in to caching explicitly via metadata.cacheControl.
-  headers.set('cache-control', metadata?.cacheControl || 'no-store');
+  // opts in to caching explicitly via metadata.cacheControl. A non-200 does
+  // NOT inherit it (#1140): the page-action re-render is a 422 carrying the
+  // submitter's own field values and errors, which must never be handed to a
+  // shared cache just because the page opted into public caching.
+  headers.set('cache-control', status === 200 ? (metadata?.cacheControl || 'no-store') : 'no-store');
   // See htmlResponse: published build id on every response for the
   // client router's importmap-mismatch detection on partial swaps.
   headers.set('x-webjs-build', publishedBuildId());