@webjsdev/server 0.8.57 → 0.8.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.57",
+  "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

@@ -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 {

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());