@pylonsync/functions 0.3.298 → 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
@@ -151,6 +157,30 @@ export declare function makeResponseController(state: ResponseState, defaultRedi
  * 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
@@ -334,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
@@ -361,6 +394,47 @@ export declare function computeRevalidateSecs(mod: any): number | null;
  * cached). Fail-closed: every condition must hold.
  */
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.298",
+  "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

@@ -17,6 +17,8 @@ import {
   finalizeHeaders,
   makeResponseController,
   makeReadTrackingProxy,
+  makeRevocableReadTrackingProxy,
+  jsonClone,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -148,6 +150,42 @@ describe("reserved x-pylon-* header namespace (cache-proof forgery fence)", () =
     });
     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
@@ -321,7 +327,37 @@ export function makeReadTrackingProxy(
   obj: Record<string, unknown> | undefined,
   onTouch: () => void,
 ): Record<string, unknown> {
-  return new Proxy((obj ?? {}) as 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);
@@ -1202,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
@@ -1216,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,
@@ -1563,12 +1629,71 @@ export function computeCacheVerdict(args: {
   // 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;
+  status: number;
+}): boolean {
+  return (
+    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 &&
@@ -1791,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
@@ -1869,14 +1999,24 @@ export async function handleRenderRoute(
 
     // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
     // 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.
+    // 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 = makeReadTrackingProxy(
+    const authProxy = track(
       msg.auth as Record<string, unknown> | undefined,
       () => {
         authTouched = true;
@@ -1889,10 +2029,24 @@ export async function handleRenderRoute(
     // cookies — the framework's metadata path reads `msg.headers` directly.
     let dynamicTouched = false;
     const touchProxy = (obj: Record<string, unknown> | undefined) =>
-      makeReadTrackingProxy(obj, () => {
+      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,
@@ -1900,6 +2054,7 @@ export async function handleRenderRoute(
       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,
@@ -1907,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
@@ -2063,7 +2235,31 @@ 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,
@@ -2073,13 +2269,26 @@ export async function handleRenderRoute(
       wantsStream,
       status: responseState.status,
     });
-    // 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;
-    }
+    // 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
@@ -2100,10 +2309,15 @@ export async function handleRenderRoute(
       headers: finalizeHeaders(
         responseState,
         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,
+        // 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,
       ),
     });
 
@@ -2242,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,
@@ -2252,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);
     }
@@ -2344,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,
@@ -97,6 +98,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     forceDynamic: false,
     authTouched: false,
     dynamicTouched: false,
+    sessionTouched: false,
     cookieCount: 0,
     strictPolicies: false,
     wantsStream: false,
@@ -112,6 +114,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     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
@@ -136,6 +139,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
                     forceDynamic,
                     authTouched,
                     dynamicTouched: false,
+                    sessionTouched: false,
                     cookieCount,
                     strictPolicies,
                     wantsStream,
@@ -151,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,
@@ -303,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);
+  });
+});