@pylonsync/functions 0.3.297 → 0.3.298

package/dist/ssr-runtime.d.ts

@@ -142,7 +142,16 @@ export declare function makeResponseController(state: ResponseState, defaultRedi
  * into one `Set-Cookie` header each (newline is forbidden inside a
  * cookie, so it can't be turned into header injection).
  */
-export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>): Record<string, string>;
+/**
+ * Wrap a per-request object so ANY observation — property `get`, `in` (`has`),
+ * `Object.keys`/spread/`for…in` (`ownKeys`), or a descriptor probe — calls
+ * `onTouch`. Used to mark a render request-specific (vetoing shared caching) the
+ * instant it reads auth/headers/cookies. A bare `get` trap misses `in` and
+ * `Object.keys`, which would observe the data without tripping the veto.
+ * Exported for direct unit testing of that property.
+ */
+export declare function makeReadTrackingProxy(obj: Record<string, unknown> | undefined, onTouch: () => void): Record<string, unknown>;
+export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>, internal?: Record<string, string>): Record<string, string>;
 /**
  * Phase 1 SSR handler. Resolves the component, renders it via
  * react-dom/server.renderToReadableStream, pumps chunks back to the
@@ -355,6 +364,7 @@ export declare function computeCacheVerdict(args: {
     revalidateSecs: number | null;
     forceDynamic: boolean;
     authTouched: boolean;
+    dynamicTouched: boolean;
     cookieCount: number;
     strictPolicies: boolean;
     wantsStream: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.297",
+  "version": "0.3.298",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.test.ts

@@ -14,6 +14,9 @@ import {
   isSafeRedirect,
   asRouteControl,
   PylonRouteControl,
+  finalizeHeaders,
+  makeResponseController,
+  makeReadTrackingProxy,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -53,6 +56,98 @@ describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () =
   test("no public origin + untrusted host → empty (relative, never poisoned)", () => {
     expect(resolveOrigin({ host: "evil.com" })).toBe("");
   });
+
+  test("off-loopback never honors X-Forwarded-Proto (no downgrade poisoning)", () => {
+    // Even on a TRUSTED host, a client-supplied proto must not change the
+    // absolute origin — it feeds og:image/canonical and is cache-keyed only by
+    // host, so honoring `http` would downgrade the cached URL for everyone.
+    // Off-loopback is ALWAYS https.
+    expect(
+      resolveOrigin({ host: "www.notbehind.com", publicUrl, forwardedProto: "http" }),
+    ).toBe("https://www.notbehind.com");
+    expect(
+      resolveOrigin({
+        host: "www.notbehind.com",
+        publicUrl,
+        forwardedProto: "javascript:alert(1)",
+      }),
+    ).toBe("https://www.notbehind.com");
+    // Loopback (dev) may be http; an explicit https there is honored.
+    expect(resolveOrigin({ host: "localhost:4321", forwardedProto: "http" })).toBe(
+      "http://localhost:4321",
+    );
+    expect(resolveOrigin({ host: "localhost:4321", forwardedProto: "https" })).toBe(
+      "https://localhost:4321",
+    );
+  });
+});
+
+describe("reserved x-pylon-* header namespace (cache-proof forgery fence)", () => {
+  test("response.setHeader() rejects the reserved x-pylon-* namespace", () => {
+    const state = {
+      status: 200,
+      headers: {} as Record<string, string>,
+      cookies: [] as string[],
+    };
+    const res = makeResponseController(state);
+    // Forging the #277 cache proof from userland must throw, not silently set it.
+    expect(() => res.setHeader("x-pylon-cacheable", "300")).toThrow(/reserved/i);
+    expect(() => res.setHeader("X-Pylon-Anything", "1")).toThrow(/reserved/i);
+    // An ordinary header still works.
+    res.setHeader("x-custom", "ok");
+    expect(state.headers["x-custom"]).toBe("ok");
+  });
+
+  test("finalizeHeaders: x-pylon-* survives ONLY from the trusted internal channel", () => {
+    // The #277 proof must come from the 3rd `internal` arg. A page-set header
+    // (state.headers) OR a route-handler header (the 2nd `extra` arg, which
+    // ssr-form-runtime fills from user-returned headers) is stripped — so
+    // userland can't forge the host-side cache verdict through ANY path.
+    const state = {
+      status: 200,
+      headers: { "x-pylon-cacheable": "999", "x-keep": "yes" } as Record<string, string>,
+      cookies: [] as string[],
+    };
+    const out = finalizeHeaders(
+      state,
+      { "x-pylon-cacheable": "888", "x-extra": "e" }, // untrusted extra → stripped
+      { "x-pylon-cacheable": "60" }, // trusted internal → kept
+    );
+    expect(out["x-pylon-cacheable"]).toBe("60"); // only the trusted value
+    expect(out["x-keep"]).toBe("yes");
+    expect(out["x-extra"]).toBe("e"); // a non-reserved extra header still merges
+
+    // No internal proof → NO x-pylon-* survives, from page headers OR extra.
+    const out2 = finalizeHeaders(
+      { status: 200, headers: { "x-pylon-cacheable": "999" }, cookies: [] as string[] },
+      { "x-pylon-cacheable": "777" },
+    );
+    expect(out2["x-pylon-cacheable"]).toBeUndefined();
+  });
+
+  test("makeReadTrackingProxy trips on get / in / Object.keys / descriptor / spread", () => {
+    const probes: Array<(o: any) => unknown> = [
+      (o) => o.host,
+      (o) => "host" in o,
+      (o) => Object.keys(o),
+      (o) => Object.getOwnPropertyDescriptor(o, "host"),
+      (o) => ({ ...o }),
+    ];
+    for (const probe of probes) {
+      let touched = false;
+      const p = makeReadTrackingProxy({ host: "x" }, () => {
+        touched = true;
+      });
+      probe(p);
+      expect(touched).toBe(true); // a bare `get` trap would miss in/keys
+    }
+    // No observation → never touched.
+    let t = false;
+    makeReadTrackingProxy({ host: "x" }, () => {
+      t = true;
+    });
+    expect(t).toBe(false);
+  });
 });
 
 // Pull the JSON out of the `__PYLON_DATA__` <script> a hydration tail emits.

package/src/ssr-runtime.ts

@@ -253,6 +253,16 @@ export function makeResponseController(
       if (!TOKEN_RE.test(name)) {
         throw new Error(`pylon ssr: invalid header name ${JSON.stringify(name)}`);
       }
+      // `x-pylon-*` is a reserved internal namespace — the host trusts headers
+      // like the #277 `x-pylon-cacheable` cache proof as runtime-emitted. Letting
+      // userland set one would forge the cache verdict (e.g. mark a personalized
+      // render shareable). Reject it loudly.
+      if (name.toLowerCase().startsWith("x-pylon-")) {
+        throw new Error(
+          `pylon ssr: "x-pylon-*" is a reserved internal header namespace and ` +
+            `cannot be set via response.setHeader() (got ${JSON.stringify(name)})`,
+        );
+      }
       assertNoControlChars(value, "header value");
       state.headers[name.toLowerCase()] = value;
     },
@@ -299,11 +309,63 @@ export function makeResponseController(
  * into one `Set-Cookie` header each (newline is forbidden inside a
  * cookie, so it can't be turned into header injection).
  */
+/**
+ * Wrap a per-request object so ANY observation — property `get`, `in` (`has`),
+ * `Object.keys`/spread/`for…in` (`ownKeys`), or a descriptor probe — calls
+ * `onTouch`. Used to mark a render request-specific (vetoing shared caching) the
+ * instant it reads auth/headers/cookies. A bare `get` trap misses `in` and
+ * `Object.keys`, which would observe the data without tripping the veto.
+ * Exported for direct unit testing of that property.
+ */
+export function makeReadTrackingProxy(
+  obj: Record<string, unknown> | undefined,
+  onTouch: () => void,
+): Record<string, unknown> {
+  return new Proxy((obj ?? {}) as Record<string, unknown>, {
+    get(t, p, r) {
+      onTouch();
+      return Reflect.get(t, p, r);
+    },
+    has(t, p) {
+      onTouch();
+      return Reflect.has(t, p);
+    },
+    ownKeys(t) {
+      onTouch();
+      return Reflect.ownKeys(t);
+    },
+    getOwnPropertyDescriptor(t, p) {
+      onTouch();
+      return Reflect.getOwnPropertyDescriptor(t, p);
+    },
+  });
+}
+
 export function finalizeHeaders(
   state: ResponseState,
+  // UNTRUSTED user headers (page-set `state.headers` and, at the form/data-route
+  // call sites, a route handler's returned headers). `x-pylon-*` is stripped.
   extra?: Record<string, string>,
+  // TRUSTED runtime headers (e.g. the #277 `x-pylon-cacheable` proof). The ONLY
+  // legitimate source of `x-pylon-*`; merged last and never stripped.
+  internal?: Record<string, string>,
 ): Record<string, string> {
-  const h: Record<string, string> = { ...state.headers, ...(extra ?? {}) };
+  // The host TRUSTS `x-pylon-*` headers (cache verdict, etc.). They must come
+  // ONLY from `internal` — strip them from BOTH page-set headers AND `extra` so
+  // userland can't forge the verdict through any path (setHeader is also
+  // rejected at the source, this is defense-in-depth + covers route-handler
+  // headers that flow through `extra`).
+  const h: Record<string, string> = {};
+  const mergeStripped = (src?: Record<string, string>) => {
+    if (!src) return;
+    for (const [k, v] of Object.entries(src)) {
+      if (k.toLowerCase().startsWith("x-pylon-")) continue;
+      h[k] = v; // later sources override earlier (page < extra)
+    }
+  };
+  mergeStripped(state.headers);
+  mergeStripped(extra);
+  if (internal) Object.assign(h, internal); // trusted, never stripped
   if (!h["content-type"]) h["content-type"] = "text/html; charset=utf-8";
   if (state.cookies.length > 0) {
     // Preserve a set-cookie value set via setHeader() (rare) and join it
@@ -811,9 +873,17 @@ export function resolveOrigin(opts: {
     for (const x of (opts.trustedHostsCsv || "").split(",")) add(x);
     const isLoopback = LOOPBACK_HOST.test(host);
     if (isLoopback || allow.has(host)) {
-      // Only honor a forwarded proto for a TRUSTED host — else an attacker
-      // could downgrade the cached URL to http://. Default https off-loopback.
-      const proto = opts.forwardedProto || (isLoopback ? "http" : "https");
+      // Off-loopback (prod) we ALWAYS use https and never honor the request's
+      // X-Forwarded-Proto. The SSR cache is keyed only by host (not proto), so
+      // honoring a client-supplied `http` would poison the cached canonical/OG
+      // URL with a downgraded scheme for every subsequent visitor. Loopback
+      // (dev) may be plain http. (A genuinely non-https prod origin should set
+      // PYLON_PUBLIC_URL explicitly, which takes precedence above.)
+      const proto = isLoopback
+        ? opts.forwardedProto === "https"
+          ? "https"
+          : "http"
+        : "https";
       return `${proto}://${host}`;
     }
   }
@@ -1486,6 +1556,13 @@ export function computeCacheVerdict(args: {
   revalidateSecs: number | null;
   forceDynamic: boolean;
   authTouched: boolean;
+  // True when the render read any OTHER per-request input that is not part of
+  // the cache key — request `headers` (incl. non-bucketed ones) or `cookies`
+  // (incl. via generateMetadata). Such a read makes the output request-specific,
+  // so it must veto shared caching exactly like `authTouched`. (Keyed inputs —
+  // pathname, and Host via the host bucket — are handled by the cache key and do
+  // not set this.)
+  dynamicTouched: boolean;
   cookieCount: number;
   strictPolicies: boolean;
   wantsStream: boolean;
@@ -1495,6 +1572,7 @@ export function computeCacheVerdict(args: {
     args.revalidateSecs != null &&
     !args.forceDynamic &&
     !args.authTouched &&
+    !args.dynamicTouched &&
     args.cookieCount === 0 &&
     !args.strictPolicies &&
     !args.wantsStream &&
@@ -1790,26 +1868,37 @@ export async function handleRenderRoute(
     );
 
     // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
-    // if its output is auth-INDEPENDENT — so wrap props.auth in a Proxy that
-    // flips `authTouched` the moment a page/layout reads it. Reading auth at
-    // all (even for an anonymous request) opts the render OUT of caching,
-    // because the output could differ by identity. The raw auth is restored
-    // before serialization (so the hydration blob carries real values, and so
-    // JSON.stringify doesn't trip the Proxy itself).
+    // if its output is independent of per-request inputs — so wrap each in a
+    // read-tracking Proxy (makeReadTrackingProxy) that flips a flag the moment a
+    // page/layout/generateMetadata observes it (get / `in` / Object.keys / probe).
+    // The raw objects are restored before serialization.
+
+    // Reading auth at all (even for an anon request) opts the render OUT of
+    // caching, because the output could differ by identity.
     let authTouched = false;
-    const authProxy = new Proxy(msg.auth as Record<string, unknown>, {
-      get(target, prop, receiver) {
+    const authProxy = makeReadTrackingProxy(
+      msg.auth as Record<string, unknown> | undefined,
+      () => {
         authTouched = true;
-        return Reflect.get(target, prop, receiver);
       },
-    });
+    );
+
+    // Same proof for the OTHER per-request inputs that aren't in the cache key:
+    // reading `headers` (any header, incl. via generateMetadata) or `cookies`
+    // makes the output request-specific. Only USER code reads props.headers/
+    // cookies — the framework's metadata path reads `msg.headers` directly.
+    let dynamicTouched = false;
+    const touchProxy = (obj: Record<string, unknown> | undefined) =>
+      makeReadTrackingProxy(obj, () => {
+        dynamicTouched = true;
+      });
 
     props = {
       url: msg.url,
       params: msg.params,
       searchParams: msg.search_params,
-      headers: msg.headers,
-      cookies: msg.cookies,
+      headers: touchProxy(msg.headers as Record<string, unknown> | undefined),
+      cookies: touchProxy(msg.cookies as Record<string, unknown> | undefined),
       auth: authProxy,
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
@@ -1978,14 +2067,19 @@ export async function handleRenderRoute(
       revalidateSecs,
       forceDynamic,
       authTouched,
+      dynamicTouched,
       cookieCount: responseState.cookies.length,
       strictPolicies,
       wantsStream,
       status: responseState.status,
     });
-    // Restore the raw auth before any serialization below (the Proxy was only
-    // for the render-time auth-touch probe).
-    if (props) props.auth = msg.auth;
+    // Restore the raw auth/headers/cookies before any serialization below (the
+    // Proxies were only for the render-time touch probe).
+    if (props) {
+      props.auth = msg.auth;
+      props.headers = msg.headers;
+      props.cookies = msg.cookies;
+    }
     // #278: on a STREAMING render the head commits NOW, before suspended
     // subtrees run. Snapshot what's committed so we can detect (after EOF) a
     // late response.setStatus/setCookie/setHeader from a suspended subtree that
@@ -2005,7 +2099,11 @@ export async function handleRenderRoute(
       status: responseState.status,
       headers: finalizeHeaders(
         responseState,
-        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : {},
+        undefined,
+        // The #277 proof rides the TRUSTED `internal` channel (never stripped),
+        // so userland (page setHeader / route-handler headers via `extra`) can't
+        // forge it.
+        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : undefined,
       ),
     });
 

package/src/ssr-streaming.test.ts

@@ -96,6 +96,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     revalidateSecs: 60 as number | null,
     forceDynamic: false,
     authTouched: false,
+    dynamicTouched: false,
     cookieCount: 0,
     strictPolicies: false,
     wantsStream: false,
@@ -110,6 +111,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     expect(computeCacheVerdict({ ...base, revalidateSecs: null })).toBe(false); // no opt-in
     expect(computeCacheVerdict({ ...base, forceDynamic: true })).toBe(false);
     expect(computeCacheVerdict({ ...base, authTouched: true })).toBe(false); // read auth
+    expect(computeCacheVerdict({ ...base, dynamicTouched: true })).toBe(false); // read headers/cookies
     expect(computeCacheVerdict({ ...base, cookieCount: 1 })).toBe(false); // set a cookie
     expect(computeCacheVerdict({ ...base, strictPolicies: true })).toBe(false);
     expect(computeCacheVerdict({ ...base, wantsStream: true })).toBe(false); // STREAMING
@@ -133,6 +135,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
                     revalidateSecs,
                     forceDynamic,
                     authTouched,
+                    dynamicTouched: false,
                     cookieCount,
                     strictPolicies,
                     wantsStream,