# Cache-Control and Vary Response Headers

Load this reference when reviewing a Route Handler's (`route.ts`) or `getServerSideProps`'s response headers for a response derived from per-user data. Includes the MDN grounding reference for `Vary`; cite it only when a `Vary` finding is actually present.

## `Cache-Control: public` on per-user data

Any Route Handler or `getServerSideProps` call that sets `Cache-Control: public` (or a directive implying public cacheability, like a bare `s-maxage` with no `private`) authorizes every shared cache between the origin and the client -- CDN edge nodes, corporate proxies, ISP caches -- to store the response body and replay it to a *different* client that requests the same URL. If that body is derived from `cookies()`, a session token, or any other per-user request context, this is a direct cross-user data-exposure path, not a cosmetic caching choice.

```ts
// DANGEROUS: CDN may store and replay this session-derived body to any
// subsequent requester of the same URL.
export async function GET() {
  const session = (await cookies()).get('session')?.value
  const userData = await db.users.findBySession(session)
  return new Response(JSON.stringify(userData), {
    headers: { 'Cache-Control': 'public, max-age=300' },
  })
}
```

The documented fix is `Cache-Control: private`, which tells shared caches not to store the response at all -- only the requesting user's own browser may cache it locally. Next.js's own dynamically-rendered pages (including Draft Mode) set `private, no-cache, no-store, max-age=0, must-revalidate` by default for exactly this reason; an explicit `public` override on a per-user response works against that default protection.

```ts
// SAFE: shared caches must not store this response.
return new Response(JSON.stringify(userData), {
  headers: { 'Cache-Control': 'private, max-age=300' },
})
```

## `Vary` and cache-key selection

`Vary` tells a shared cache which request headers it must fold into the cache key -- two requests that differ only in a header *not* listed in `Vary` are treated as cache-equivalent and may share a cached response. If a response is `Cache-Control: public` (or otherwise CDN-cacheable) and is derived from a session cookie, but `Vary` does not include `Cookie` (or whatever header actually carries the session identifier), the CDN has no signal that two different users' requests need separate cache entries -- it may serve User A's cached response to User B simply because every other varied header (e.g. `Accept-Encoding`) happened to match.

```ts
// DANGEROUS: Cookie is absent from Vary, so the CDN cache-keys only on
// Accept-Encoding and may conflate two different users' requests.
return new Response(JSON.stringify(userData), {
  headers: {
    'Cache-Control': 'public, max-age=300',
    Vary: 'Accept-Encoding',
  },
})
```

```ts
// SAFE: Cookie is included, so the CDN keys its cache on the session value.
return new Response(JSON.stringify(userData), {
  headers: {
    'Cache-Control': 'public, max-age=300',
    Vary: 'Cookie, Accept-Encoding',
  },
})
```

This is standard HTTP caching semantics (see MDN's `Vary` reference in `official_docs`), not a Next.js-specific API -- ground this specific claim against the MDN URL rather than Context7 against `/vercel/next.js`, which does not reliably document general `Vary` mechanics.

## Reading the trace correctly

A `Vary` gap only matters when the response is otherwise cacheable by a shared cache (`Cache-Control: public`, or a `s-maxage`/CDN-level caching directive). If the response already sets `Cache-Control: private` (or relies on Next.js's dynamic-rendering default), the `Vary` value is moot -- do not raise a `Vary`-only finding on a response that is never stored by a shared cache in the first place. When both are wrong (public `Cache-Control` and an incomplete `Vary`), report them together as one `header-cache-bleed` finding with both header values named, not as two separate findings for the same response.

# Caching Directives and Route Segment Config

Load this reference when reviewing `revalidate`, `'use cache: private'`, `generateStaticParams`, or `dynamic` route segment config.

## `revalidate` and per-user data

`export const revalidate = N` (a route segment config export) tells Next.js to treat the rendered output of that route as fresh for up to `N` seconds, then re-render and re-cache it on the next request after the window elapses. This is a single, shared cache entry keyed on the route path (and any static params) -- it is not scoped to an individual visitor. If the render reads `cookies()`, `headers()`, or any other per-request/per-user API, the rendered HTML captured in that cache entry belongs to whichever request happened to trigger the re-render, and every other visitor who hits the same URL within the window receives that same cached, personalized output.

```tsx
// DANGEROUS: shared 60-second cache entry serves one user's session data to
// every visitor who hits this route within the window.
export const revalidate = 60

export default async function DashboardPage() {
  const session = (await cookies()).get('session')?.value
  const user = await db.users.findBySession(session)
  return <Dashboard user={user} />
}
```

The documented fix is not to shorten the window -- it is to remove the route-level `revalidate` export for personalized content and isolate the per-user lookup behind `'use cache: private'` instead (see below), or to make the route fully dynamic.

## `'use cache: private'`

`'use cache: private'` is a directive placed as the first statement inside a function body. It allows the function to read runtime request APIs (`cookies()`, `headers()`, `searchParams`) from within a cached scope, but the result is **never stored on the server** -- it is cached only in the requesting user's own browser, making it per-user by definition and safe to combine with cookie-derived lookups.

```tsx
async function getUser() {
  'use cache: private'
  const session = (await cookies()).get('session')?.value
  return db.users.findBySession(session)
}
```

Two structural checks matter here, not just the directive's presence:

- The directive must be the function's own first statement -- a function that reads `cookies()` and calls out to *another* function that has the directive does not itself get the protection unless the `cookies()` read happens inside the directive-scoped function.
- A function with `'use cache: private'` still needs the actual per-request read (`cookies()`, `headers()`) to happen inside it for the isolation to be meaningful -- a function that has the directive but reads no per-request data isn't wrong, but it also isn't evidence that some *other*, undirected function elsewhere is safe.

## `generateStaticParams` and personalized routes

`generateStaticParams` pre-computes which dynamic-segment values (`[id]`, `[userId]`, etc.) Next.js should statically render for a route. When the enumerated values are user- or account-scoped IDs and the route also renders authenticated, per-user data, pairing this with `revalidate` reproduces the same shared-cache-entry problem as above, except now the cache key includes the user ID segment -- so specifically, requests for `/account/123` from *different* people (e.g. a shared/public device, or a URL passed between users) hitting the route within the same revalidate window get the same cached response for that ID, not a fresh per-request one.

```tsx
// DANGEROUS: authenticated per-user page pre-rendered by ID, then reused for
// 60 seconds regardless of who requests it next.
export const revalidate = 60

export async function generateStaticParams() {
  const users = await db.users.findAll()
  return users.map((u) => ({ userId: u.id }))
}
```

The documented alternative for a route whose content must always reflect the current requester's own authenticated view is `export const dynamic = 'force-dynamic'`, which forces the route to render fresh on every request and skip both the static pre-render and the ISR cache entirely. Do not pair `generateStaticParams` enumerating auth-scoped IDs with `revalidate` on a route that renders session-derived content -- if the enumerated IDs are genuinely public and non-personalized (e.g. public blog post slugs), this pairing is fine and not a finding.

## Reading the trace correctly

When flagging any of the above, name the exact per-request API call (`cookies()`, `headers()`) and its exact reachability path from the flagged route-segment-config export -- a route segment config alone, with no per-request read anywhere in its render tree, is not a finding; conversely, a per-request read with no route-segment-config export at all is still a `missing-private-cache-boundary` finding on its own (see the main workflow reference), because a future caller could wrap it in a shared cache scope.

# Review Workflow and Findings Contract

Use this reference for the step-by-step review procedure and the required output shape. Load the other two references only for the specific caching surface the code under review actually raises.

## Prerequisites

- Confirm the Next.js major version and router in `package.json`. `'use cache: private'`, `revalidate` route segment config, and `dynamic = 'force-dynamic'` are App Router (Next.js 13+ `app/`) concepts. A Pages Router app (`pages/`) uses `getServerSideProps`/`getStaticProps` and `res.setHeader('Cache-Control', ...)` instead -- the header-based findings still apply there, but the directive-based findings (`'use cache: private'`, route segment `revalidate`) do not.
- Identify every route, layout, server function, and Route Handler that reads `cookies()`, `headers()`, or another per-request/per-user runtime API. These are the candidate personalization points this skill traces forward from.

## Workflow

1. **Locate every route segment config export.** Grep for `export const revalidate`, `export const dynamic`, and `generateStaticParams` across `app/**/page.tsx`, `app/**/layout.tsx`, and `app/**/route.ts`.
2. **For each route carrying `revalidate`, trace whether it (or any server function/component it renders) reads `cookies()`, `headers()`, or another per-request API.** If it does, check whether that specific lookup is isolated behind `'use cache: private'`. See `references/caching-directives-and-route-config.md` for the decision tree.
3. **For each route with `generateStaticParams`, inspect the params being enumerated.** If they are user-, account-, or org-scoped IDs, check whether the route is also authenticated (renders session-derived data) and whether it carries `revalidate` or defaults to static generation without `dynamic = 'force-dynamic'`.
4. **Enumerate every server function (not just page-level components) that reads `cookies()`/`headers()` to produce a per-user result.** For each, confirm `'use cache: private'` is declared as the function's own first statement -- do not accept "no cache export nearby" as sufficient; the isolation must be intrinsic to the function.
5. **Enumerate every Route Handler (`route.ts`) and `getServerSideProps` call that sets response headers.** For each, trace whether the response body is derived from `cookies()`/session/account data, and check the `Cache-Control` and `Vary` header values. See `references/cache-control-and-vary-headers.md`.
6. **Produce ranked findings** using the output contract below.

## Decision tree

- Route carries `export const revalidate = N` and reads `cookies()` (directly or via a called function) with no `'use cache: private'` isolating that read → **HIGH** finding, `revalidate-cookie-bleed`. The shared ISR cache entry serves the first requester's personalized render to everyone else within the window.
- A server function reads `cookies()`/`headers()` to produce a per-user result and declares no `'use cache: private'` (or equivalent) boundary of its own → **HIGH** finding, `missing-private-cache-boundary`, regardless of whether a `revalidate` export currently sits nearby -- the risk is that any future caching wrapper reintroduces the bleed with no defense at the function itself.
- `generateStaticParams` enumerates user/account-scoped IDs, the route also carries `revalidate`, and the page renders authenticated per-user data → **HIGH** finding, `static-params-auth-bleed`. The safe fix is `export const dynamic = 'force-dynamic'` with no `revalidate`/static-params pairing for that authenticated path.
- `generateStaticParams` enumerates IDs for genuinely public, non-personalized content (e.g. public blog post IDs with no auth-gated data in the render) → not a finding; state this explicitly rather than silently omitting it.
- A Route Handler or `getServerSideProps` response derived from `cookies()`/session data sets `Cache-Control: public` (or omits `Cache-Control` while behind a CDN that caches by default) → **HIGH** finding, `header-cache-bleed`.
- The same response also sets `Vary` but the value does not include `Cookie` (or the actual header carrying the session identifier) → **MEDIUM-to-HIGH** finding depending on whether the surface is public-facing or requires an existing session to reach, `header-cache-bleed`. A `Cache-Control: private` response makes the `Vary` gap moot -- only flag it when the response is otherwise CDN-cacheable.
- Response sets `Cache-Control: private`, or relies on Next.js's documented dynamic-rendering default (`private, no-cache, no-store, max-age=0, must-revalidate`), for a `cookies()`-derived response → not a finding.

## Output contract

Every response from this skill must return:

1. **Scope** -- the route(s), server function(s), and/or response-header call sites reviewed.
2. **Ranked findings** -- each with file:line, defect category (`revalidate-cookie-bleed` / `missing-private-cache-boundary` / `static-params-auth-bleed` / `header-cache-bleed`), the concrete data-flow trace (the route segment config and the per-request read it coexists with, or the header value and the per-user data source), and a fix sketch matching Next.js's documented pattern.
3. **Cache-boundary status per `cookies()`-derived finding** -- an explicit statement of whether `'use cache: private'` (or `Cache-Control: private`) is present on the traced path; never infer one exists elsewhere in the codebase.
4. **Evidence level per finding** -- `repo evidence`, `documentation-based`, or `inference`. Label structural risk findings as structural risk explicitly -- do not imply confirmed exploitation without live evidence (e.g., a captured cross-user response from a deployed CDN).
5. **Verdict** -- approve / approve-with-notes / block.
6. **Open questions or out-of-scope items** -- e.g., "confirming an actual cross-user response replay requires a live CDN reproduction with two concurrent sessions, not static review," or "ISR revalidation-timing tuning is out of scope -- this review covers cache-boundary correctness, not cache-hit-ratio performance."

## When to push back

Push back if the user asks to:

- approve a `revalidate`-plus-`cookies()` route because "the window is only 10 seconds, so the exposure is small" -- any nonzero shared window during which a personalized response is replayed to a different user is a data-exposure defect, not a tunable performance tradeoff,
- skip the `'use cache: private'` check on a server function because "nothing currently wraps it in a shared cache" -- the isolation needs to be intrinsic to the function so a future refactor cannot silently reintroduce the bleed,
- treat a `Vary: Cookie` header as sufficient on its own without checking `Cache-Control` -- if `Cache-Control` is `private` (or absent, defaulting to Next.js's dynamic-rendering default), the CDN never caches the response at all and `Vary` is moot; if `Cache-Control` is `public`, `Vary: Cookie` alone does not make blanket caching safe unless every downstream cache actually honors `Vary` correctly,
- downgrade an untraced `generateStaticParams`-plus-`revalidate` finding on an authenticated route to informational because "it's probably fine" -- this skill's default is HIGH for exactly this class of unproven claim.