Opt-in ISR for pages that are identical for every user behind Cloudflare Access #482

Summary

Void skips ISR for every request that carries Cookie, Authorization, or (since #335) Cf-Access-Jwt-Assertion (Cache bypass). That is the right default. But it means an app behind Cloudflare Access, including a Void Platform project with Zero Trust protection, can never be served from the ISR cache, even for pages that are the same for everyone Access lets in. The Zero Trust docs already note the cost: "Protected pages render on each request, which can increase latency and request usage." (Caching)

Access decides who may see the app. I'd like a per-path opt-in where the developer states that the response is the same for everyone Access admits, so Void can serve it from the ISR cache once Access has admitted the request. The default would not change.

Use case

A private, annotated collection of statutes behind Access: tens of thousands of pages, a handful of readers, most pages rarely opened. The statute pages are the same for every reader, so we want each page rendered on first request and served from the ISR cache afterwards. Per-user parts (bookmarks, notes, "last read") come from islands that call uncached /api routes, so the cached HTML stays shared. Streaming such parts with defer() would not work, since they would be stored as part of the cached response. output: "static" would render every page on every build, while most pages are never read. Behind Access today, every view renders instead.

What reaches the Worker behind Access

Checked on our production site (workers.dev, protected by Access) with a route that returns only cookie names and header presence: a signed-in browser's request reaches the Worker with the cookies CF_AppSession and CF_Authorization, the headers Cf-Access-Jwt-Assertion and Cf-Access-Authenticated-User-Email, and no Authorization header. Each of these alone is enough to bypass ISR today.

Proposal

The name is a placeholder. The opt-in could sit next to the per-page revalidate export (and, mirroring revalidate, as a routing pattern in void.config.ts):

// pages/laws/[id].server.ts
export const revalidate = 31536000;
export const sharedBehindAccess = true; // placeholder name

What the opt-in means. The whole cached response (layout, embedded loader data and headers included) is the same for every user Access admits, and no authorization beyond Access is needed. The second half matters because a cache hit is served before the app runs: in 1.1.11 the ISR lookup in the Worker's fetch handler comes before app.fetch, so middleware does not run on a hit (void/dist/runtime/routing.mjs). A page that reads the identity, or relies on app middleware to turn some admitted users away, must not opt in.

For a path that opts in:

• Ignored credentials. Void parses the Cookie header. If every cookie name is CF_Authorization or CF_AppSession (exact names; both are documented on the application hostname in Authorization cookie, and both reach the Worker as shown above) and the only other credential is Cf-Access-Jwt-Assertion, the request uses the ISR cache like a public request. Any other cookie, and any Authorization header, still bypasses the cache. No prefix matching such as CF_*; CF_Binding is stripped before the origin, and CF_Session and CF_Device belong to the team domain.
• Storage rules unchanged. Whether to store is decided on the app's response as today (complete 200 only; no Set-Cookie, private, no-store, no-cache or Vary on request headers; x-revalidate: 0 still opts out).
• Browser-facing copy is private. For requests that carried Access credentials, the copy sent to the browser gets Cache-Control: private, no-cache instead of public, max-age=0, must-revalidate, on MISS, HIT, STALE and after background revalidation alike. The runtime already builds the stored copy and the client copy separately (clientRevalidateResponse() in @void/isr).
• Same boundary for the Pages JSON. The X-VoidPages JSON variant follows the same rules as the HTML.
• Paths that don't opt in behave exactly as today.

Safety

• Cache hits stay behind the existing checks. On Void Platform, feat(platform): add project Zero Trust protection #335 says that dispatch checks the Access JWT again before it serves Worker, static or ISR content; every hit for an opted-in path must keep that order. With direct Cloudflare deploys, Access runs in front of the Worker; this proposal relies on that, does not treat the presence of an Access cookie or header as proof, and does not ask for JWT validation in the Worker.
• No reuse across hostnames. Entries are keyed by hostname, so an entry filled through a protected hostname is never served on another one.
• Identity-read detection is only an aid. Every admitted request carries Cf-Access-Authenticated-User-Email, so a render can always read the identity. Void could warn in dev, or refuse to store, when a render on an opted-in path reads it, but a hit renders nothing; the developer's statement is what safety rests on. The docs should say so plainly, as fix(auth): keep private route cache policies on authenticated responses #408 does for hand-written ETags.

Acceptance criteria

• A cache entry filled by admitted user A is served to admitted user B.
• No content is served from the cache to a request that is unauthenticated, carries invalid credentials, or was rejected by Access, even when an entry exists.
• A request with any non-Access cookie or an Authorization header neither reads nor writes the cache.
• MISS, HIT, STALE and background revalidation apply the same storage rules and the same browser-facing policy.
• The X-VoidPages JSON variant follows the same boundary as the HTML.

Current workaround and alternatives

We turned ISR off and cache the HTML in our own Cache API middleware. It works, but it loses stale-while-revalidate, per-path TTLs and revalidate({ paths }), and it ignores every credential, not only Access's (in the reproduction it served cached pages to requests with other cookies or Authorization). An Access Bypass policy for those paths would make them public. output: "static" is covered in the use case above.

Open questions

• Naming, and whether the opt-in belongs in a per-page export, in routing, or both; a single switch may suit an app that sits entirely behind Access.
• Cloudflare's edge cookies (__cf_bm, cf_clearance) on custom domains where Bot Fight Mode or a WAF challenge runs alongside Access.

Environment

• void@1.1.11, @void/md, React 19.3.1, Vite 8.3.4, Node.js 24.22.0, pnpm 12.14.0
• Production: void deploy --platform cloudflare to workers.dev, protected by Access ("Manage Worker access"). ISR is off there.
• Reproduction: local vite preview (workerd) with a local KV namespace as ISR_CACHE.