fix(shared): Include suffixed cookie names in Netlify-Vary header

Clerk uses suffixed cookies (e.g. __client_uat_AbC12345) by default for
newer instances. The Netlify-Vary header now includes both unsuffixed and
suffixed cookie names computed from the publishable key, ensuring CDN
cache isolation works for all Clerk instances.

Author: wobsoriano

packages/astro/src/server/clerk-middleware.ts

@@ -121,7 +121,7 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
       createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
     );
 
-    handleNetlifyCacheHeaders(requestState);
+    await handleNetlifyCacheHeaders(requestState);
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {

packages/nextjs/src/server/clerkMiddleware.ts

@@ -221,7 +221,7 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
         reason: requestState.reason,
       }));
 
-      handleNetlifyCacheHeaders(requestState);
+      await handleNetlifyCacheHeaders(requestState);
 
       const locationHeader = requestState.headers.get(constants.Headers.Location);
       if (locationHeader) {

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -87,7 +87,7 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
       acceptsToken: 'any',
     });
 
-    handleNetlifyCacheHeaders(requestState);
+    await handleNetlifyCacheHeaders(requestState);
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {

packages/react-router/src/server/clerkMiddleware.ts

@@ -88,7 +88,7 @@ export const clerkMiddleware = (options?: ClerkMiddlewareOptions): MiddlewareFun
       __keylessApiKeysUrl,
     });
 
-    handleNetlifyCacheHeaders(requestState);
+    await handleNetlifyCacheHeaders(requestState);
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {

packages/shared/src/__tests__/netlifyCacheHandler.spec.ts

@@ -1,6 +1,7 @@
 /* eslint-disable turbo/no-undeclared-env-vars */
 import { beforeEach, describe, expect, it } from 'vitest';
 
+import { getCookieSuffix } from '../keys';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM, handleNetlifyCacheHeaders } from '../netlifyCacheHandler';
 
 const mockDevPublishableKey = 'pk_test_YW55LW9mZabcZS1wYWdlX3BhZ2VfcG9pbnRlci1pZF90ZXN0XzE';
@@ -14,86 +15,98 @@ describe('handleNetlifyCacheHeaders', () => {
   });
 
   describe('Netlify-Vary header', () => {
-    it('should set Netlify-Vary header when on Netlify', () => {
+    it('should set Netlify-Vary header with unsuffixed and suffixed cookie names when on Netlify', async () => {
       process.env.NETLIFY = 'true';
 
       const headers = new Headers();
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
 
-      expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
+      const suffix = await getCookieSuffix(mockProdPublishableKey);
+      expect(headers.get('Netlify-Vary')).toBe(
+        `cookie=__client_uat,cookie=__session,cookie=__client_uat_${suffix},cookie=__session_${suffix}`,
+      );
     });
 
-    it('should not set Netlify-Vary header when not on Netlify', () => {
+    it('should not set Netlify-Vary header when not on Netlify', async () => {
       const headers = new Headers();
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
 
       expect(headers.get('Netlify-Vary')).toBeNull();
     });
 
-    it('should detect Netlify via NETLIFY_FUNCTIONS_TOKEN', () => {
+    it('should detect Netlify via NETLIFY_FUNCTIONS_TOKEN', async () => {
       process.env.NETLIFY_FUNCTIONS_TOKEN = 'some-token';
 
       const headers = new Headers();
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
 
-      expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
+      expect(headers.get('Netlify-Vary')).toContain('cookie=__client_uat');
     });
 
-    it('should detect Netlify via URL ending with netlify.app', () => {
+    it('should detect Netlify via URL ending with netlify.app', async () => {
       process.env.URL = 'https://example.netlify.app';
 
       const headers = new Headers();
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+
+      expect(headers.get('Netlify-Vary')).toContain('cookie=__client_uat');
+    });
+
+    it('should fall back to unsuffixed cookies only when publishableKey is empty', async () => {
+      process.env.NETLIFY = 'true';
+
+      const headers = new Headers();
+      await handleNetlifyCacheHeaders({ headers, publishableKey: '' });
 
       expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
     });
   });
 
   describe('cache bust parameter (dev instances)', () => {
-    it('should add cache bust parameter when on Netlify and in development with Location header', () => {
+    it('should add cache bust parameter when on Netlify and in development with Location header', async () => {
       process.env.NETLIFY = 'true';
 
       const headers = new Headers({ Location: 'https://example.netlify.app' });
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
 
       const locationUrl = new URL(headers.get('Location') || '');
       expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
     });
 
-    it('should not add cache bust parameter for production instances', () => {
+    it('should not add cache bust parameter for production instances', async () => {
       process.env.NETLIFY = 'true';
 
       const headers = new Headers({ Location: 'https://example.netlify.app' });
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
 
       const locationUrl = new URL(headers.get('Location') || '');
       expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(false);
     });
 
-    it('should not modify the Location header if it has the handshake param', () => {
+    it('should not modify the Location header if it has the handshake param', async () => {
       process.env.NETLIFY = 'true';
 
       const locationValue = 'https://example.netlify.app/redirect?__clerk_handshake=';
       const headers = new Headers({ Location: locationValue });
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
 
       expect(headers.get('Location')).toBe(locationValue);
     });
 
-    it('should not modify the Location header if not on Netlify', () => {
+    it('should not modify the Location header if not on Netlify', async () => {
       const headers = new Headers({ Location: 'https://example.com' });
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
 
       expect(headers.get('Location')).toBe('https://example.com');
     });
 
-    it('should ignore the URL environment variable if it is not a string', () => {
+    it('should ignore the URL environment variable if it is not a string', async () => {
       // @ts-expect-error - Random object
       process.env.URL = {};
       process.env.NETLIFY = 'true';
 
       const headers = new Headers({ Location: 'https://example.netlify.app' });
-      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+      await handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
 
       const locationUrl = new URL(headers.get('Location') || '');
       expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);

packages/shared/src/netlifyCacheHandler.ts

@@ -1,5 +1,5 @@
 /* eslint-disable turbo/no-undeclared-env-vars */
-import { isDevelopmentFromPublishableKey } from './keys';
+import { getCookieSuffix, isDevelopmentFromPublishableKey } from './keys';
 
 /**
  * Cache busting parameter for Netlify to prevent cached responses
@@ -32,23 +32,33 @@ function isNetlifyRuntime(): boolean {
  * Applies Netlify-specific cache headers to the request state.
  *
  * When running on Netlify, this function:
- * 1. Sets `Netlify-Vary: cookie=__client_uat,cookie=__session` to instruct Netlify's CDN
- *    to create separate cache entries based on auth cookie values, preventing cached auth
- *    state from bleeding across users/sessions.
+ * 1. Sets `Netlify-Vary` with both unsuffixed and suffixed Clerk cookie names to instruct
+ *    Netlify's CDN to create separate cache entries based on auth cookie values, preventing
+ *    cached auth state from bleeding across users/sessions.
  * 2. For development instances with a redirect (Location header), adds a cache-bust query
  *    parameter to prevent Netlify from serving cached responses during the handshake flow.
  *
  * @internal
  */
-export function handleNetlifyCacheHeaders(requestState: { headers: Headers; publishableKey: string }): void {
+export async function handleNetlifyCacheHeaders(requestState: {
+  headers: Headers;
+  publishableKey: string;
+}): Promise<void> {
   if (!isNetlifyRuntime()) {
     return;
   }
 
   const { headers, publishableKey } = requestState;
 
-  // Tell Netlify CDN to vary cache by auth cookie values (all instances, dev + prod)
-  headers.set('Netlify-Vary', 'cookie=__client_uat,cookie=__session');
+  // Tell Netlify CDN to vary cache by auth cookie values (all instances, dev + prod).
+  // Include both unsuffixed and suffixed cookie names since Clerk uses suffixed cookies
+  // by default for newer instances (e.g. __client_uat_AbC12345).
+  const cookieNames = ['__client_uat', '__session'];
+  if (publishableKey) {
+    const suffix = await getCookieSuffix(publishableKey);
+    cookieNames.push(`__client_uat_${suffix}`, `__session_${suffix}`);
+  }
+  headers.set('Netlify-Vary', cookieNames.map(name => `cookie=${name}`).join(','));
 
   // Add cache-bust param to redirect URL for dev instances to prevent cached redirects
   const locationHeader = headers.get('Location');
@@ -66,7 +76,7 @@ export function handleNetlifyCacheHeaders(requestState: { headers: Headers; publ
  * @deprecated Use `handleNetlifyCacheHeaders` instead.
  * @internal
  */
-export function handleNetlifyCacheInDevInstance({
+export async function handleNetlifyCacheInDevInstance({
   locationHeader: _locationHeader,
   requestStateHeaders,
   publishableKey,
@@ -75,5 +85,5 @@ export function handleNetlifyCacheInDevInstance({
   requestStateHeaders: Headers;
   publishableKey: string;
 }) {
-  handleNetlifyCacheHeaders({ headers: requestStateHeaders, publishableKey });
+  await handleNetlifyCacheHeaders({ headers: requestStateHeaders, publishableKey });
 }

packages/tanstack-react-start/src/server/clerkMiddleware.ts

@@ -48,7 +48,7 @@ export const clerkMiddleware = (
       acceptsToken: 'any',
     });
 
-    handleNetlifyCacheHeaders(requestState);
+    await handleNetlifyCacheHeaders(requestState);
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {