@workos-inc/authkit-nextjs 3.0.0-beta.1 → 3.0.1

package/src/session.ts

@@ -4,9 +4,10 @@ import { sealData, unsealData } from 'iron-session';
 import { JWTPayload, createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
-import { NextRequest, NextResponse } from 'next/server';
-import { getCookieOptions, getJwtCookie } from './cookie.js';
+import { NextRequest } from 'next/server';
+import { getCookieOptions, getJwtCookie, getPKCECookieOptions } from './cookie.js';
 import { WORKOS_CLIENT_ID, WORKOS_COOKIE_NAME, WORKOS_COOKIE_PASSWORD, WORKOS_REDIRECT_URI } from './env-variables.js';
+import { TokenRefreshError, getSessionErrorContext } from './errors.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import {
   AccessToken,
@@ -17,11 +18,30 @@ import {
   Session,
   UserInfo,
 } from './interfaces.js';
+import { getPKCECookieNameForState, setPKCECookie } from './pkce.js';
 import { getWorkOS } from './workos.js';
 
 import type { AuthenticationResponse } from '@workos-inc/node';
 import { parse, tokensToRegexp } from 'path-to-regexp';
-import { lazy, redirectWithFallback } from './utils.js';
+import { handleAuthkitHeaders } from './middleware-helpers.js';
+import { lazy, setCachePreventionHeaders } from './utils.js';
+
+// Only set the PKCE cookie for initial document navigations — fetch/XHR/RSC/prefetch
+// requests never follow cross-origin redirects so they'll never complete the OAuth
+// flow and therefore don't need the cookie set.
+// This prevents cookie bloat (HTTP 431) when multiple requests fire concurrently
+// now that we are generating unique cookie names per flow, they add up quickly if
+// we don't limit to just the initial navigation request
+function appendPKCESetCookieHeader(request: NextRequest, headers: Headers, sealedState: string): void {
+  if (!isInitialDocumentRequest(request)) {
+    return;
+  }
+
+  headers.append(
+    'Set-Cookie',
+    `${getPKCECookieNameForState(sealedState)}=${sealedState}; ${getPKCECookieOptions(request.url, true)}`,
+  );
+}
 
 const sessionHeaderName = 'x-workos-session';
 const middlewareHeaderName = 'x-workos-middleware';
@@ -30,6 +50,49 @@ const jwtCookieName = 'workos-access-token';
 
 const JWKS = lazy(() => createRemoteJWKSet(new URL(getWorkOS().userManagement.getJwksUrl(WORKOS_CLIENT_ID))));
 
+/**
+ * Applies cache security headers with Vary header deduplication.
+ * Only applies headers if the request is authenticated (has session, cookie, or Authorization header).
+ * Used in middleware where existing Vary headers may already be present.
+ * @param headers - The Headers object to set the cache security headers on.
+ * @param request - The NextRequest object to check for authentication.
+ * @param sessionData - Optional session data to check for authentication.
+ */
+function applyCacheSecurityHeaders(
+  headers: Headers,
+  request: NextRequest,
+  sessionData?: { accessToken?: string } | Session,
+): void {
+  const cookieName = WORKOS_COOKIE_NAME || 'wos-session';
+
+  // Only apply cache headers for authenticated requests
+  if (!sessionData?.accessToken && !request.cookies.has(cookieName) && !request.headers.has('authorization')) {
+    return;
+  }
+
+  const varyValues = new Set<string>(['cookie']);
+  if (request.headers.has('authorization')) {
+    varyValues.add('authorization');
+  }
+
+  const currentVary = headers.get('Vary');
+  if (currentVary) {
+    currentVary.split(',').forEach((v) => {
+      const trimmed = v.trim().toLowerCase();
+      if (trimmed) varyValues.add(trimmed);
+    });
+  }
+
+  headers.set(
+    'Vary',
+    Array.from(varyValues)
+      .map((v) => v.charAt(0).toUpperCase() + v.slice(1))
+      .join(', '),
+  );
+
+  setCachePreventionHeaders(headers);
+}
+
 /**
  * Determines if a request is for an initial document load (not API/RSC/prefetch)
  */
@@ -106,23 +169,23 @@ async function updateSessionMiddleware(
     eagerAuth,
   });
 
+  // Record the sign up paths so we can use them later
+  if (signUpPaths.length > 0) {
+    headers.set(signUpPathsHeaderName, signUpPaths.join(','));
+  }
+
+  applyCacheSecurityHeaders(headers, request, session);
+
   // If the user is logged out and this path isn't on the allowlist for logged out paths, redirect to AuthKit.
   if (middlewareAuth.enabled && matchedPaths.length === 0 && !session.user) {
     if (debug) {
       console.log(`Unauthenticated user on protected route ${request.url}, redirecting to AuthKit`);
     }
 
-    return redirectWithFallback(authorizationUrl as string, headers);
-  }
-
-  // Record the sign up paths so we can use them later
-  if (signUpPaths.length > 0) {
-    headers.set(signUpPathsHeaderName, signUpPaths.join(','));
+    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl as string });
   }
 
-  return NextResponse.next({
-    headers,
-  });
+  return handleAuthkitHeaders(request, headers);
 }
 
 async function updateSession(
@@ -157,14 +220,18 @@ async function updateSession(
       console.log('No session found from cookie');
     }
 
+    const { url: authorizationUrl, sealedState } = await getAuthorizationUrl({
+      returnPathname: getReturnPathname(request.url),
+      redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
+      screenHint: options.screenHint,
+    });
+
+    appendPKCESetCookieHeader(request, newRequestHeaders, sealedState);
+
     return {
       session: { user: null },
       headers: newRequestHeaders,
-      authorizationUrl: await getAuthorizationUrl({
-        returnPathname: getReturnPathname(request.url),
-        redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
-        screenHint: options.screenHint,
-      }),
+      authorizationUrl,
     };
   }
 
@@ -172,6 +239,8 @@ async function updateSession(
 
   const cookieName = WORKOS_COOKIE_NAME || 'wos-session';
 
+  applyCacheSecurityHeaders(newRequestHeaders, request, session);
+
   if (hasValidSession) {
     newRequestHeaders.set(sessionHeaderName, request.cookies.get(cookieName)!.value);
 
@@ -293,13 +362,17 @@ async function updateSession(
 
     options.onSessionRefreshError?.({ error: e, request });
 
+    const { url: authorizationUrl, sealedState } = await getAuthorizationUrl({
+      returnPathname: getReturnPathname(request.url),
+      redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
+    });
+
+    appendPKCESetCookieHeader(request, newRequestHeaders, sealedState);
+
     return {
       session: { user: null },
       headers: newRequestHeaders,
-      authorizationUrl: await getAuthorizationUrl({
-        returnPathname: getReturnPathname(request.url),
-        redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
-      }),
+      authorizationUrl,
     };
   }
 }
@@ -335,9 +408,11 @@ async function refreshSession({
       organizationId: nextOrganizationId ?? organizationIdFromAccessToken,
     });
   } catch (error) {
-    throw new Error(`Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`, {
-      cause: error,
-    });
+    throw new TokenRefreshError(
+      `Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`,
+      error,
+      getSessionErrorContext(session),
+    );
   }
 
   const headersList = await headers();
@@ -404,7 +479,9 @@ async function redirectToSignIn() {
 
   const returnPathname = getReturnPathname(url);
 
-  redirect(await getAuthorizationUrl({ returnPathname, screenHint }));
+  const { url: authkitUrl, sealedState } = await getAuthorizationUrl({ returnPathname, screenHint });
+  await setPKCECookie(sealedState);
+  redirect(authkitUrl);
 }
 
 export async function getTokenClaims<T = Record<string, unknown>>(
@@ -488,7 +565,7 @@ async function getSessionFromHeader(): Promise<Session | undefined> {
   if (!hasMiddleware) {
     const url = headersList.get('x-url');
     throw new Error(
-      `You are calling 'withAuth' on ${url ?? 'a route'} that isn’t covered by the AuthKit middleware. Make sure it is running on all paths you are calling 'withAuth' from by updating your middleware config in 'middleware.(js|ts)'.`,
+      `You are calling 'withAuth' on ${url ?? 'a route'} that isn't covered by the AuthKit middleware. Make sure it is running on all paths you are calling 'withAuth' from by updating your middleware config in 'middleware.(js|ts)'.`,
     );
   }
 
@@ -501,7 +578,7 @@ async function getSessionFromHeader(): Promise<Session | undefined> {
 function getReturnPathname(url: string): string {
   const newUrl = new URL(url);
 
-  return `${newUrl.pathname}${newUrl.searchParams.size > 0 ? '?' + newUrl.searchParams.toString() : ''}`;
+  return `${newUrl.pathname}${newUrl.search}`;
 }
 
 function getScreenHint(signUpPaths: string[] | undefined, pathname: string) {

package/src/test-helpers.ts

@@ -43,9 +43,9 @@ export async function generateSession(overrides: Partial<User> = {}) {
     createdAt: '2024-01-01T00:00:00Z',
     updatedAt: '2024-01-01T00:00:00Z',
     lastSignInAt: '2024-01-01T00:00:00Z',
-    locale: null,
     externalId: null,
     metadata: {},
+    locale: null,
     ...overrides,
   } satisfies User;
 

package/src/utils.spec.ts

@@ -3,23 +3,21 @@ import { redirectWithFallback, errorResponseWithFallback } from './utils.js';
 
 describe('utils', () => {
   afterEach(() => {
-    jest.resetModules();
+    vi.resetModules();
+    vi.restoreAllMocks();
   });
 
   describe('redirectWithFallback', () => {
     it('uses NextResponse.redirect when available', () => {
       const redirectUrl = 'https://example.com';
-      const mockRedirect = jest.fn().mockReturnValue('redirected');
-      const originalRedirect = NextResponse.redirect;
+      const mockRedirect = vi.fn().mockReturnValue('redirected');
 
-      NextResponse.redirect = mockRedirect;
+      vi.spyOn(NextResponse, 'redirect').mockImplementation(mockRedirect);
 
       const result = redirectWithFallback(redirectUrl);
 
       expect(mockRedirect).toHaveBeenCalledWith(redirectUrl, { headers: undefined });
       expect(result).toBe('redirected');
-
-      NextResponse.redirect = originalRedirect;
     });
 
     it('uses headers when provided', () => {
@@ -35,9 +33,9 @@ describe('utils', () => {
     it('falls back to standard Response when NextResponse exists but redirect is undefined', async () => {
       const redirectUrl = 'https://example.com';
 
-      jest.resetModules();
+      vi.resetModules();
 
-      jest.mock('next/server', () => ({
+      vi.doMock('next/server', () => ({
         NextResponse: {
           // exists but has no redirect method
         },
@@ -55,10 +53,10 @@ describe('utils', () => {
     it('falls back to standard Response when NextResponse is undefined', async () => {
       const redirectUrl = 'https://example.com';
 
-      jest.resetModules();
+      vi.resetModules();
 
       // Mock with undefined NextResponse
-      jest.mock('next/server', () => ({
+      vi.doMock('next/server', () => ({
         NextResponse: undefined,
       }));
 
@@ -81,8 +79,8 @@ describe('utils', () => {
     };
 
     it('uses NextResponse.json when available', () => {
-      const mockJson = jest.fn().mockReturnValue('error json response');
-      NextResponse.json = mockJson;
+      const mockJson = vi.fn().mockReturnValue('error json response');
+      vi.spyOn(NextResponse, 'json').mockImplementation(mockJson);
 
       const result = errorResponseWithFallback(errorBody);
 
@@ -90,25 +88,10 @@ describe('utils', () => {
       expect(result).toBe('error json response');
     });
 
-    it('falls back to standard Response when NextResponse is not available', () => {
-      const originalJson = NextResponse.json;
-
-      // @ts-expect-error - This is to test the fallback
-      delete NextResponse.json;
-
-      const result = errorResponseWithFallback(errorBody);
-
-      expect(result).toBeInstanceOf(Response);
-      expect(result.status).toBe(500);
-      expect(result.headers.get('Content-Type')).toBe('application/json');
-
-      NextResponse.json = originalJson;
-    });
-
     it('falls back to standard Response when NextResponse exists but json is undefined', async () => {
-      jest.resetModules();
+      vi.resetModules();
 
-      jest.mock('next/server', () => ({
+      vi.doMock('next/server', () => ({
         NextResponse: {
           // exists but has no json method
         },
@@ -124,9 +107,9 @@ describe('utils', () => {
     });
 
     it('falls back to standard Response when NextResponse is undefined', async () => {
-      jest.resetModules();
+      vi.resetModules();
 
-      jest.mock('next/server', () => ({
+      vi.doMock('next/server', () => ({
         NextResponse: undefined,
       }));
 

package/src/utils.ts

@@ -1,5 +1,14 @@
 import { NextResponse } from 'next/server';
 
+/**
+ * Sets cache prevention headers to prevent CDN/proxy caching.
+ * @param headers - The Headers object to set the cache prevention headers on.
+ */
+export function setCachePreventionHeaders(headers: Headers): void {
+  headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate, max-age=0');
+  headers.set('x-middleware-cache', 'no-cache');
+}
+
 export function redirectWithFallback(redirectUri: string, headers?: Headers) {
   const newHeaders = headers ? new Headers(headers) : new Headers();
   newHeaders.set('Location', redirectUri);

package/src/validate-api-key.spec.ts

@@ -0,0 +1,111 @@
+import { validateApiKey } from './validate-api-key.js';
+import { getWorkOS } from './workos.js';
+
+// These are mocked in vitest.setup.ts
+import { headers } from 'next/headers';
+
+const workos = getWorkOS();
+
+describe('validate-api-key.ts', () => {
+  beforeEach(async () => {
+    // Clear all mocks between tests
+    vi.clearAllMocks();
+
+    const nextHeaders = await headers();
+    // @ts-expect-error - _reset is part of the mock
+    nextHeaders._reset();
+  });
+
+  describe('validateApiKey', () => {
+    it('should return valid API key when Bearer token is present and valid', async () => {
+      const mockApiKeyResponse = {
+        apiKey: {
+          id: 'api_key_123',
+          object: 'api_key' as const,
+          name: 'Test API Key',
+          obfuscatedValue: 'sk_…7890',
+          createdAt: '2024-01-01T00:00:00Z',
+          updatedAt: '2024-01-01T00:00:00Z',
+          lastUsedAt: '2024-01-01T00:00:00Z',
+          permissions: [],
+          owner: { type: 'organization' as const, id: 'org_123' },
+        },
+      };
+
+      vi.spyOn(workos.apiKeys, 'validateApiKey').mockResolvedValue(mockApiKeyResponse);
+
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', 'Bearer sk_test_1234567890');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).toHaveBeenCalledWith({
+        value: 'sk_test_1234567890',
+      });
+      expect(result).toEqual(mockApiKeyResponse);
+    });
+
+    it('should return { apiKey: null } when no authorization header is present', async () => {
+      // Don't set any authorization header
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).not.toHaveBeenCalled();
+      expect(result).toEqual({ apiKey: null });
+    });
+
+    it('should return { apiKey: null } when authorization header is empty', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', '');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).not.toHaveBeenCalled();
+      expect(result).toEqual({ apiKey: null });
+    });
+
+    it('should return { apiKey: null } when authorization header does not start with Bearer', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', 'Basic dXNlcjpwYXNz');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).not.toHaveBeenCalled();
+      expect(result).toEqual({ apiKey: null });
+    });
+
+    it('should return { apiKey: null } when Bearer token is missing', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', 'Bearer');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).not.toHaveBeenCalled();
+      expect(result).toEqual({ apiKey: null });
+    });
+
+    it('should return { apiKey: null } when Bearer token is only whitespace', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', 'Bearer   ');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).not.toHaveBeenCalled();
+      expect(result).toEqual({ apiKey: null });
+    });
+
+    it('should return { apiKey: null } when WorkOS validation fails', async () => {
+      const mockResponse = { apiKey: null };
+      vi.spyOn(workos.apiKeys, 'validateApiKey').mockResolvedValue(mockResponse);
+
+      const nextHeaders = await headers();
+      nextHeaders.set('authorization', 'Bearer invalid_key');
+
+      const result = await validateApiKey();
+
+      expect(workos.apiKeys.validateApiKey).toHaveBeenCalledWith({
+        value: 'invalid_key',
+      });
+      expect(result).toEqual({ apiKey: null });
+    });
+  });
+});

package/src/validate-api-key.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { getWorkOS } from './workos.js';
+import { headers } from 'next/headers';
+
+export async function validateApiKey() {
+  const headersList = await headers();
+  const authorizationHeader = headersList.get('authorization');
+  if (!authorizationHeader) {
+    return { apiKey: null };
+  }
+
+  const value = authorizationHeader.match(/Bearer\s+(.*)/i)?.[1];
+  if (!value) {
+    return { apiKey: null };
+  }
+
+  return getWorkOS().apiKeys.validateApiKey({ value });
+}

package/src/workos.spec.ts

@@ -4,7 +4,7 @@ import { getWorkOS, VERSION } from './workos.js';
 describe('workos', () => {
   const workos = getWorkOS();
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   it('initializes WorkOS with the correct configuration', () => {
@@ -35,7 +35,7 @@ describe('workos', () => {
     const originalEnv = process.env;
 
     beforeEach(() => {
-      jest.resetModules();
+      vi.resetModules();
       process.env = { ...originalEnv };
     });
 

package/src/workos.ts

@@ -2,7 +2,7 @@ import { WorkOS } from '@workos-inc/node';
 import { WORKOS_API_HOSTNAME, WORKOS_API_KEY, WORKOS_API_HTTPS, WORKOS_API_PORT } from './env-variables.js';
 import { lazy } from './utils.js';
 
-export const VERSION = '2.10.0';
+export const VERSION = '2.14.0';
 
 const options = {
   apiHostname: WORKOS_API_HOSTNAME,