fix: isolate concurrent PKCE flows to prevent cookie clobbering (#403)

Co-authored-by: Nick Nisi <nick.nisi@workos.com>

Author: cn-stephen

package.json

@@ -37,6 +37,7 @@
     "typecheck": "tsc --project tsconfig.app.json --noEmit && tsc --project tsconfig.test.json --noEmit"
   },
   "dependencies": {
+    "@sindresorhus/fnv1a": "^3.1.0",
     "@workos-inc/node": "^8.9.0",
     "iron-session": "^8.0.4",
     "jose": "^5.10.0",

pnpm-lock.yaml

@@ -274,6 +274,25 @@ describe('auth.ts', () => {
       expect(sessionCookie).toBeUndefined();
     });
 
+    it('should clear lingering PKCE verifier cookies (legacy and per-flow)', async () => {
+      const nextCookies = await cookies();
+      const nextHeaders = await headers();
+
+      nextHeaders.set('x-workos-middleware', 'true');
+      nextCookies.set('wos-session', 'foo');
+      nextCookies.set('wos-auth-verifier', 'legacy-state');
+      nextCookies.set('wos-auth-verifier-a1b2c3d4', 'flow-a-state');
+      nextCookies.set('wos-auth-verifier-deadbeef', 'flow-b-state');
+      nextCookies.set('unrelated-cookie', 'keep-me');
+
+      await signOut();
+
+      expect(nextCookies.get('wos-auth-verifier')).toBeUndefined();
+      expect(nextCookies.get('wos-auth-verifier-a1b2c3d4')).toBeUndefined();
+      expect(nextCookies.get('wos-auth-verifier-deadbeef')).toBeUndefined();
+      expect(nextCookies.get('unrelated-cookie')?.value).toBe('keep-me');
+    });
+
     describe('when given a `returnTo` parameter', () => {
       it('passes the `returnTo` through to the `getLogoutUrl` call', async () => {
         vi.spyOn(workos.userManagement, 'getLogoutUrl').mockReturnValue(

src/auth.spec.ts

@@ -5,10 +5,10 @@ import { revalidatePath, revalidateTag } from 'next/cache';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { WORKOS_COOKIE_NAME } from './env-variables.js';
-import { getCookieOptions } from './cookie.js';
+import { getCookieOptions, getPKCECookieOptions } from './cookie.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import type { AccessToken, GetAuthURLOptions, SwitchToOrganizationOptions, UserInfo } from './interfaces.js';
-import { setPKCECookie } from './pkce.js';
+import { PKCE_COOKIE_NAME, setPKCECookie } from './pkce.js';
 import { getSessionFromCookie, refreshSession, withAuth } from './session.js';
 import { getWorkOS } from './workos.js';
 
@@ -80,6 +80,24 @@ export async function signOut({ returnTo }: { returnTo?: string } = {}) {
       nextCookies.delete(cookieName);
     }
 
+    // Clear any lingering PKCE verifier cookies so orphans from abandoned
+    // flows don't accumulate toward HTTP 431 or confuse future sign-ins.
+    const pkceOptions = getPKCECookieOptions();
+    for (const { name } of nextCookies.getAll()) {
+      if (!name.startsWith(PKCE_COOKIE_NAME)) continue;
+      try {
+        nextCookies.delete({
+          name,
+          domain: pkceOptions.domain,
+          path: pkceOptions.path,
+          sameSite: pkceOptions.sameSite,
+          secure: pkceOptions.secure,
+        });
+      } catch {
+        nextCookies.delete(name);
+      }
+    }
+
     if (sessionId) {
       redirect(getWorkOS().userManagement.getLogoutUrl({ sessionId, returnTo }));
     } else {

src/auth.ts

@@ -1,6 +1,7 @@
 import type { Mock } from 'vitest';
 import { getWorkOS } from './workos.js';
 import { handleAuth } from './authkit-callback-route.js';
+import { getPKCECookieNameForState } from './pkce.js';
 import { getSessionFromCookie, saveSession } from './session.js';
 import { NextRequest, NextResponse } from 'next/server';
 import { sealData } from 'iron-session';
@@ -56,7 +57,7 @@ describe('authkit-callback-route', () => {
 
   async function setAuthCookie(req: NextRequest, state: State): Promise<string> {
     const sealedState = await sealData(state, { password: process.env.WORKOS_COOKIE_PASSWORD! });
-    req.cookies.set('wos-auth-verifier', sealedState);
+    req.cookies.set(getPKCECookieNameForState(sealedState), sealedState);
     return sealedState;
   }
 
@@ -548,10 +549,11 @@ describe('authkit-callback-route', () => {
       it('should return an error response when PKCE cookie is corrupted', async () => {
         vi.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
 
-        // Set a corrupted cookie
-        request.cookies.set('wos-auth-verifier', 'not-a-valid-sealed-value');
+        // Set a corrupted cookie using the flow-specific name
+        const corruptedState = 'not-a-valid-sealed-value';
+        request.cookies.set(getPKCECookieNameForState(corruptedState), corruptedState);
         request.nextUrl.searchParams.set('code', 'test-code');
-        request.nextUrl.searchParams.set('state', 'not-a-valid-sealed-value');
+        request.nextUrl.searchParams.set('state', corruptedState);
 
         const handler = handleAuth();
         const response = await handler(request);
@@ -570,11 +572,12 @@ describe('authkit-callback-route', () => {
         const handler = handleAuth();
         const response = await handler(request);
 
-        // The response should be a redirect (success) and have a Set-Cookie header to delete the PKCE cookie
+        // The response should be a redirect (success) and have a Set-Cookie header to delete the flow-specific PKCE cookie
         expect(response.status).toBe(307);
 
+        const flowCookieName = getPKCECookieNameForState(sealedState);
         const setCookieHeaders = response.headers.getSetCookie();
-        const pkceDeletionCookie = setCookieHeaders.find((c: string) => c.startsWith('wos-auth-verifier='));
+        const pkceDeletionCookie = setCookieHeaders.find((c: string) => c.startsWith(`${flowCookieName}=`));
         expect(pkceDeletionCookie).toBeDefined();
         expect(pkceDeletionCookie).toContain('Max-Age=0');
       });
@@ -590,11 +593,70 @@ describe('authkit-callback-route', () => {
         const response = await handler(request);
 
         expect(response.status).toBe(500);
+        const flowCookieName = getPKCECookieNameForState(sealedState);
         const setCookieHeaders = response.headers.getSetCookie();
-        const pkceDeletionCookie = setCookieHeaders.find((c: string) => c.startsWith('wos-auth-verifier='));
+        const pkceDeletionCookie = setCookieHeaders.find((c: string) => c.startsWith(`${flowCookieName}=`));
         expect(pkceDeletionCookie).toBeDefined();
         expect(pkceDeletionCookie).toContain('Max-Age=0');
       });
+
+      it('should isolate concurrent auth flows using per-flow cookie names', async () => {
+        vi.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+        // Simulate two concurrent auth flows with different sealed states
+        const sealedStateA = await sealData(
+          { nonce: 'nonce-a', codeVerifier: 'verifier-a' },
+          { password: process.env.WORKOS_COOKIE_PASSWORD! },
+        );
+        const sealedStateB = await sealData(
+          { nonce: 'nonce-b', codeVerifier: 'verifier-b' },
+          { password: process.env.WORKOS_COOKIE_PASSWORD! },
+        );
+
+        // Both cookies exist on the request (set by different middleware redirects)
+        request.cookies.set(getPKCECookieNameForState(sealedStateA), sealedStateA);
+        request.cookies.set(getPKCECookieNameForState(sealedStateB), sealedStateB);
+
+        // Callback for flow A — should find its own cookie
+        request.nextUrl.searchParams.set('code', 'code-a');
+        request.nextUrl.searchParams.set('state', sealedStateA);
+
+        const handler = handleAuth();
+        const response = await handler(request);
+
+        expect(response.status).toBe(307);
+        expect(workos.userManagement.authenticateWithCode).toHaveBeenCalledWith(
+          expect.objectContaining({ codeVerifier: 'verifier-a' }),
+        );
+
+        // Flow B's cookie should NOT have been deleted
+        const setCookieHeaders = response.headers.getSetCookie();
+        const flowBCookieName = getPKCECookieNameForState(sealedStateB);
+        const flowBDeletion = setCookieHeaders.find((c: string) => c.startsWith(`${flowBCookieName}=`));
+        expect(flowBDeletion).toBeUndefined();
+      });
+
+      it('should fall back to the legacy shared PKCE cookie for v3.0.x in-flight flows', async () => {
+        vi.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+        const sealedState = await sealData(
+          { nonce: 'legacy', codeVerifier: 'legacy-verifier' },
+          { password: process.env.WORKOS_COOKIE_PASSWORD! },
+        );
+
+        // Simulate a user mid-OAuth on v3.0.x: only the legacy cookie name exists
+        request.cookies.set('wos-auth-verifier', sealedState);
+        request.nextUrl.searchParams.set('code', 'test-code');
+        request.nextUrl.searchParams.set('state', sealedState);
+
+        const handler = handleAuth();
+        const response = await handler(request);
+
+        expect(response.status).toBe(307);
+        expect(workos.userManagement.authenticateWithCode).toHaveBeenCalledWith(
+          expect.objectContaining({ codeVerifier: 'legacy-verifier' }),
+        );
+      });
     });
   });
 });

src/authkit-callback-route.spec.ts

@@ -2,7 +2,7 @@ import { NextRequest } from 'next/server';
 import { getPKCECookieOptions } from './cookie.js';
 import { WORKOS_CLIENT_ID } from './env-variables.js';
 import { HandleAuthOptions } from './interfaces.js';
-import { PKCE_COOKIE_NAME, getStateFromPKCECookieValue } from './pkce.js';
+import { PKCE_COOKIE_NAME, getPKCECookieNameForState, getStateFromPKCECookieValue } from './pkce.js';
 import { saveSession } from './session.js';
 import { errorResponseWithFallback, redirectWithFallback, setCachePreventionHeaders } from './utils.js';
 import { getWorkOS } from './workos.js';
@@ -25,26 +25,29 @@ export function handleAuth(options: HandleAuthOptions = {}) {
   }
 
   return async function GET(request: NextRequest) {
-    // Always delete the PKCE cookie after handling the callback, regardless of success or error
-    // to avoid stale cookies affecting future auth attempts & prevent replays
-    const deleteCookie = `${PKCE_COOKIE_NAME}=; ${getPKCECookieOptions(request.url, true, true)}`;
+    // Fall back to standard URL parsing when nextUrl is not available (e.g., vinext)
+    const requestUrl = request.nextUrl ?? new URL(request.url);
 
-    // We want to catch any & all errors and respond the same way
-    // Firstly, by destroying the 1-use PKCE cookie to prevent replay attacks
-    // or stale cookies affecting future auth attempts
-    try {
-      // Fall back to standard URL parsing when nextUrl is not available (e.g., vinext)
-      const requestUrl = request.nextUrl ?? new URL(request.url);
-
-      // Gather mandatory information
-      const code = requestUrl.searchParams.get('code');
-      const state = requestUrl.searchParams.get('state');
-      const pkceCookie = request.cookies.get(PKCE_COOKIE_NAME)?.value;
+    // Gather mandatory information
+    const code = requestUrl.searchParams.get('code');
+    const state = requestUrl.searchParams.get('state');
 
+    // We want to catch any & all errors and respond the same way, always
+    // destroying the 1-use PKCE cookie to prevent replay attacks or stale
+    // cookies affecting future auth attempts.
+    try {
       if (!code || !state) {
         throw new Error('Missing required auth parameter');
       }
 
+      // Derive the flow-specific cookie name from the state param so each
+      // concurrent auth flow reads/deletes its own cookie, not a shared one.
+      // Fall back to the legacy shared cookie name so in-flight OAuth flows
+      // started on v3.0.x don't fail on the first callback after upgrade.
+      // Safe to remove once v3.0.x is unsupported.
+      const pkceCookieName = getPKCECookieNameForState(state);
+      const pkceCookie = request.cookies.get(pkceCookieName)?.value ?? request.cookies.get(PKCE_COOKIE_NAME)?.value;
+
       // CSRF verification: both channels (cookie + URL state) must be present and match
       if (!pkceCookie) {
         throw new Error(
@@ -95,7 +98,10 @@ export function handleAuth(options: HandleAuthOptions = {}) {
       // This is to support Next.js 13.
       const response = redirectWithFallback(url.toString());
       preventCaching(response.headers);
-      response.headers.append('Set-Cookie', deleteCookie);
+
+      // Always delete the PKCE cookie after handling the callback, regardless of success or error
+      // to avoid stale cookies affecting future auth attempts & prevent replays
+      response.headers.append('Set-Cookie', `${pkceCookieName}=; ${getPKCECookieOptions(request.url, true, true)}`);
 
       await saveSession({ accessToken, refreshToken, user, impersonator }, request);
 
@@ -116,7 +122,16 @@ export function handleAuth(options: HandleAuthOptions = {}) {
     } catch (error) {
       console.error('[AuthKit callback error]', error);
       const response = await errorResponse(request, error);
-      response.headers.append('Set-Cookie', deleteCookie);
+
+      // Always delete the PKCE cookie after handling the callback, regardless of success or error
+      // to avoid stale cookies affecting future auth attempts & prevent replays
+      if (state) {
+        response.headers.append(
+          'Set-Cookie',
+          `${getPKCECookieNameForState(state)}=; ${getPKCECookieOptions(request.url, true, true)}`,
+        );
+      }
+
       return response;
     }
   };

src/authkit-callback-route.ts

@@ -278,4 +278,53 @@ describe('cookie.ts', () => {
       expect(ipCookie).not.toContain('Secure');
     });
   });
+
+  describe('getPKCECookieOptions', () => {
+    it('should use 10-minute max-age, not the session cookie max-age', async () => {
+      const { getPKCECookieOptions } = await import('./cookie');
+
+      const options = getPKCECookieOptions();
+
+      expect(options).toEqual(expect.objectContaining({ maxAge: 600 }));
+    });
+
+    it('should use 10-minute max-age in string format', async () => {
+      const { getPKCECookieOptions } = await import('./cookie');
+
+      const options = getPKCECookieOptions('http://localhost:3000', true);
+
+      expect(options).toContain('Max-Age=600');
+      expect(options).not.toContain('Max-Age=34560000');
+    });
+
+    it('should use max-age 0 when expired in object format', async () => {
+      const { getPKCECookieOptions } = await import('./cookie');
+
+      const options = getPKCECookieOptions(undefined, false, true);
+
+      expect(options).toEqual(expect.objectContaining({ maxAge: 0 }));
+    });
+
+    it('should use max-age 0 when expired in string format', async () => {
+      const { getPKCECookieOptions } = await import('./cookie');
+
+      const options = getPKCECookieOptions('http://localhost:3000', true, true);
+
+      expect(options).toContain('Max-Age=0');
+    });
+
+    it('should downgrade SameSite=Strict to Lax', async () => {
+      const envVars = await import('./env-variables');
+      Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'strict' });
+
+      const { getPKCECookieOptions } = await import('./cookie');
+
+      const objectOptions = getPKCECookieOptions();
+      expect(objectOptions).toEqual(expect.objectContaining({ sameSite: 'lax' }));
+
+      const stringOptions = getPKCECookieOptions('http://localhost:3000', true);
+      expect(stringOptions).toContain('SameSite=Lax');
+      expect(stringOptions).not.toContain('SameSite=Strict');
+    });
+  });
 });

src/cookie.spec.ts

@@ -92,10 +92,13 @@ export function getCookieOptions(
   };
 }
 
+const PKCE_COOKIE_MAX_AGE = 600; // 10 minutes
+
 /**
  * Cookie options for the PKCE verifier cookie.
  * 'strict' blocks the cookie on the cross-site redirect back from WorkOS; downgrade to 'lax'.
  * 'none' is more permissive and must be preserved for iframe/cross-origin embed flows.
+ * Max-age is always capped to 10 minutes — PKCE cookies are single-use and short-lived.
  */
 export function getPKCECookieOptions(): CookieOptions;
 export function getPKCECookieOptions(redirectUri: string | null | undefined, asString: true, expired?: boolean): string;
@@ -111,13 +114,16 @@ export function getPKCECookieOptions(
 ): CookieOptions | string {
   if (asString) {
     const options = getCookieOptions(redirectUri, true, expired);
-    return options.replace(/SameSite=Strict/i, 'SameSite=Lax');
+    return options
+      .replace(/SameSite=Strict/i, 'SameSite=Lax')
+      .replace(/Max-Age=\d+/, `Max-Age=${expired ? 0 : PKCE_COOKIE_MAX_AGE}`);
   }
 
   const options = getCookieOptions(redirectUri);
   return {
     ...options,
     sameSite: options.sameSite.toLowerCase() === 'strict' ? 'lax' : options.sameSite,
+    maxAge: expired ? 0 : PKCE_COOKIE_MAX_AGE,
   };
 }