fix(shared): Add Netlify-Vary header to prevent CDN caching of auth responses

wobsoriano · wobsoriano · commit 2c89aed84870 · 2026-03-10T09:37:38.000-07:00
Consolidate Netlify cache handling into a single `handleNetlifyCacheHeaders`
function that sets `Netlify-Vary: cookie=__client_uat,cookie=__session` on all
auth responses when running on Netlify. This prevents the CDN from serving
stale session state across different users/sessions.

The function is called once per request in each framework SDK middleware,
right after `authenticateRequest` returns, replacing the previous dev-only
cache-bust approach with proper CDN cache isolation for both dev and prod.
diff --git a/.changeset/netlify-vary-cache-headers.md b/.changeset/netlify-vary-cache-headers.md
@@ -0,0 +1,10 @@
+---
+"@clerk/shared": patch
+"@clerk/nextjs": patch
+"@clerk/astro": patch
+"@clerk/react-router": patch
+"@clerk/nuxt": patch
+"@clerk/tanstack-react-start": patch
+---
+
+Add `Netlify-Vary` header to prevent Netlify CDN from caching auth responses across different users/sessions. Sets `Netlify-Vary: cookie=__client_uat,cookie=__session` on all auth responses when running on Netlify, ensuring the CDN creates separate cache entries per auth state.
diff --git a/packages/astro/src/server/clerk-middleware.ts b/packages/astro/src/server/clerk-middleware.ts
@@ -16,7 +16,7 @@ import {
   TokenType,
 } from '@clerk/backend/internal';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { handleNetlifyCacheHeaders } from '@clerk/shared/netlifyCacheHandler';
 import { isHttpOrHttps } from '@clerk/shared/proxy';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 import { handleValueOrFn } from '@clerk/shared/utils';
@@ -121,14 +121,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
       createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
     );
 
+    handleNetlifyCacheHeaders(requestState);
+
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
-      handleNetlifyCacheInDevInstance({
-        locationHeader,
-        requestStateHeaders: requestState.headers,
-        publishableKey: requestState.publishableKey,
-      });
-
       const res = new Response(null, { status: 307, headers: requestState.headers });
       return decorateResponseWithObservabilityHeaders(res, requestState);
     } else if (requestState.status === AuthStatus.Handshake) {
diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts
@@ -22,7 +22,7 @@ import {
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
 import { parsePublishableKey } from '@clerk/shared/keys';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { handleNetlifyCacheHeaders } from '@clerk/shared/netlifyCacheHandler';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -221,14 +221,10 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
         reason: requestState.reason,
       }));
 
+      handleNetlifyCacheHeaders(requestState);
+
       const locationHeader = requestState.headers.get(constants.Headers.Location);
       if (locationHeader) {
-        handleNetlifyCacheInDevInstance({
-          locationHeader,
-          requestStateHeaders: requestState.headers,
-          publishableKey: requestState.publishableKey,
-        });
-
         const res = NextResponse.redirect(requestState.headers.get(constants.Headers.Location) || locationHeader);
         requestState.headers.forEach((value, key) => {
           if (key === constants.Headers.Location) {
diff --git a/packages/nuxt/src/runtime/server/clerkMiddleware.ts b/packages/nuxt/src/runtime/server/clerkMiddleware.ts
@@ -1,6 +1,6 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
 import { AuthStatus, constants, getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { handleNetlifyCacheHeaders } from '@clerk/shared/netlifyCacheHandler';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
@@ -87,13 +87,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
       acceptsToken: 'any',
     });
 
+    handleNetlifyCacheHeaders(requestState);
+
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
-      handleNetlifyCacheInDevInstance({
-        locationHeader,
-        requestStateHeaders: requestState.headers,
-        publishableKey: requestState.publishableKey,
-      });
       // Trigger a handshake redirect
       return new Response(null, { status: 307, headers: requestState.headers });
     }
diff --git a/packages/react-router/src/server/clerkMiddleware.ts b/packages/react-router/src/server/clerkMiddleware.ts
@@ -1,7 +1,7 @@
 import type { AuthObject } from '@clerk/backend';
 import type { RequestState } from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest } from '@clerk/backend/internal';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { handleNetlifyCacheHeaders } from '@clerk/shared/netlifyCacheHandler';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 import type { MiddlewareFunction } from 'react-router';
 import { createContext } from 'react-router';
@@ -88,13 +88,10 @@ export const clerkMiddleware = (options?: ClerkMiddlewareOptions): MiddlewareFun
       __keylessApiKeysUrl,
     });
 
+    handleNetlifyCacheHeaders(requestState);
+
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
-      handleNetlifyCacheInDevInstance({
-        locationHeader,
-        requestStateHeaders: requestState.headers,
-        publishableKey: requestState.publishableKey,
-      });
       // Trigger a handshake redirect
       return new Response(null, { status: 307, headers: requestState.headers });
     }
diff --git a/packages/shared/src/__tests__/netlifyCacheHandler.spec.ts b/packages/shared/src/__tests__/netlifyCacheHandler.spec.ts
@@ -1,85 +1,102 @@
 /* eslint-disable turbo/no-undeclared-env-vars */
 import { beforeEach, describe, expect, it } from 'vitest';
 
-import { CLERK_NETLIFY_CACHE_BUST_PARAM, handleNetlifyCacheInDevInstance } from '../netlifyCacheHandler';
+import { CLERK_NETLIFY_CACHE_BUST_PARAM, handleNetlifyCacheHeaders } from '../netlifyCacheHandler';
 
-const mockPublishableKey = 'pk_test_YW55LW9mZabcZS1wYWdlX3BhZ2VfcG9pbnRlci1pZF90ZXN0XzE';
+const mockDevPublishableKey = 'pk_test_YW55LW9mZabcZS1wYWdlX3BhZ2VfcG9pbnRlci1pZF90ZXN0XzE';
+const mockProdPublishableKey = 'pk_live_YW55LW9mZabcZS1wYWdlX3BhZ2VfcG9pbnRlci1pZF90ZXN0XzE';
 
-describe('handleNetlifyCacheInDevInstance', () => {
+describe('handleNetlifyCacheHeaders', () => {
   beforeEach(() => {
     delete process.env.URL;
     delete process.env.NETLIFY;
+    delete process.env.NETLIFY_FUNCTIONS_TOKEN;
   });
 
-  it('should add cache bust parameter when on Netlify and in development', () => {
-    process.env.NETLIFY = 'true';
-    process.env.URL = 'https://example.netlify.app';
+  describe('Netlify-Vary header', () => {
+    it('should set Netlify-Vary header when on Netlify', () => {
+      process.env.NETLIFY = 'true';
 
-    const requestStateHeaders = new Headers({
-      Location: 'https://example.netlify.app',
+      const headers = new Headers();
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+
+      expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
     });
-    const locationHeader = requestStateHeaders.get('Location') || '';
 
-    handleNetlifyCacheInDevInstance({
-      locationHeader,
-      requestStateHeaders,
-      publishableKey: mockPublishableKey,
+    it('should not set Netlify-Vary header when not on Netlify', () => {
+      const headers = new Headers();
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+
+      expect(headers.get('Netlify-Vary')).toBeNull();
     });
 
-    const locationUrl = new URL(requestStateHeaders.get('Location') || '');
-    expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
-  });
+    it('should detect Netlify via NETLIFY_FUNCTIONS_TOKEN', () => {
+      process.env.NETLIFY_FUNCTIONS_TOKEN = 'some-token';
 
-  it('should not modify the Location header if it has the handshake param', () => {
-    process.env.URL = 'https://example.netlify.app';
-    process.env.NETLIFY = 'true';
+      const headers = new Headers();
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
 
-    const requestStateHeaders = new Headers({
-      Location: 'https://example.netlify.app/redirect?__clerk_handshake=',
+      expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
     });
-    const locationHeader = requestStateHeaders.get('Location') || '';
 
-    handleNetlifyCacheInDevInstance({
-      locationHeader,
-      requestStateHeaders,
-      publishableKey: mockPublishableKey,
-    });
+    it('should detect Netlify via URL ending with netlify.app', () => {
+      process.env.URL = 'https://example.netlify.app';
 
-    expect(requestStateHeaders.get('Location')).toBe(locationHeader);
+      const headers = new Headers();
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+
+      expect(headers.get('Netlify-Vary')).toBe('cookie=__client_uat,cookie=__session');
+    });
   });
 
-  it('should not modify the Location header if not on Netlify', () => {
-    const requestStateHeaders = new Headers({
-      Location: 'https://example.netlify.app',
+  describe('cache bust parameter (dev instances)', () => {
+    it('should add cache bust parameter when on Netlify and in development with Location header', () => {
+      process.env.NETLIFY = 'true';
+
+      const headers = new Headers({ Location: 'https://example.netlify.app' });
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+
+      const locationUrl = new URL(headers.get('Location') || '');
+      expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
     });
-    const locationHeader = requestStateHeaders.get('Location') || '';
 
-    handleNetlifyCacheInDevInstance({
-      locationHeader,
-      requestStateHeaders,
-      publishableKey: mockPublishableKey,
+    it('should not add cache bust parameter for production instances', () => {
+      process.env.NETLIFY = 'true';
+
+      const headers = new Headers({ Location: 'https://example.netlify.app' });
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockProdPublishableKey });
+
+      const locationUrl = new URL(headers.get('Location') || '');
+      expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(false);
     });
 
-    expect(requestStateHeaders.get('Location')).toBe('https://example.netlify.app');
-  });
+    it('should not modify the Location header if it has the handshake param', () => {
+      process.env.NETLIFY = 'true';
 
-  it('should ignore the URL environment variable if it is not a string', () => {
-    // @ts-expect-error - Random object
-    process.env.URL = {};
-    process.env.NETLIFY = 'true';
+      const locationValue = 'https://example.netlify.app/redirect?__clerk_handshake=';
+      const headers = new Headers({ Location: locationValue });
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
 
-    const requestStateHeaders = new Headers({
-      Location: 'https://example.netlify.app',
+      expect(headers.get('Location')).toBe(locationValue);
     });
-    const locationHeader = requestStateHeaders.get('Location') || '';
 
-    handleNetlifyCacheInDevInstance({
-      locationHeader,
-      requestStateHeaders,
-      publishableKey: mockPublishableKey,
+    it('should not modify the Location header if not on Netlify', () => {
+      const headers = new Headers({ Location: 'https://example.com' });
+      handleNetlifyCacheHeaders({ headers, publishableKey: mockDevPublishableKey });
+
+      expect(headers.get('Location')).toBe('https://example.com');
     });
 
-    const locationUrl = new URL(requestStateHeaders.get('Location') || '');
-    expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
+    it('should ignore the URL environment variable if it is not a string', () => {
+      // @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 });
+
+      const locationUrl = new URL(headers.get('Location') || '');
+      expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
+    });
   });
 });
diff --git a/packages/shared/src/netlifyCacheHandler.ts b/packages/shared/src/netlifyCacheHandler.ts
@@ -29,37 +29,51 @@ function isNetlifyRuntime(): boolean {
 }
 
 /**
- * Prevents infinite redirects in Netlify's functions by adding a cache bust parameter
- * to the original redirect URL. This ensures that Netlify doesn't serve a cached response
- * during the handshake flow.
+ * Applies Netlify-specific cache headers to the request state.
  *
- * The issue happens only on Clerk development instances running on Netlify. This is
- * a workaround until we find a better solution.
- *
- * See https://answers.netlify.com/t/cache-handling-recommendation-for-authentication-handshake-redirects/143969/1.
+ * 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.
+ * 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 {
+  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');
+
+  // Add cache-bust param to redirect URL for dev instances to prevent cached redirects
+  const locationHeader = headers.get('Location');
+  if (locationHeader && isDevelopmentFromPublishableKey(publishableKey)) {
+    const hasHandshakeQueryParam = locationHeader.includes('__clerk_handshake');
+    if (!hasHandshakeQueryParam) {
+      const url = new URL(locationHeader);
+      url.searchParams.append(CLERK_NETLIFY_CACHE_BUST_PARAM, Date.now().toString());
+      headers.set('Location', url.toString());
+    }
+  }
+}
+
+/**
+ * @deprecated Use `handleNetlifyCacheHeaders` instead.
+ * @internal
+ */
 export function handleNetlifyCacheInDevInstance({
-  locationHeader,
+  locationHeader: _locationHeader,
   requestStateHeaders,
   publishableKey,
 }: {
   locationHeader: string;
   requestStateHeaders: Headers;
   publishableKey: string;
 }) {
-  const isOnNetlify = isNetlifyRuntime();
-  const isDevelopmentInstance = isDevelopmentFromPublishableKey(publishableKey);
-
-  if (isOnNetlify && isDevelopmentInstance) {
-    const hasHandshakeQueryParam = locationHeader.includes('__clerk_handshake');
-    // If location header is the original URL before the handshake flow, add cache bust param
-    // The param should be removed in clerk-js
-    if (!hasHandshakeQueryParam) {
-      const url = new URL(locationHeader);
-      url.searchParams.append(CLERK_NETLIFY_CACHE_BUST_PARAM, Date.now().toString());
-      requestStateHeaders.set('Location', url.toString());
-    }
-  }
+  handleNetlifyCacheHeaders({ headers: requestStateHeaders, publishableKey });
 }
diff --git a/packages/tanstack-react-start/src/server/clerkMiddleware.ts b/packages/tanstack-react-start/src/server/clerkMiddleware.ts
@@ -1,6 +1,6 @@
 import type { RequestState } from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest } from '@clerk/backend/internal';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { handleNetlifyCacheHeaders } from '@clerk/shared/netlifyCacheHandler';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 import type { AnyRequestMiddleware } from '@tanstack/react-start';
 import { createMiddleware } from '@tanstack/react-start';
@@ -48,13 +48,10 @@ export const clerkMiddleware = (
       acceptsToken: 'any',
     });
 
+    handleNetlifyCacheHeaders(requestState);
+
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
-      handleNetlifyCacheInDevInstance({
-        locationHeader,
-        requestStateHeaders: requestState.headers,
-        publishableKey: requestState.publishableKey,
-      });
       // Trigger a handshake redirect
       // eslint-disable-next-line @typescript-eslint/only-throw-error
       throw new Response(null, { status: 307, headers: requestState.headers });
