feat: pass cache headers to setAll to prevent CDN caching of auth responses

[mandarini]

What

SetAllCookies now receives a required second argument headers: Record<string, string> alongside the cookies array. When applyServerStorage calls setAll after a token refresh or any auth state change, it passes the following headers:

{
  'Cache-Control': 'private, no-cache, no-store, must-revalidate, max-age=0',
  'Expires': '0',
  'Pragma': 'no-cache',
}

Users must apply these headers to their HTTP response in their setAll implementation:

// Next.js middleware
cookies: {
  setAll(cookiesToSet, headers) {
    cookiesToSet.forEach(({ name, value, options }) =>
      response.cookies.set(name, value, options)
    )
    Object.entries(headers).forEach(([key, value]) =>
      response.headers.set(key, value)
    )
  }
}

// Nuxt server middleware
cookies: {
  setAll(cookiesToSet, headers) {
    cookiesToSet.forEach(({ name, value, options }) =>
      setCookie(event, name, value, options)
    )
    Object.entries(headers).forEach(([key, value]) =>
      setHeader(event, key, value)
    )
  }
}

Why

See: supabase/supabase-js#1682

When @supabase/ssr refreshes a session server-side, the new JWT is written to the response via Set-Cookie. If a CDN (CloudFront, Vercel Edge, Cloudflare, etc.) caches that response and serves it to a different user, that user's browser stores the cached token and is signed in as the wrong person. This has been confirmed in production by multiple users.

The library knows exactly when this happens, which is inside applyServerStorage, triggered by the TOKEN_REFRESHED event, but previously gave the user no way to know they needed to set cache headers. The fix surfaces that information directly in the setAll callback.

Breaking change

SetAllCookies now has a required second argument. Existing setAll implementations that do not declare the second parameter will not receive a TypeScript error (TypeScript allows functions with fewer parameters to satisfy a type expecting more), but they will silently miss applying the headers. All official quickstart examples and docs will be updated to include the headers.

What was considered and ruled out

• serverRefresh: false option: Rejected. The server must be able to refresh an expired token before rendering auth-gated pages — skipping server-side refresh entirely breaks the core SSR auth flow.
• Docs-only fix: Insufficient. Users who copy an outdated quickstart or don't read the changelog stay insecure without knowing it.
• Optional headers? argument: Also insufficient for the same reason — optional typing gives users an escape hatch and TypeScript won't warn them.
• Setting headers on the fetch request: auth-js previously added cache: no-store to outgoing fetch requests (PR #847) and had to revert it (PR #886) because it broke Cloudflare's fetch handling. That was a different mechanism (Next.js Data Cache on outgoing requests). Our change operates at the HTTP response level via the user's setAll callback and does not touch fetch options.

Files changed

• src/types.ts — SetAllCookies type updated with required headers second argument and JSDoc
• src/cookies.ts — applyServerStorage passes cache headers; browser-only setAll call sites pass {}
• src/cookies.spec.ts — existing tests updated; new assertion verifies applyServerStorage passes the correct headers

Related: supabase/supabase-js#1682

[jonzhep]

amazing work