@pylonsync/functions 0.3.297 → 0.3.299

package/dist/ssr-runtime.d.ts

@@ -56,6 +56,12 @@ export interface RenderRouteMessage {
         tenant_id: string | null;
         roles: string[];
     };
+    /**
+     * Whether the request carried a session cookie (presence, not identity) —
+     * surfaced as the identity-free `props.session.exists` (Phase 0 auth
+     * bucketing). Default false / absent for back-compat.
+     */
+    session_present?: boolean;
     /**
      * Initial HTTP status the response controller starts at (default 200).
      * The host sets this to 404 when dispatching a `not-found.tsx` render
@@ -142,7 +148,40 @@ 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>;
+/**
+ * Deep clone via JSON round-trip — drops functions / proxies / symbols, keeping
+ * only JSON-serializable data. Used to SNAPSHOT the bucket-tail props before any
+ * page code can mutate them, so a page can't smuggle identity through a nested
+ * field of params/searchParams into a shared cache entry. The deep copy is fully
+ * independent of the source: a later mutation of the original object can't reach
+ * the snapshot.
+ */
+export declare function jsonClone<T>(v: T): T;
+/**
+ * Revocable form of {@link makeReadTrackingProxy}. The render path wraps each
+ * per-request input (auth / headers / cookies / session) in one of these and
+ * REVOKES it once the render is done — so a page that stashed the props object
+ * (or `props.auth`) in module-level state and read it on a LATER render gets a
+ * hard throw instead of silently reading a prior request's identity WITHOUT
+ * tripping this render's read-tracking. Revocation is per-render (each render
+ * revokes only its own proxies), so it is sound even when the Bun runner
+ * multiplexes concurrent renders. Fail-closed: the stale read throws, the render
+ * fails, and nothing is cached.
+ */
+export declare function makeRevocableReadTrackingProxy(obj: Record<string, unknown> | undefined, onTouch: () => void): {
+    proxy: Record<string, unknown>;
+    revoke: () => void;
+};
+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
@@ -325,6 +364,9 @@ export declare function buildHydrationTail(args: {
         message: string;
         digest?: string;
     };
+    bucketAuth?: {
+        signedIn: boolean;
+    };
 }): string;
 /**
  * A short, non-reversible correlation id for an error — surfaced to the
@@ -355,6 +397,48 @@ export declare function computeCacheVerdict(args: {
     revalidateSecs: number | null;
     forceDynamic: boolean;
     authTouched: boolean;
+    dynamicTouched: boolean;
+    sessionTouched: boolean;
+    cookieCount: number;
+    strictPolicies: boolean;
+    wantsStream: boolean;
+    status: number;
+}): boolean;
+/**
+ * PPR Phase 0 — the AUTH-BUCKET verdict: may this render be stored as a SHARED
+ * cache entry keyed only on session-cookie PRESENCE (one signed-in shell + one
+ * signed-out shell, both IDENTITY-FREE)? Pure, exported, leak-class tested.
+ *
+ * Like `computeCacheVerdict` EXCEPT `sessionTouched` is ALLOWED (reading
+ * `props.session.exists` to render a binary signed-in/out nav is the whole
+ * point — that bit is what the bucket keys on, and it's identical across all
+ * users in the same bucket). Everything else still vetoes:
+ *
+ *  - `authTouched` — reading real `props.auth` (user_id/tenant_id/roles) makes
+ *    the output identity-SPECIFIC, not bucket-uniform. This is the load-bearing
+ *    gate: ANY identity-dependent output requires reading auth, so vetoing on
+ *    `authTouched` proves a bucketable body depends on nothing but the binary
+ *    session bit.
+ *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
+ *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
+ *    body/ssrData would vary by identity even without the page reading auth. In
+ *    the default (non-strict) mode serverData reads bypass the policy gate and
+ *    return identity-independent rows, so the cached body is safe to share within
+ *    the bucket. Strict mode therefore must NOT bucket.
+ *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
+ *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
+ *    safely shared).
+ *
+ * Requires the explicit `bucketOptIn` (`export const cache = "auth-bucketed"`)
+ * AND a TTL via `export const revalidate = N` — fail-closed: no opt-in or no TTL
+ * → no bucket.
+ */
+export declare function computeBucketVerdict(args: {
+    bucketOptIn: boolean;
+    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.299",
   "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,11 @@ import {
   isSafeRedirect,
   asRouteControl,
   PylonRouteControl,
+  finalizeHeaders,
+  makeResponseController,
+  makeReadTrackingProxy,
+  makeRevocableReadTrackingProxy,
+  jsonClone,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -53,6 +58,134 @@ 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);
+  });
+
+  test("revocable proxy throws after revoke (stale module-stashed props fence)", () => {
+    // P0 (codex 2026-06-28): a page that stashes `props` (or `props.auth`) in
+    // module-level state and reads it on a LATER render must not silently read a
+    // prior request's identity without tripping THIS render's read-tracking. The
+    // render path revokes each per-request proxy when the render ends, so any
+    // retained reference throws on access — fail-closed.
+    const { proxy, revoke } = makeRevocableReadTrackingProxy(
+      { user_id: "alice" },
+      () => {},
+    );
+    expect((proxy as any).user_id).toBe("alice"); // live during the render
+    revoke();
+    // A stashed reference, read on a later render:
+    expect(() => (proxy as any).user_id).toThrow();
+    expect(() => "user_id" in proxy).toThrow();
+    expect(() => Object.keys(proxy)).toThrow();
+  });
+
+  test("jsonClone snapshot is independent of later source mutation (bucket params fence)", () => {
+    // The bucket-tail snapshot (bucketTailBase) is jsonClone'd at render START.
+    // The defense rests on the clone being decoupled from the live params object:
+    // a page mutating a NESTED field afterwards (props.searchParams.leak =
+    // props.auth) can't reach the already-captured snapshot.
+    const source: any = { id: "a", nested: { keep: 1 } };
+    const snap = jsonClone(source);
+    // Simulate the page smuggling identity in after the snapshot was taken.
+    source.leak = { user_id: "alice" };
+    source.nested.keep = 999;
+    expect(snap).toEqual({ id: "a", nested: { keep: 1 } });
+    expect((snap as any).leak).toBeUndefined();
+    // And it strips non-JSON values (a proxy aliased in would serialize as its
+    // target via JSON, but a function/symbol is dropped entirely).
+    const stripped = jsonClone({ ok: "v", fn: () => 1, sym: Symbol("x") } as any);
+    expect(stripped).toEqual({ ok: "v" });
+  });
 });
 
 // Pull the JSON out of the `__PYLON_DATA__` <script> a hydration tail emits.

package/src/ssr-runtime.ts

@@ -75,6 +75,12 @@ export interface RenderRouteMessage {
     tenant_id: string | null;
     roles: string[];
   };
+  /**
+   * Whether the request carried a session cookie (presence, not identity) —
+   * surfaced as the identity-free `props.session.exists` (Phase 0 auth
+   * bucketing). Default false / absent for back-compat.
+   */
+  session_present?: boolean;
   /**
    * Initial HTTP status the response controller starts at (default 200).
    * The host sets this to 404 when dispatching a `not-found.tsx` render
@@ -253,6 +259,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 +315,93 @@ 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 makeRevocableReadTrackingProxy(obj, onTouch).proxy;
+}
+
+/**
+ * Deep clone via JSON round-trip — drops functions / proxies / symbols, keeping
+ * only JSON-serializable data. Used to SNAPSHOT the bucket-tail props before any
+ * page code can mutate them, so a page can't smuggle identity through a nested
+ * field of params/searchParams into a shared cache entry. The deep copy is fully
+ * independent of the source: a later mutation of the original object can't reach
+ * the snapshot.
+ */
+export function jsonClone<T>(v: T): T {
+  return v == null ? v : (JSON.parse(JSON.stringify(v)) as T);
+}
+
+/**
+ * Revocable form of {@link makeReadTrackingProxy}. The render path wraps each
+ * per-request input (auth / headers / cookies / session) in one of these and
+ * REVOKES it once the render is done — so a page that stashed the props object
+ * (or `props.auth`) in module-level state and read it on a LATER render gets a
+ * hard throw instead of silently reading a prior request's identity WITHOUT
+ * tripping this render's read-tracking. Revocation is per-render (each render
+ * revokes only its own proxies), so it is sound even when the Bun runner
+ * multiplexes concurrent renders. Fail-closed: the stale read throws, the render
+ * fails, and nothing is cached.
+ */
+export function makeRevocableReadTrackingProxy(
+  obj: Record<string, unknown> | undefined,
+  onTouch: () => void,
+): { proxy: Record<string, unknown>; revoke: () => void } {
+  return Proxy.revocable((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 +909,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}`;
     }
   }
@@ -1132,6 +1238,15 @@ export function buildHydrationTail(args: {
   manifestErr: string | null;
   kind?: "error" | "not-found";
   errorForClient?: { message: string; digest?: string };
+  // PPR Phase 0 (auth-bucketed caching): when set, this render is being stored
+  // as a SHARED cache entry keyed only on session-cookie PRESENCE, so its
+  // hydration tail must carry an IDENTITY-FREE auth — the binary `{ signedIn }`
+  // bit the bucket is keyed on, and NOTHING ELSE (no user_id / tenant_id /
+  // roles / email). Two different signed-in users hitting the same bucketed
+  // page MUST produce a byte-identical tail, or the shared cache replays one
+  // user's identity to another (the #277 leak class, at the body level). The
+  // raw `auth` is replaced AFTER the live-handle strip below.
+  bucketAuth?: { signedIn: boolean };
 }): string {
   // Strip live, non-serializable handles (serverData / response / reset) + the
   // request headers/cookies (SECURITY: never expose the session cookie to
@@ -1146,7 +1261,28 @@ export function buildHydrationTail(args: {
     error: _err,
     ...restProps
   } = args.props ?? {};
-  const serializableProps: any = { ...restProps, headers: {}, cookies: {} };
+  let serializableProps: any;
+  if (args.bucketAuth) {
+    // Bucketed render → SHARED entry. Serialize a strict ALLOWLIST of the
+    // framework props that are provably bucket-uniform — never a spread of the
+    // page's props object. A page can alias identity onto a custom key
+    // (`props.leak = props.auth`) without tripping read-tracking; spreading
+    // `restProps` would then serialize that identity into the shared tail. The
+    // allowlisted fields are all path/route-derived (in the cache key) or the
+    // collapsed binary auth bit. (params/searchParams are keyed by pathname; a
+    // bucket request has no query, so searchParams is empty.)
+    serializableProps = {
+      url: restProps.url,
+      params: restProps.params,
+      searchParams: restProps.searchParams,
+      auth: { signedIn: args.bucketAuth.signedIn },
+      session: { exists: args.bucketAuth.signedIn },
+      headers: {},
+      cookies: {},
+    };
+  } else {
+    serializableProps = { ...restProps, headers: {}, cookies: {} };
+  }
   if (args.errorForClient) serializableProps.error = args.errorForClient;
   const hydrationPayload: any = {
     component: args.component,
@@ -1486,6 +1622,18 @@ 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;
+  // True when the render read `props.session.exists` (Phase 0). For the PLAIN
+  // anonymous cache this is a veto — the output varies by signed-in bucket, and
+  // the anon cache holds one entry for all. (The auth-BUCKET verdict, which keys
+  // the cache on the bucket, permits it; this gate does not.)
+  sessionTouched: boolean;
   cookieCount: number;
   strictPolicies: boolean;
   wantsStream: boolean;
@@ -1495,6 +1643,61 @@ export function computeCacheVerdict(args: {
     args.revalidateSecs != null &&
     !args.forceDynamic &&
     !args.authTouched &&
+    !args.dynamicTouched &&
+    !args.sessionTouched &&
+    args.cookieCount === 0 &&
+    !args.strictPolicies &&
+    !args.wantsStream &&
+    args.status === 200
+  );
+}
+
+/**
+ * PPR Phase 0 — the AUTH-BUCKET verdict: may this render be stored as a SHARED
+ * cache entry keyed only on session-cookie PRESENCE (one signed-in shell + one
+ * signed-out shell, both IDENTITY-FREE)? Pure, exported, leak-class tested.
+ *
+ * Like `computeCacheVerdict` EXCEPT `sessionTouched` is ALLOWED (reading
+ * `props.session.exists` to render a binary signed-in/out nav is the whole
+ * point — that bit is what the bucket keys on, and it's identical across all
+ * users in the same bucket). Everything else still vetoes:
+ *
+ *  - `authTouched` — reading real `props.auth` (user_id/tenant_id/roles) makes
+ *    the output identity-SPECIFIC, not bucket-uniform. This is the load-bearing
+ *    gate: ANY identity-dependent output requires reading auth, so vetoing on
+ *    `authTouched` proves a bucketable body depends on nothing but the binary
+ *    session bit.
+ *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
+ *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
+ *    body/ssrData would vary by identity even without the page reading auth. In
+ *    the default (non-strict) mode serverData reads bypass the policy gate and
+ *    return identity-independent rows, so the cached body is safe to share within
+ *    the bucket. Strict mode therefore must NOT bucket.
+ *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
+ *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
+ *    safely shared).
+ *
+ * Requires the explicit `bucketOptIn` (`export const cache = "auth-bucketed"`)
+ * AND a TTL via `export const revalidate = N` — fail-closed: no opt-in or no TTL
+ * → no bucket.
+ */
+export function computeBucketVerdict(args: {
+  bucketOptIn: boolean;
+  revalidateSecs: number | null;
+  forceDynamic: boolean;
+  authTouched: boolean;
+  dynamicTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  status: number;
+}): boolean {
+  return (
+    args.bucketOptIn &&
+    args.revalidateSecs != null &&
+    !args.forceDynamic &&
+    !args.authTouched &&
+    !args.dynamicTouched &&
     args.cookieCount === 0 &&
     !args.strictPolicies &&
     !args.wantsStream &&
@@ -1713,6 +1916,11 @@ export async function handleRenderRoute(
   let React: any = null;
   let renderToReadableStream: any = null;
   let props: any = null;
+  // Revoke fns for this render's per-request proxies (auth/headers/cookies/
+  // session). Declared OUT here so the `finally` revokes them on EVERY exit path
+  // (success, redirect/notFound/error boundary, throw) — neutralizing any
+  // module-stashed reference to a prior request's identity.
+  const proxyRevokers: Array<() => void> = [];
   // Accumulates the resolved results of every `serverData.*` read the page
   // made during render, keyed identically to the client shim. Serialized
   // into `__PYLON_DATA__.ssrData` so hydration replays the same values
@@ -1790,27 +1998,63 @@ 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 that flips a flag the moment a page/layout/
+    // generateMetadata observes it (get / `in` / Object.keys / probe). The
+    // proxies are REVOKED in the `finally` (never restored to raw onto `props`),
+    // so the live props object never aliases a prior request's identity. The tail
+    // serializes from the raw `msg` values via `tailProps` below.
+    const track = (
+      obj: Record<string, unknown> | undefined,
+      onTouch: () => void,
+    ) => {
+      const { proxy, revoke } = makeRevocableReadTrackingProxy(obj, onTouch);
+      proxyRevokers.push(revoke);
+      return proxy;
+    };
+
+    // 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 = track(
+      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) =>
+      track(obj, () => {
+        dynamicTouched = true;
+      });
+
+    // Phase 0 (auth bucketing): `props.session.exists` — the identity-FREE
+    // presence bit, so a page can render a binary auth nav WITHOUT reading real
+    // `auth`. Reading it sets `sessionTouched` (separate from authTouched): it
+    // vetoes the plain anonymous cache (the output now varies by signed-in
+    // bucket) but is PERMITTED by the bucket verdict (which keys the cache on the
+    // bucket).
+    let sessionTouched = false;
+    const sessionProxy = track(
+      { exists: msg.session_present === true },
+      () => {
+        sessionTouched = 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,
+      session: sessionProxy,
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
@@ -1818,6 +2062,23 @@ export async function handleRenderRoute(
       serverData,
     };
 
+    // PPR Phase 0: an immutable, pre-render SNAPSHOT of the only props a bucketed
+    // (SHARED) tail may serialize — url/params/searchParams, all path-derived and
+    // in the cache key. Deep-cloned NOW, before any page/generateMetadata code
+    // runs, because `props.params`/`searchParams` ARE the live `msg` objects: a
+    // page could mutate a nested field to smuggle identity (e.g.
+    // `props.searchParams.leak = props.auth`) WITHOUT tripping read-tracking, and
+    // a shallow allowlist would copy that mutation by reference into the shared
+    // tail. Captured only for opted-in pages (zero cost otherwise).
+    const bucketOptIn = (mod as any).cache === "auth-bucketed";
+    const bucketTailBase = bucketOptIn
+      ? {
+          url: msg.url,
+          params: jsonClone(msg.params),
+          searchParams: jsonClone(msg.search_params),
+        }
+      : null;
+
     // SEO metadata: static `export const metadata` or dynamic
     // `export async function generateMetadata(props)`. Awaited before the
     // first byte, so keep it to cheap derivations (params → title); heavy
@@ -1974,18 +2235,60 @@ export async function handleRenderRoute(
     // `!Loading`) is the gate: a `streaming = true` page has `Loading` null but
     // `wantsStream` true, and must still be excluded. Fail-closed. (See
     // computeCacheVerdict — pure + unit-tested for the leak class.)
-    const cacheable = computeCacheVerdict({
+    // PPR Phase 0: `bucketOptIn` (`export const cache = "auth-bucketed"`) was
+    // resolved at props-construction time (it gates the immutable bucketTailBase
+    // snapshot). A bucketed render and the plain anon cache are mutually exclusive
+    // — `cacheable` excludes the opt-in so a bucket page never also emits the anon
+    // proof.
+    const cacheable =
+      !bucketOptIn &&
+      computeCacheVerdict({
+        revalidateSecs,
+        forceDynamic,
+        authTouched,
+        dynamicTouched,
+        sessionTouched,
+        cookieCount: responseState.cookies.length,
+        strictPolicies,
+        wantsStream,
+        status: responseState.status,
+      });
+    // The bucket verdict permits `sessionTouched` (reading the binary signed-in
+    // bit) but still vetoes any real-auth read. When true, this render is stored
+    // as a shared, identity-free, session-presence-keyed entry — so its
+    // hydration tail MUST be anonymized (bucketAuth below) and it advertises the
+    // TRUSTED internal `x-pylon-bucket` proof for the host to key + store it.
+    const bucketable = computeBucketVerdict({
+      bucketOptIn,
       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;
+    // Serialization view of props built from the RAW `msg` values — the live
+    // `props` (with its read-tracking proxies) is NEVER mutated back to raw, so
+    // it can't become a vehicle that leaks a prior request's identity to a later
+    // render (the proxies are revoked in `finally`). headers/cookies are stripped
+    // inside buildHydrationTail; auth uses the raw value (so anon auth stays
+    // falsy/undefined rather than the proxy's empty `{}`). For a BUCKETED render,
+    // url/params/searchParams come from the pre-render `bucketTailBase` snapshot —
+    // NOT the live (page-mutable) props — so a page can't smuggle identity through
+    // a nested field into the shared tail. buildHydrationTail's bucket allowlist
+    // then serializes only these fields + the collapsed { signedIn } bit.
+    const tailProps = props
+      ? {
+          ...props,
+          auth: msg.auth,
+          headers: msg.headers,
+          cookies: msg.cookies,
+          session: { exists: msg.session_present === true },
+          ...(bucketable && bucketTailBase ? bucketTailBase : {}),
+        }
+      : props;
     // #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 +2308,16 @@ export async function handleRenderRoute(
       status: responseState.status,
       headers: finalizeHeaders(
         responseState,
-        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : {},
+        undefined,
+        // The #277 anon proof and the Phase 0 bucket proof both ride the TRUSTED
+        // `internal` channel (never stripped), so userland (page setHeader /
+        // route-handler headers via `extra`) can't forge either. Mutually
+        // exclusive (bucketOptIn splits the two verdicts).
+        bucketable
+          ? { "x-pylon-bucket": String(revalidateSecs) }
+          : cacheable
+            ? { "x-pylon-cacheable": String(revalidateSecs) }
+            : undefined,
       ),
     });
 
@@ -2144,7 +2456,7 @@ export async function handleRenderRoute(
       const tail = buildHydrationTail({
         component: msg.component,
         layouts: msg.layouts ?? [],
-        props,
+        props: tailProps,
         ssrData: ssrValueCache,
         manifestRoute: preloadManifestRoute,
         publicPrefix: preloadPublicPrefix,
@@ -2154,6 +2466,11 @@ export async function handleRenderRoute(
             ? "error"
             : "not-found"
           : undefined,
+        // A bucketed render is stored shared → its tail must carry ONLY the
+        // binary signed-in bit, never this request's real identity.
+        bucketAuth: bucketable
+          ? { signedIn: msg.session_present === true }
+          : undefined,
       });
       sendChunk(tail);
     }
@@ -2246,5 +2563,17 @@ export async function handleRenderRoute(
       message:
         devMode && err?.stack ? String(err.stack) : err?.message ?? String(err),
     });
+  } finally {
+    // Revoke this render's per-request proxies. Any reference a page stashed in
+    // module-level state (props or props.auth/headers/cookies/session) now throws
+    // on access from a LATER render — fail-closed, so a prior request's identity
+    // can never silently enter a cached body without tripping read-tracking.
+    for (const revoke of proxyRevokers) {
+      try {
+        revoke();
+      } catch {
+        // best-effort
+      }
+    }
   }
 }

package/src/ssr-streaming.test.ts

@@ -18,6 +18,7 @@ import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
 import {
   buildHydrationTail,
+  computeBucketVerdict,
   computeCacheVerdict,
   computeRevalidateSecs,
   computeWantsStream,
@@ -96,6 +97,8 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     revalidateSecs: 60 as number | null,
     forceDynamic: false,
     authTouched: false,
+    dynamicTouched: false,
+    sessionTouched: false,
     cookieCount: 0,
     strictPolicies: false,
     wantsStream: false,
@@ -110,6 +113,8 @@ 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, sessionTouched: true })).toBe(false); // read session.exists (anon cache)
     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 +138,8 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
                     revalidateSecs,
                     forceDynamic,
                     authTouched,
+                    dynamicTouched: false,
+                    sessionTouched: false,
                     cookieCount,
                     strictPolicies,
                     wantsStream,
@@ -148,6 +155,73 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
   });
 });
 
+describe("computeBucketVerdict (PPR Phase 0 — session-presence shared cache)", () => {
+  const base = {
+    bucketOptIn: true,
+    revalidateSecs: 60 as number | null,
+    forceDynamic: false,
+    authTouched: false,
+    dynamicTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    status: 200,
+  };
+
+  test("a clean opted-in bucketed 200 is bucketable", () => {
+    expect(computeBucketVerdict(base)).toBe(true);
+  });
+
+  test("sessionTouched is NOT a veto here (the whole point of a bucket)", () => {
+    // computeBucketVerdict has no sessionTouched field — reading session.exists
+    // is allowed. This test documents the contract by construction: the same
+    // base (which a bucket render reaches with sessionTouched=true) buckets.
+    expect(computeBucketVerdict(base)).toBe(true);
+  });
+
+  test("no opt-in → never buckets, even when otherwise clean", () => {
+    expect(computeBucketVerdict({ ...base, bucketOptIn: false })).toBe(false);
+  });
+
+  test("every identity/safety veto flips it to non-bucketable (fail-closed)", () => {
+    expect(computeBucketVerdict({ ...base, revalidateSecs: null })).toBe(false); // no TTL
+    expect(computeBucketVerdict({ ...base, forceDynamic: true })).toBe(false);
+    expect(computeBucketVerdict({ ...base, authTouched: true })).toBe(false); // read real auth
+    expect(computeBucketVerdict({ ...base, dynamicTouched: true })).toBe(false); // headers/cookies
+    expect(computeBucketVerdict({ ...base, cookieCount: 1 })).toBe(false); // set a cookie
+    expect(computeBucketVerdict({ ...base, strictPolicies: true })).toBe(false); // auth-filtered reads
+    expect(computeBucketVerdict({ ...base, wantsStream: true })).toBe(false); // streaming head
+    expect(computeBucketVerdict({ ...base, status: 404 })).toBe(false);
+    expect(computeBucketVerdict({ ...base, status: 307 })).toBe(false);
+  });
+
+  test("LOAD-BEARING: authTouched ALWAYS vetoes regardless of opt-in", () => {
+    // The proof that a bucketable body is identity-free: any output that depends
+    // on identity must read props.auth, which sets authTouched. So authTouched
+    // ⟹ !bucketable over the full cross-product.
+    const bools = [false, true];
+    for (const bucketOptIn of bools)
+      for (const dynamicTouched of bools)
+        for (const strictPolicies of bools)
+          for (const wantsStream of bools)
+            for (const cookieCount of [0, 1])
+              for (const status of [200, 404]) {
+                const v = computeBucketVerdict({
+                  bucketOptIn,
+                  revalidateSecs: 60,
+                  forceDynamic: false,
+                  authTouched: true,
+                  dynamicTouched,
+                  cookieCount,
+                  strictPolicies,
+                  wantsStream,
+                  status,
+                });
+                expect(v).toBe(false);
+              }
+  });
+});
+
 describe("diffCommittedResponse (#278 late-response.* drop detector)", () => {
   const snap = (over: any = {}) => ({
     status: 200,
@@ -300,3 +374,144 @@ describe("hydration tail ordering (#278: data blob before entry script)", () =>
     expect(tail).toContain('"body":"hi"');
   });
 });
+
+// ---------------------------------------------------------------------------
+// PPR Phase 0 — bucketed hydration tail must be IDENTITY-FREE
+// ---------------------------------------------------------------------------
+
+// Pull the __PYLON_DATA__ payload back out of a tail. JSON.parse natively
+// decodes the unicode escapes (< etc.) buildHydrationTail applies.
+function parsePylonData(tail: string): any {
+  const m = tail.match(
+    /<script id="__PYLON_DATA__" type="application\/json">([\s\S]*?)<\/script>/,
+  );
+  if (!m) throw new Error("no __PYLON_DATA__ blob in tail");
+  return JSON.parse(m[1]);
+}
+
+describe("bucketed hydration tail (PPR Phase 0 leak class)", () => {
+  // Two DIFFERENT signed-in identities. A non-bucketed tail serializes each
+  // verbatim; a bucketed tail MUST collapse both to `{ signedIn: true }`.
+  const alice = {
+    user_id: "user_alice",
+    tenant_id: "tenant_1",
+    roles: ["admin"],
+    email: "alice@x.com",
+  };
+  const bob = {
+    user_id: "user_bob",
+    tenant_id: "tenant_2",
+    roles: ["member"],
+    email: "bob@y.com",
+  };
+  const baseArgs = (auth: any) => ({
+    component: "app/page",
+    layouts: [],
+    props: {
+      url: "/",
+      params: {},
+      searchParams: {},
+      auth,
+      session: { exists: true },
+    },
+    ssrData: {},
+    manifestRoute: { file: "index.js", imports: [], css: [] },
+    publicPrefix: "/_pylon/build/",
+    manifestErr: null,
+  });
+
+  test("non-bucketed tail keeps real auth (unchanged legacy behavior)", () => {
+    const tail = buildHydrationTail(baseArgs(alice));
+    expect(parsePylonData(tail).props.auth).toEqual(alice);
+  });
+
+  test("bucketed signed-in tail carries ONLY { signedIn: true }", () => {
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      bucketAuth: { signedIn: true },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: true });
+    expect(data.props.session).toEqual({ exists: true });
+    // No identity escapes — not in props, not anywhere in the rendered tail.
+    expect(tail).not.toContain("user_alice");
+    expect(tail).not.toContain("tenant_1");
+    expect(tail).not.toContain("alice@x.com");
+    expect(tail).not.toContain("admin");
+  });
+
+  test("bucketed signed-out tail carries ONLY { signedIn: false }", () => {
+    const tail = buildHydrationTail({
+      ...baseArgs(null),
+      props: {
+        url: "/",
+        params: {},
+        searchParams: {},
+        auth: null,
+        session: { exists: false },
+      },
+      bucketAuth: { signedIn: false },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: false });
+    expect(data.props.session).toEqual({ exists: false });
+  });
+
+  test("LEAK INVARIANT: two identities → byte-identical bucketed tail", () => {
+    // The load-bearing property. If these two tails differed by a single byte,
+    // a shared cache entry would replay alice's identity to bob (or vice-versa).
+    const aTail = buildHydrationTail({
+      ...baseArgs(alice),
+      bucketAuth: { signedIn: true },
+    });
+    const bTail = buildHydrationTail({
+      ...baseArgs(bob),
+      bucketAuth: { signedIn: true },
+    });
+    expect(aTail).toBe(bTail);
+  });
+
+  test("bucketed tail DROPS page-added props (alias-identity fence, codex #4)", () => {
+    // A page can alias identity onto a custom key without tripping read-tracking
+    // (`props.leak = props.auth` — props is a plain object, no proxy trap). A
+    // bucketed (SHARED) tail must therefore serialize a strict ALLOWLIST of
+    // framework props, never a spread — else `leak` would carry one user's
+    // identity into every signed-in visitor's cached page.
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      props: {
+        url: "/",
+        params: { id: "x" },
+        searchParams: {},
+        auth: alice,
+        session: { exists: true },
+        // Page-aliased identity + a copied cookie bag.
+        leak: { uid: alice.user_id },
+        sneaky: alice.email,
+      },
+      bucketAuth: { signedIn: true },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: true });
+    // Allowlisted framework fields survive…
+    expect(data.props.url).toBe("/");
+    expect(data.props.params).toEqual({ id: "x" });
+    // …but the page-added keys are GONE, and no identity is anywhere in the tail.
+    expect(data.props.leak).toBeUndefined();
+    expect(data.props.sneaky).toBeUndefined();
+    expect(tail).not.toContain("user_alice");
+    expect(tail).not.toContain("alice@x.com");
+  });
+
+  test("NON-bucket tail still preserves page-added props (no behavior change)", () => {
+    // The allowlist applies ONLY to bucketed renders. A normal (non-shared)
+    // render keeps serializing all props so hydration matches the server tree.
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      props: { url: "/", params: {}, searchParams: {}, auth: alice, custom: 42 },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.custom).toBe(42);
+    expect(data.props.auth).toEqual(alice);
+  });
+});