@workos-inc/authkit-nextjs 2.17.0 → 3.0.0

package/src/components/useAccessToken.spec.tsx

@@ -1,3 +1,4 @@
+import type { Mock } from 'vitest';
 import '@testing-library/jest-dom';
 import { act, render, waitFor } from '@testing-library/react';
 import React from 'react';
@@ -89,7 +90,7 @@ describe('useAccessToken', () => {
       'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2lkIjoic2Vzc2lvbl8xMjMiLCJleHAiOjk5OTk5OTk5OTl9.mock-signature';
 
     (getAccessTokenAction as Mock).mockResolvedValueOnce(expiringToken);
-    (refreshAccessTokenAction as Mock).mockResolvedValueOnce(refreshedToken);
+    (refreshAccessTokenAction as Mock).mockResolvedValueOnce({ accessToken: refreshedToken });
 
     const { getByTestId } = render(<TestComponent />);
 
@@ -112,7 +113,7 @@ describe('useAccessToken', () => {
       'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNoZWQiLCJzaWQiOiJzZXNzaW9uXzEyMyIsImV4cCI6OTk5OTk5OTk5OX0.mock-signature-2';
 
     (getAccessTokenAction as Mock).mockResolvedValueOnce(initialToken);
-    (refreshAccessTokenAction as Mock).mockResolvedValueOnce(refreshedToken);
+    (refreshAccessTokenAction as Mock).mockResolvedValueOnce({ accessToken: refreshedToken });
 
     const { getByTestId } = render(<TestComponent />);
 
@@ -170,10 +171,12 @@ describe('useAccessToken', () => {
   it('should handle errors during manual refresh', async () => {
     const initialToken =
       'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2lkIjoic2Vzc2lvbl8xMjMiLCJleHAiOjk5OTk5OTk5OTl9.mock-signature';
-    const error = new Error('Failed to refresh token');
 
     (getAccessTokenAction as Mock).mockResolvedValueOnce(initialToken);
-    (refreshAccessTokenAction as Mock).mockRejectedValueOnce(error);
+    (refreshAccessTokenAction as Mock).mockResolvedValueOnce({
+      accessToken: undefined,
+      error: 'Failed to refresh token',
+    });
 
     const { getByTestId } = render(<TestComponent />);
 
@@ -277,10 +280,12 @@ describe('useAccessToken', () => {
       iat: currentTimeInSeconds - 35,
     };
     const expiringToken = `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.${btoa(JSON.stringify(payload))}.mock-signature`;
-    const error = new Error('Failed to refresh token');
 
     (getAccessTokenAction as Mock).mockResolvedValueOnce(expiringToken);
-    (refreshAccessTokenAction as Mock).mockRejectedValueOnce(error);
+    (refreshAccessTokenAction as Mock).mockResolvedValueOnce({
+      accessToken: undefined,
+      error: 'Failed to refresh token',
+    });
 
     const { getByTestId } = render(<TestComponent />);
 
@@ -410,7 +415,7 @@ describe('useAccessToken', () => {
 
     (refreshAccessTokenAction as Mock).mockImplementation(() => {
       refreshCalls++;
-      return refreshPromise;
+      return refreshPromise.then((t) => ({ accessToken: t }));
     });
 
     (getAccessTokenAction as Mock).mockImplementation(() => {
@@ -507,7 +512,7 @@ describe('useAccessToken', () => {
       resolveRefreshPromise = resolve;
     });
 
-    (refreshAccessTokenAction as Mock).mockReturnValue(refreshPromise);
+    (refreshAccessTokenAction as Mock).mockReturnValue(refreshPromise.then((t) => ({ accessToken: t })));
     (getAccessTokenAction as Mock).mockResolvedValue(initialToken);
 
     const { getByTestId } = render(<TestComponent />);
@@ -582,10 +587,8 @@ describe('useAccessToken', () => {
     const stringError = 'String error directly'; // Not wrapped in Error object
 
     (getAccessTokenAction as Mock).mockResolvedValueOnce(initialToken);
-    // Mock refreshAccessTokenAction to reject with a string, not an Error object
-    (refreshAccessTokenAction as Mock).mockImplementation(() => {
-      return Promise.reject(stringError); // Directly reject with string
-    });
+    // Mock refreshAccessTokenAction to return an error result (as server actions do)
+    (refreshAccessTokenAction as Mock).mockResolvedValueOnce({ accessToken: undefined, error: stringError });
 
     const { getByTestId } = render(<TestComponent />);
 

package/src/components/useTokenClaims.spec.tsx

@@ -1,3 +1,4 @@
+import type { Mock } from 'vitest';
 import '@testing-library/jest-dom';
 import { render, waitFor } from '@testing-library/react';
 import React from 'react';

package/src/cookie.ts

@@ -92,6 +92,35 @@ export function getCookieOptions(
   };
 }
 
+/**
+ * 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.
+ */
+export function getPKCECookieOptions(): CookieOptions;
+export function getPKCECookieOptions(redirectUri: string | null | undefined, asString: true, expired?: boolean): string;
+export function getPKCECookieOptions(
+  redirectUri?: string | null,
+  asString?: boolean,
+  expired?: boolean,
+): CookieOptions | string;
+export function getPKCECookieOptions(
+  redirectUri?: string | null,
+  asString: boolean = false,
+  expired: boolean = false,
+): CookieOptions | string {
+  if (asString) {
+    const options = getCookieOptions(redirectUri, true, expired);
+    return options.replace(/SameSite=Strict/i, 'SameSite=Lax');
+  }
+
+  const options = getCookieOptions(redirectUri);
+  return {
+    ...options,
+    sameSite: options.sameSite.toLowerCase() === 'strict' ? 'lax' : options.sameSite,
+  };
+}
+
 export function getJwtCookie(body: string | null, requestUrlOrRedirectUri?: string | null, expired?: boolean): string {
   const cookie = `${JWT_COOKIE_NAME}=${expired ? '' : (body ?? '')}`;
 

package/src/env-variables.ts

@@ -13,7 +13,6 @@ const WORKOS_COOKIE_MAX_AGE = getEnvVariable('WORKOS_COOKIE_MAX_AGE');
 const WORKOS_COOKIE_NAME = getEnvVariable('WORKOS_COOKIE_NAME');
 const WORKOS_COOKIE_SAMESITE = getEnvVariable('WORKOS_COOKIE_SAMESITE') as 'lax' | 'strict' | 'none' | undefined;
 const WORKOS_CLAIM_TOKEN = getEnvVariable('WORKOS_CLAIM_TOKEN');
-const WORKOS_ENABLE_PKCE = getEnvVariable('WORKOS_ENABLE_PKCE');
 
 // Required env variables
 const WORKOS_API_KEY = getEnvVariable('WORKOS_API_KEY') ?? '';
@@ -34,5 +33,4 @@ export {
   WORKOS_COOKIE_PASSWORD,
   WORKOS_REDIRECT_URI,
   WORKOS_COOKIE_SAMESITE,
-  WORKOS_ENABLE_PKCE,
 };

package/src/get-authorization-url.spec.ts

@@ -1,6 +1,7 @@
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import { headers } from 'next/headers';
 import { getWorkOS } from './workos.js';
+import { getStateFromPKCECookieValue } from './pkce.js';
 
 // Mock dependencies
 const { fakeWorkosInstance } = vi.hoisted(() => ({
@@ -27,7 +28,6 @@ describe('getAuthorizationUrl', () => {
   const workos = getWorkOS();
   beforeEach(() => {
     vi.clearAllMocks();
-    delete process.env.WORKOS_ENABLE_PKCE;
     fakeWorkosInstance.pkce.generate.mockResolvedValue({
       codeVerifier: 'test-code-verifier',
       codeChallenge: 'test-code-challenge',
@@ -39,7 +39,6 @@ describe('getAuthorizationUrl', () => {
     const nextHeaders = await headers();
     nextHeaders.set('x-redirect-uri', 'http://test-redirect.com');
 
-    // Mock workos.userManagement.getAuthorizationUrl
     vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
     await getAuthorizationUrl({});
@@ -54,7 +53,7 @@ describe('getAuthorizationUrl', () => {
   it('works when called with no arguments', async () => {
     vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
-    await getAuthorizationUrl(); // Call with no arguments
+    await getAuthorizationUrl();
 
     expect(workos.userManagement.getAuthorizationUrl).toHaveBeenCalled();
   });
@@ -160,9 +159,8 @@ describe('getAuthorizationUrl', () => {
       warnSpy.mockRestore();
     });
 
-    it('works with PKCE disabled', async () => {
+    it('includes PKCE and claim nonce together', async () => {
       process.env.WORKOS_CLAIM_TOKEN = 'test-claim-token';
-      process.env.WORKOS_DISABLE_PKCE = 'true';
       const fetchSpy = vi
         .spyOn(globalThis, 'fetch')
         .mockResolvedValueOnce(new Response(JSON.stringify({ nonce: 'test-nonce' }), { status: 201 }));
@@ -174,39 +172,23 @@ describe('getAuthorizationUrl', () => {
       const result = await freshGetAuthorizationUrl({});
 
       expect(workos.userManagement.getAuthorizationUrl).toHaveBeenCalledWith(
-        expect.objectContaining({ claimNonce: 'test-nonce' }),
+        expect.objectContaining({
+          claimNonce: 'test-nonce',
+          codeChallenge: 'test-code-challenge',
+          codeChallengeMethod: 'S256',
+        }),
       );
-      expect(result.pkceCookieValue).toBeUndefined();
+      expect(result.sealedState).toBeDefined();
       fetchSpy.mockRestore();
     });
   });
 
   describe('PKCE', () => {
-    it('skips PKCE by default', async () => {
+    it('always generates PKCE pair and includes code challenge', async () => {
       vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
       const result = await getAuthorizationUrl({});
 
-      expect(fakeWorkosInstance.pkce.generate).not.toHaveBeenCalled();
-      expect(workos.userManagement.getAuthorizationUrl).toHaveBeenCalledWith(
-        expect.not.objectContaining({
-          codeChallenge: expect.any(String),
-        }),
-      );
-      expect(result.pkceCookieValue).toBeUndefined();
-    });
-
-    it('generates PKCE pair when WORKOS_ENABLE_PKCE is set to true', async () => {
-      process.env.WORKOS_ENABLE_PKCE = 'true';
-
-      // Re-import to pick up the new env var
-      vi.resetModules();
-      const { getAuthorizationUrl: freshGetAuthorizationUrl } = await import('./get-authorization-url.js');
-
-      vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
-
-      const result = await freshGetAuthorizationUrl({});
-
       expect(fakeWorkosInstance.pkce.generate).toHaveBeenCalled();
       expect(workos.userManagement.getAuthorizationUrl).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -215,23 +197,19 @@ describe('getAuthorizationUrl', () => {
         }),
       );
       expect(result.url).toBe('mock-url');
-      expect(result.pkceCookieValue).toBeDefined();
-      expect(result.pkceCookieValue).not.toBe('');
+      expect(result.sealedState).toBeDefined();
+      expect(result.sealedState).not.toBe('');
     });
 
-    it('returns sealed cookie value for the verifier when PKCE is enabled', async () => {
-      process.env.WORKOS_ENABLE_PKCE = 'true';
-
-      vi.resetModules();
-      const { getAuthorizationUrl: freshGetAuthorizationUrl } = await import('./get-authorization-url.js');
-
+    it('seals codeVerifier and nonce into state', async () => {
       vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
-      const result = await freshGetAuthorizationUrl({});
+      const result = await getAuthorizationUrl({});
 
-      // pkceCookieValue should be a sealed (encrypted) string
-      expect(typeof result.pkceCookieValue).toBe('string');
-      expect(result.pkceCookieValue!.length).toBeGreaterThan(0);
+      const { codeVerifier, nonce } = await getStateFromPKCECookieValue(result.sealedState);
+      expect(codeVerifier).toBe('test-code-verifier');
+      expect(nonce).toBeDefined();
+      expect(typeof nonce).toBe('string');
     });
   });
 });

package/src/get-authorization-url.ts

@@ -1,13 +1,7 @@
 import { sealData } from 'iron-session';
 import { headers } from 'next/headers';
-import {
-  WORKOS_CLAIM_TOKEN,
-  WORKOS_CLIENT_ID,
-  WORKOS_COOKIE_PASSWORD,
-  WORKOS_ENABLE_PKCE,
-  WORKOS_REDIRECT_URI,
-} from './env-variables.js';
-import { GetAuthURLOptions, GetAuthURLResult } from './interfaces.js';
+import { WORKOS_CLAIM_TOKEN, WORKOS_CLIENT_ID, WORKOS_COOKIE_PASSWORD, WORKOS_REDIRECT_URI } from './env-variables.js';
+import { GetAuthURLOptions, GetAuthURLResult, State } from './interfaces.js';
 import { getWorkOS } from './workos.js';
 
 async function fetchClaimNonce(baseURL: string): Promise<string | null> {
@@ -39,51 +33,51 @@ async function fetchClaimNonce(baseURL: string): Promise<string | null> {
   }
 }
 
-async function getAuthorizationUrl(options: GetAuthURLOptions = {}): Promise<GetAuthURLResult> {
-  const { returnPathname, screenHint, organizationId, loginHint, prompt, state: customState } = options;
-  let redirectUri = options.redirectUri;
-  if (!redirectUri) {
-    const headersList = await headers();
-    redirectUri = headersList.get('x-redirect-uri') ?? undefined;
-  }
+async function getAuthorizationUrl({
+  returnPathname,
+  screenHint,
+  organizationId,
+  loginHint,
+  prompt,
+  state: customState,
+  redirectUri,
+}: GetAuthURLOptions = {}): Promise<GetAuthURLResult> {
+  const redirectUriToUse = await (async () => {
+    if (redirectUri) {
+      return redirectUri;
+    }
 
-  const internalState = returnPathname
-    ? btoa(JSON.stringify({ returnPathname })).replace(/\+/g, '-').replace(/\//g, '_')
-    : null;
+    const headersList = await headers();
+    return headersList.get('x-redirect-uri') ?? undefined;
+  })();
 
+  const pkce = await getWorkOS().pkce.generate();
   const claimNonce = WORKOS_CLAIM_TOKEN ? await fetchClaimNonce(getWorkOS().baseURL) : null;
 
-  const finalState =
-    internalState && customState ? `${internalState}.${customState}` : internalState || customState || undefined;
+  const state = {
+    nonce: crypto.randomUUID(),
+    codeVerifier: pkce.codeVerifier,
+    customState,
+    returnPathname,
+  } satisfies State;
+
+  const sealedState = await sealData(state, { password: WORKOS_COOKIE_PASSWORD, ttl: 600 });
 
-  const baseOptions = {
+  const url = getWorkOS().userManagement.getAuthorizationUrl({
     provider: 'authkit' as const,
     clientId: WORKOS_CLIENT_ID,
-    redirectUri: redirectUri ?? WORKOS_REDIRECT_URI,
-    state: finalState,
+    redirectUri: redirectUriToUse ?? WORKOS_REDIRECT_URI,
     screenHint,
     organizationId,
     loginHint,
     prompt,
+    state: sealedState,
+    codeChallenge: pkce.codeChallenge,
+    codeChallengeMethod: pkce.codeChallengeMethod,
     ...(claimNonce && { claimNonce }),
-  };
-
-  if (WORKOS_ENABLE_PKCE === 'true') {
-    const pkce = await getWorkOS().pkce.generate();
-    const pkceCookieValue = await sealData(
-      { codeVerifier: pkce.codeVerifier },
-      { password: WORKOS_COOKIE_PASSWORD, ttl: 600 },
-    );
-    const url = getWorkOS().userManagement.getAuthorizationUrl({
-      ...baseOptions,
-      codeChallenge: pkce.codeChallenge,
-      codeChallengeMethod: pkce.codeChallengeMethod,
-    });
-
-    return { url, pkceCookieValue };
-  }
+  });
 
-  return { url: getWorkOS().userManagement.getAuthorizationUrl(baseOptions), pkceCookieValue: undefined };
+  return { url, sealedState };
 }
 
 export { getAuthorizationUrl };

package/src/index.ts

@@ -1,10 +1,11 @@
 import { getSignInUrl, getSignUpUrl, signOut, switchToOrganization } from './auth.js';
 import { handleAuth } from './authkit-callback-route.js';
 import { AuthKitError, TokenRefreshError } from './errors.js';
-import { authkit, authkitMiddleware } from './middleware.js';
+import { authkit, authkitMiddleware, authkitProxy } from './middleware.js';
 export {
   applyResponseHeaders,
   handleAuthkitHeaders,
+  handleAuthkitProxy,
   partitionAuthkitHeaders,
   isAuthkitRequestHeader,
   AUTHKIT_REQUEST_HEADERS,
@@ -24,6 +25,7 @@ export {
   TokenRefreshError,
   authkit,
   authkitMiddleware,
+  authkitProxy,
   getSignInUrl,
   getSignUpUrl,
   getTokenClaims,

package/src/interfaces.ts

@@ -1,5 +1,6 @@
 import type { AuthenticationResponse, OauthTokens, User } from '@workos-inc/node';
 import { type NextRequest } from 'next/server';
+import * as v from 'valibot';
 
 export interface HandleAuthOptions {
   returnPathname?: string;
@@ -61,9 +62,18 @@ export interface AccessToken {
   feature_flags?: string[];
 }
 
+export const StateSchema = v.object({
+  nonce: v.string(),
+  customState: v.optional(v.string()),
+  returnPathname: v.optional(v.string()),
+  codeVerifier: v.string(),
+});
+
+export type State = v.InferOutput<typeof StateSchema>;
+
 export interface GetAuthURLResult {
   url: string;
-  pkceCookieValue?: string;
+  sealedState: string;
 }
 
 export interface GetAuthURLOptions {

package/src/jwt.ts

@@ -2,16 +2,16 @@
  * JWT (JSON Web Token) Interface Definitions
  */
 export interface JWTHeader {
-  'alg': string;
-  'typ'?: string | undefined;
-  'cty'?: string | undefined;
-  'crit'?: Array<string | Exclude<keyof JWTHeader, 'crit'>> | undefined;
-  'kid'?: string | undefined;
-  'jku'?: string | undefined;
-  'x5u'?: string | string[] | undefined;
+  alg: string;
+  typ?: string | undefined;
+  cty?: string | undefined;
+  crit?: Array<string | Exclude<keyof JWTHeader, 'crit'>> | undefined;
+  kid?: string | undefined;
+  jku?: string | undefined;
+  x5u?: string | string[] | undefined;
   'x5t#S256'?: string | undefined;
-  'x5t'?: string | undefined;
-  'x5c'?: string | string[] | undefined;
+  x5t?: string | undefined;
+  x5c?: string | string[] | undefined;
 }
 /**
  * JWT Payload Interface

package/src/middleware-helpers.spec.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import {
   handleAuthkitHeaders,
+  handleAuthkitProxy,
   partitionAuthkitHeaders,
   applyResponseHeaders,
   isAuthkitRequestHeader,
@@ -228,4 +229,10 @@ describe('middleware-helpers', () => {
       expect(response.headers.getSetCookie()).toHaveLength(2);
     });
   });
+
+  describe('handleAuthkitHeaders (deprecated alias)', () => {
+    it('should be the same function reference as handleAuthkitProxy', () => {
+      expect(handleAuthkitHeaders).toBe(handleAuthkitProxy);
+    });
+  });
 });

package/src/middleware-helpers.ts

@@ -56,8 +56,9 @@ export function partitionAuthkitHeaders(request: NextRequest, authkitHeaders: He
   const headers = new Headers(authkitHeaders);
   const requestHeaders = new Headers(request.headers);
 
-  // Strip any client-injected authkit headers, then apply trusted ones
-  for (const name of [...requestHeaders.keys()]) {
+  // Snapshot keys before iterating, since we delete headers during the loop
+  const requestHeaderKeys = Array.from(requestHeaders.keys());
+  for (const name of requestHeaderKeys) {
     if (isAuthkitRequestHeader(name)) {
       requestHeaders.delete(name);
     }
@@ -106,7 +107,7 @@ export interface HandleAuthkitHeadersOptions {
 /**
  * Creates a NextResponse with properly merged AuthKit headers.
  */
-export function handleAuthkitHeaders(
+export function handleAuthkitProxy(
   request: NextRequest,
   authkitHeaders: Headers,
   options: HandleAuthkitHeadersOptions = {},
@@ -128,3 +129,6 @@ export function handleAuthkitHeaders(
 
   return applyResponseHeaders(NextResponse.next({ request: { headers: requestHeaders } }), responseHeaders);
 }
+
+/** @deprecated Use `handleAuthkitProxy` instead. */
+export const handleAuthkitHeaders: typeof handleAuthkitProxy = handleAuthkitProxy;

package/src/middleware.spec.ts

@@ -0,0 +1,25 @@
+import { authkitMiddleware, authkitProxy } from './middleware.js';
+
+describe('middleware', () => {
+  describe('authkitProxy', () => {
+    it('should return a middleware function when called with no options', () => {
+      const middleware = authkitProxy();
+      expect(typeof middleware).toBe('function');
+    });
+
+    it('should accept the same options as authkitMiddleware', () => {
+      const middleware = authkitProxy({
+        debug: true,
+        middlewareAuth: { enabled: true, unauthenticatedPaths: ['/public'] },
+        signUpPaths: ['/sign-up'],
+      });
+      expect(typeof middleware).toBe('function');
+    });
+  });
+
+  describe('authkitMiddleware (deprecated alias)', () => {
+    it('should be the same function reference as authkitProxy', () => {
+      expect(authkitMiddleware).toBe(authkitProxy);
+    });
+  });
+});

package/src/middleware.ts

@@ -3,7 +3,7 @@ import { updateSessionMiddleware, updateSession } from './session.js';
 import { AuthkitMiddlewareOptions, AuthkitOptions, AuthkitResponse } from './interfaces.js';
 import { WORKOS_REDIRECT_URI } from './env-variables.js';
 
-export function authkitMiddleware({
+export function authkitProxy({
   debug = false,
   middlewareAuth = { enabled: false, unauthenticatedPaths: [] },
   redirectUri = WORKOS_REDIRECT_URI,
@@ -15,6 +15,9 @@ export function authkitMiddleware({
   };
 }
 
+/** @deprecated Use `authkitProxy` instead. */
+export const authkitMiddleware: typeof authkitProxy = authkitProxy;
+
 export async function authkit(request: NextRequest, options: AuthkitOptions = {}): Promise<AuthkitResponse> {
   return await updateSession(request, options);
 }

package/src/pkce.spec.ts

@@ -0,0 +1,125 @@
+import { sealData } from 'iron-session';
+import { getStateFromPKCECookieValue } from './pkce.js';
+
+const PASSWORD = process.env.WORKOS_COOKIE_PASSWORD!;
+
+describe('setPKCECookie SameSite override', () => {
+  const mockSet = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    vi.doMock('next/headers', () => ({
+      cookies: async () => ({ set: mockSet, get: vi.fn(), getAll: vi.fn(), delete: vi.fn() }),
+      headers: async () => ({ get: vi.fn(), set: vi.fn(), delete: vi.fn() }),
+    }));
+    vi.doMock('./env-variables', async (importOriginal) => {
+      return { ...(await importOriginal<typeof import('./env-variables')>()) };
+    });
+  });
+
+  it('should downgrade strict to lax', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'strict' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      'wos-auth-verifier',
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+
+  it('should preserve none for iframe/cross-origin flows', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'none' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      'wos-auth-verifier',
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'none' }),
+    );
+  });
+
+  it('should downgrade mixed-case Strict to lax', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'Strict' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      'wos-auth-verifier',
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+
+  it('should default to lax when no SameSite configured', async () => {
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      'wos-auth-verifier',
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+});
+
+describe('getStateFromPKCECookieValue', () => {
+  it('should unseal and validate a valid state', async () => {
+    const sealed = await sealData(
+      { nonce: 'test-nonce', codeVerifier: 'verifier-abc', returnPathname: '/dashboard', customState: 'custom' },
+      { password: PASSWORD },
+    );
+
+    const state = await getStateFromPKCECookieValue(sealed);
+
+    expect(state.nonce).toBe('test-nonce');
+    expect(state.returnPathname).toBe('/dashboard');
+    expect(state.customState).toBe('custom');
+  });
+
+  it('should unseal state with codeVerifier', async () => {
+    const sealed = await sealData({ nonce: 'test-nonce', codeVerifier: 'verifier-123' }, { password: PASSWORD });
+
+    const state = await getStateFromPKCECookieValue(sealed);
+
+    expect(state.nonce).toBe('test-nonce');
+    expect(state.codeVerifier).toBe('verifier-123');
+  });
+
+  it('should throw when codeVerifier is missing', async () => {
+    const sealed = await sealData({ nonce: 'test-nonce', returnPathname: '/dashboard' }, { password: PASSWORD });
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+
+  it('should throw when nonce is missing', async () => {
+    const sealed = await sealData(
+      { codeVerifier: 'verifier-abc', returnPathname: '/dashboard' },
+      { password: PASSWORD },
+    );
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+
+  it('should throw when sealed data is corrupted', async () => {
+    await expect(getStateFromPKCECookieValue('not-a-valid-sealed-value')).rejects.toThrow();
+  });
+
+  it('should throw when sealed with a different password', async () => {
+    const sealed = await sealData(
+      { nonce: 'test-nonce', codeVerifier: 'verifier-abc' },
+      { password: 'a-different-password-that-is-32-chars!' },
+    );
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+});