@workos-inc/authkit-nextjs 2.12.1 → 2.13.0

package/src/middleware-helpers.spec.ts

@@ -0,0 +1,231 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  handleAuthkitHeaders,
+  partitionAuthkitHeaders,
+  applyResponseHeaders,
+  isAuthkitRequestHeader,
+  AUTHKIT_REQUEST_HEADERS,
+} from './middleware-helpers.js';
+
+describe('middleware-helpers', () => {
+  function createMockRequest(url = 'https://example.com/test', method = 'GET'): NextRequest {
+    return new NextRequest(url, { method });
+  }
+
+  function createAuthkitHeaders(): Headers {
+    const headers = new Headers();
+    headers.set('x-workos-middleware', 'true');
+    headers.set('x-workos-session', 'encrypted-session-data');
+    headers.set('x-url', 'https://example.com/test');
+    headers.set('set-cookie', 'wos-session=abc123; Path=/; HttpOnly');
+    headers.set('cache-control', 'private, no-cache');
+    headers.set('vary', 'Cookie');
+    return headers;
+  }
+
+  describe('isAuthkitRequestHeader', () => {
+    it('should recognize known headers and x-workos-* pattern', () => {
+      expect(isAuthkitRequestHeader('x-workos-middleware')).toBe(true);
+      expect(isAuthkitRequestHeader('x-workos-session')).toBe(true);
+      expect(isAuthkitRequestHeader('x-url')).toBe(true);
+      expect(isAuthkitRequestHeader('x-workos-future-header')).toBe(true);
+      // Case insensitive
+      expect(isAuthkitRequestHeader('X-WorkOS-Session')).toBe(true);
+    });
+
+    it('should reject non-authkit headers', () => {
+      expect(isAuthkitRequestHeader('set-cookie')).toBe(false);
+      expect(isAuthkitRequestHeader('content-type')).toBe(false);
+      expect(isAuthkitRequestHeader('x-custom-header')).toBe(false);
+    });
+  });
+
+  describe('partitionAuthkitHeaders', () => {
+    it('should split headers into request-only and response headers', () => {
+      const request = createMockRequest();
+      const authkitHeaders = createAuthkitHeaders();
+
+      const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      // Request headers contain internal authkit headers
+      expect(requestHeaders.get('x-workos-session')).toBe('encrypted-session-data');
+      expect(requestHeaders.get('x-workos-middleware')).toBe('true');
+
+      // Response headers contain browser-safe headers only
+      expect(responseHeaders.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+      expect(responseHeaders.get('cache-control')).toBe('private, no-cache');
+      expect(responseHeaders.get('vary')).toBe('Cookie');
+
+      // Internal headers NOT in response
+      expect(responseHeaders.get('x-workos-session')).toBeNull();
+      expect(responseHeaders.get('x-workos-middleware')).toBeNull();
+    });
+
+    it('should preserve original request headers while adding authkit headers', () => {
+      const request = createMockRequest();
+      request.headers.set('authorization', 'Bearer token');
+      request.headers.set('x-custom', 'value');
+
+      const { requestHeaders } = partitionAuthkitHeaders(request, createAuthkitHeaders());
+
+      expect(requestHeaders.get('authorization')).toBe('Bearer token');
+      expect(requestHeaders.get('x-custom')).toBe('value');
+      expect(requestHeaders.get('x-workos-session')).toBe('encrypted-session-data');
+    });
+
+    it('should filter response headers to allowlist only', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('set-cookie', 'session=abc');
+      authkitHeaders.set('x-dangerous-header', 'leaked');
+      authkitHeaders.set('location', 'https://evil.com');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('set-cookie')).toBe('session=abc');
+      expect(responseHeaders.get('x-dangerous-header')).toBeNull();
+      expect(responseHeaders.get('location')).toBeNull();
+    });
+
+    it('should handle multiple Set-Cookie headers correctly', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.append('set-cookie', 'cookie1=value1');
+      authkitHeaders.append('set-cookie', 'cookie2=value2');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.getSetCookie()).toHaveLength(2);
+    });
+
+    it('should auto-add cache-control: no-store when cookies present without cache-control', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('set-cookie', 'session=abc');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('cache-control')).toBe('no-store');
+    });
+
+    it('should deduplicate and merge Vary header values', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.append('vary', 'Cookie');
+      authkitHeaders.append('vary', 'Cookie, Accept');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('vary')).toBe('Cookie, Accept');
+    });
+
+    it('should forward x-middleware-cache header', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('x-middleware-cache', 'no-cache');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('x-middleware-cache')).toBe('no-cache');
+    });
+
+    it('should strip client-injected x-workos-* headers and use trusted values', () => {
+      const request = createMockRequest();
+      request.headers.set('x-workos-session', 'malicious-session');
+      request.headers.set('x-workos-admin-bypass', 'true');
+
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('x-workos-session', 'real-session');
+
+      const { requestHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(requestHeaders.get('x-workos-session')).toBe('real-session');
+      expect(requestHeaders.get('x-workos-admin-bypass')).toBeNull();
+    });
+  });
+
+  describe('handleAuthkitHeaders', () => {
+    it('should return NextResponse with response headers applied', () => {
+      const request = createMockRequest();
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders());
+
+      expect(response).toBeInstanceOf(NextResponse);
+      expect(response.status).toBe(200);
+      expect(response.headers.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+      expect(response.headers.get('vary')).toBe('Cookie');
+
+      // Internal headers NOT leaked
+      for (const header of AUTHKIT_REQUEST_HEADERS) {
+        expect(response.headers.get(header)).toBeNull();
+      }
+    });
+
+    it('should redirect with normalized absolute URL', () => {
+      const request = createMockRequest('https://example.com/page');
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders(), {
+        redirect: '/login',
+      });
+
+      expect(response.status).toBe(307);
+      expect(response.headers.get('location')).toBe('https://example.com/login');
+      expect(response.headers.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+    });
+
+    it('should use 307 for GET and 303 for POST redirects by default', () => {
+      const getRequest = createMockRequest('https://example.com/test', 'GET');
+      const postRequest = createMockRequest('https://example.com/test', 'POST');
+      const headers = createAuthkitHeaders();
+
+      const getResponse = handleAuthkitHeaders(getRequest, headers, { redirect: '/login' });
+      const postResponse = handleAuthkitHeaders(postRequest, headers, { redirect: '/login' });
+
+      expect(getResponse.status).toBe(307);
+      expect(postResponse.status).toBe(303);
+    });
+
+    it('should allow overriding redirect status', () => {
+      const request = createMockRequest();
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders(), {
+        redirect: '/login',
+        redirectStatus: 302,
+      });
+
+      expect(response.status).toBe(302);
+    });
+
+    it('should throw clear error on invalid redirect URL', () => {
+      const request = createMockRequest();
+
+      expect(() =>
+        handleAuthkitHeaders(request, createAuthkitHeaders(), {
+          redirect: 'http://[invalid',
+        }),
+      ).toThrow('Invalid redirect URL: "http://[invalid". Must be a valid absolute or relative URL.');
+    });
+
+    it('should treat empty/undefined redirect as no redirect', () => {
+      const request = createMockRequest();
+      const headers = createAuthkitHeaders();
+
+      expect(handleAuthkitHeaders(request, headers, { redirect: '' }).status).toBe(200);
+      expect(handleAuthkitHeaders(request, headers, { redirect: undefined }).status).toBe(200);
+    });
+  });
+
+  describe('applyResponseHeaders', () => {
+    it('should merge headers onto existing response', () => {
+      const response = NextResponse.next();
+      response.headers.set('vary', 'Accept');
+      response.headers.set('set-cookie', 'existing=value');
+
+      const headers = new Headers();
+      headers.set('vary', 'Cookie');
+      headers.set('set-cookie', 'new=value');
+
+      applyResponseHeaders(response, headers);
+
+      expect(response.headers.get('vary')).toBe('Accept, Cookie');
+      expect(response.headers.getSetCookie()).toHaveLength(2);
+    });
+  });
+});

package/src/middleware-helpers.ts

@@ -0,0 +1,130 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/** Internal AuthKit headers - forwarded to downstream requests but never sent to browser. */
+export const AUTHKIT_REQUEST_HEADERS = [
+  'x-workos-middleware',
+  'x-url',
+  'x-redirect-uri',
+  'x-sign-up-paths',
+  'x-workos-session',
+] as const;
+
+export type AuthkitRequestHeader = (typeof AUTHKIT_REQUEST_HEADERS)[number];
+
+const ALLOWED_RESPONSE_HEADERS: readonly string[] = [
+  'set-cookie',
+  'cache-control',
+  'vary',
+  'www-authenticate',
+  'proxy-authenticate',
+  'link',
+  'x-middleware-cache',
+];
+
+const MULTI_VALUE_HEADERS: readonly string[] = ['set-cookie', 'www-authenticate', 'proxy-authenticate', 'link'];
+
+export function isAuthkitRequestHeader(name: string): boolean {
+  const lower = name.toLowerCase();
+  return (AUTHKIT_REQUEST_HEADERS as readonly string[]).includes(lower) || lower.startsWith('x-workos-');
+}
+
+function setHeader(headers: Headers, name: string, value: string): void {
+  const lower = name.toLowerCase();
+  if (MULTI_VALUE_HEADERS.includes(lower)) {
+    headers.append(name, value);
+  } else if (lower === 'vary') {
+    const existing = headers.get(name);
+    const merged = new Set([
+      ...(existing ? existing.split(',').map((v) => v.trim()) : []),
+      ...value.split(',').map((v) => v.trim()),
+    ]);
+    headers.set(name, [...merged].join(', '));
+  } else {
+    headers.set(name, value);
+  }
+}
+
+export interface AuthkitHeadersResult {
+  requestHeaders: Headers;
+  responseHeaders: Headers;
+}
+
+/**
+ * Partitions AuthKit headers into request headers (for withAuth) and response headers (for browser).
+ */
+export function partitionAuthkitHeaders(request: NextRequest, authkitHeaders: Headers): AuthkitHeadersResult {
+  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()]) {
+    if (isAuthkitRequestHeader(name)) {
+      requestHeaders.delete(name);
+    }
+  }
+  for (const headerName of AUTHKIT_REQUEST_HEADERS) {
+    const value = headers.get(headerName);
+    if (value != null) {
+      requestHeaders.set(headerName, value);
+    }
+  }
+
+  // Build response headers from allowlist only
+  const responseHeaders = new Headers();
+  for (const [name, value] of headers) {
+    const lower = name.toLowerCase();
+    if (!isAuthkitRequestHeader(lower) && ALLOWED_RESPONSE_HEADERS.includes(lower)) {
+      setHeader(responseHeaders, name, value);
+    }
+  }
+
+  // Auto-add cache-control when setting cookies
+  if (responseHeaders.has('set-cookie') && !responseHeaders.has('cache-control')) {
+    responseHeaders.set('cache-control', 'no-store');
+  }
+
+  return { requestHeaders, responseHeaders };
+}
+
+export function applyResponseHeaders(response: NextResponse, responseHeaders: Headers): NextResponse {
+  for (const [name, value] of responseHeaders) {
+    setHeader(response.headers, name, value);
+  }
+  return response;
+}
+
+export type AuthkitRedirectStatus = 302 | 303 | 307 | 308;
+
+export interface HandleAuthkitHeadersOptions {
+  /** URL to redirect to (relative or absolute). */
+  redirect?: string | URL;
+
+  /** Redirect status code. @default 307 for GET/HEAD, 303 for POST/PUT/DELETE */
+  redirectStatus?: AuthkitRedirectStatus;
+}
+
+/**
+ * Creates a NextResponse with properly merged AuthKit headers.
+ */
+export function handleAuthkitHeaders(
+  request: NextRequest,
+  authkitHeaders: Headers,
+  options: HandleAuthkitHeadersOptions = {},
+): NextResponse {
+  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+  const { redirect, redirectStatus } = options;
+
+  if (redirect != null && redirect !== '') {
+    let redirectUrl: URL;
+    try {
+      redirectUrl = redirect instanceof URL ? redirect : new URL(redirect, request.url);
+    } catch {
+      throw new Error(`Invalid redirect URL: "${redirect}". Must be a valid absolute or relative URL.`);
+    }
+    const method = request.method.toUpperCase();
+    const status = redirectStatus ?? (method === 'GET' || method === 'HEAD' ? 307 : 303);
+    return applyResponseHeaders(NextResponse.redirect(redirectUrl, status), responseHeaders);
+  }
+
+  return applyResponseHeaders(NextResponse.next({ request: { headers: requestHeaders } }), responseHeaders);
+}

package/src/session.spec.ts

@@ -374,10 +374,7 @@ describe('session.ts', () => {
         );
       });
 
-      it('should use Response if NextResponse.redirect is not available', async () => {
-        const originalRedirect = NextResponse.redirect;
-        (NextResponse as Partial<typeof NextResponse>).redirect = undefined;
-
+      it('should return a redirect response when middlewareAuth is enabled and user is not authenticated', async () => {
         const request = new NextRequest(new URL('http://example.com/protected'));
         const result = await updateSessionMiddleware(
           request,
@@ -390,10 +387,9 @@ describe('session.ts', () => {
           [],
         );
 
-        expect(result).toBeInstanceOf(Response);
-
-        // Restore the original redirect method
-        (NextResponse as Partial<typeof NextResponse>).redirect = originalRedirect;
+        expect(result).toBeInstanceOf(NextResponse);
+        expect(result.status).toBe(307);
+        expect(result.headers.get('Location')).toContain('workos.com');
       });
 
       it('should automatically add the redirect URI to unauthenticatedPaths when middleware is enabled', async () => {
@@ -429,7 +425,7 @@ describe('session.ts', () => {
         expect(result.headers.get('Location')).toContain('screen_hint=sign-up');
       });
 
-      it('should set the sign up paths in the headers', async () => {
+      it('should not leak sign-up paths header to the browser', async () => {
         const request = new NextRequest(new URL('http://example.com/protected-signup'));
         const result = await updateSessionMiddleware(
           request,
@@ -442,7 +438,8 @@ describe('session.ts', () => {
           ['/protected-signup'],
         );
 
-        expect(result.headers.get('x-sign-up-paths')).toBe('/protected-signup');
+        // x-sign-up-paths is an internal header that should not leak to the browser
+        expect(result.headers.get('x-sign-up-paths')).toBeNull();
       });
 
       it('should allow logged out users on unauthenticated paths', async () => {

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 { NextRequest } from 'next/server';
 import { getCookieOptions, getJwtCookie } 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,
@@ -21,7 +22,8 @@ import { getWorkOS } from './workos.js';
 
 import type { AuthenticationResponse } from '@workos-inc/node';
 import { parse, tokensToRegexp } from 'path-to-regexp';
-import { lazy, redirectWithFallback, setCachePreventionHeaders } from './utils.js';
+import { handleAuthkitHeaders } from './middleware-helpers.js';
+import { lazy, setCachePreventionHeaders } from './utils.js';
 
 const sessionHeaderName = 'x-workos-session';
 const middlewareHeaderName = 'x-workos-middleware';
@@ -149,15 +151,6 @@ async function updateSessionMiddleware(
     eagerAuth,
   });
 
-  // 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(','));
@@ -165,33 +158,16 @@ async function updateSessionMiddleware(
 
   applyCacheSecurityHeaders(headers, request, session);
 
-  // Create a new request with modified headers (for page handlers)
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.set(middlewareHeaderName, headers.get(middlewareHeaderName)!);
-  requestHeaders.set('x-url', headers.get('x-url')!);
-  if (headers.has('x-redirect-uri')) {
-    requestHeaders.set('x-redirect-uri', headers.get('x-redirect-uri')!);
-  }
-  if (headers.has(signUpPathsHeaderName)) {
-    requestHeaders.set(signUpPathsHeaderName, headers.get(signUpPathsHeaderName)!);
-  }
+  // 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`);
+    }
 
-  // Pass session to page handlers via request header
-  // This ensures handlers see refreshed sessions immediately (before Set-Cookie reaches browser)
-  const sessionHeader = headers.get(sessionHeaderName);
-  if (sessionHeader) {
-    requestHeaders.set(sessionHeaderName, sessionHeader);
+    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl as string });
   }
 
-  // Remove session header from response headers to prevent leakage
-  headers.delete(sessionHeaderName);
-
-  return NextResponse.next({
-    request: {
-      headers: requestHeaders,
-    },
-    headers,
-  });
+  return handleAuthkitHeaders(request, headers);
 }
 
 async function updateSession(
@@ -406,9 +382,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();

package/src/utils.ts

@@ -6,8 +6,6 @@ import { NextResponse } from 'next/server';
  */
 export function setCachePreventionHeaders(headers: Headers): void {
   headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate, max-age=0');
-  headers.set('Pragma', 'no-cache');
-  headers.set('Expires', '0');
   headers.set('x-middleware-cache', 'no-cache');
 }
 

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.12.1';
+export const VERSION = '2.13.0';
 
 const options = {
   apiHostname: WORKOS_API_HOSTNAME,