@workos-inc/authkit-nextjs 2.12.2 → 2.14.0

package/src/errors.spec.ts

@@ -0,0 +1,108 @@
+import { AuthKitError, TokenRefreshError, getSessionErrorContext } from './errors.js';
+import type { Session } from './interfaces.js';
+import type { User } from '@workos-inc/node';
+
+describe('AuthKitError', () => {
+  it('creates error with message', () => {
+    const error = new AuthKitError('Test error');
+
+    expect(error.message).toBe('Test error');
+    expect(error.name).toBe('AuthKitError');
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('creates error with cause and data', () => {
+    const originalError = new Error('Original error');
+    const data = { userId: '123' };
+    const error = new AuthKitError('Test error', originalError, data);
+
+    expect(error.cause).toBe(originalError);
+    expect(error.data).toEqual(data);
+  });
+});
+
+describe('TokenRefreshError', () => {
+  it('creates error with correct name and inheritance', () => {
+    const error = new TokenRefreshError('Refresh failed');
+
+    expect(error.name).toBe('TokenRefreshError');
+    expect(error.message).toBe('Refresh failed');
+    expect(error).toBeInstanceOf(AuthKitError);
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('creates error with cause and context', () => {
+    const originalError = new Error('Network error');
+    const error = new TokenRefreshError('Refresh failed', originalError, {
+      userId: 'user_123',
+      sessionId: 'session_456',
+    });
+
+    expect(error.cause).toBe(originalError);
+    expect(error.userId).toBe('user_123');
+    expect(error.sessionId).toBe('session_456');
+  });
+
+  it('has undefined properties when no context provided', () => {
+    const error = new TokenRefreshError('Refresh failed');
+
+    expect(error.userId).toBeUndefined();
+    expect(error.sessionId).toBeUndefined();
+  });
+});
+
+describe('getSessionErrorContext', () => {
+  function createTestJwt(payload: Record<string, unknown>): string {
+    const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+    const payloadStr = btoa(JSON.stringify(payload));
+    return `${header}.${payloadStr}.test-signature`;
+  }
+
+  it('returns empty object for missing session', () => {
+    expect(getSessionErrorContext(null)).toEqual({});
+    expect(getSessionErrorContext(undefined)).toEqual({});
+  });
+
+  it('extracts userId and sessionId from access token', () => {
+    const session: Session = {
+      accessToken: createTestJwt({ sub: 'user_456', sid: 'session_123' }),
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_456',
+        email: 'test@example.com',
+        emailVerified: true,
+        profilePictureUrl: null,
+        firstName: null,
+        lastName: null,
+        createdAt: '2024-01-01',
+        updatedAt: '2024-01-01',
+        object: 'user',
+      } as User,
+    };
+
+    const context = getSessionErrorContext(session);
+    expect(context.userId).toBe('user_456');
+    expect(context.sessionId).toBe('session_123');
+  });
+
+  it('returns empty object for invalid JWT', () => {
+    const session: Session = {
+      accessToken: 'invalid-jwt',
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_123',
+        email: 'test@example.com',
+        emailVerified: true,
+        profilePictureUrl: null,
+        firstName: null,
+        lastName: null,
+        createdAt: '2024-01-01',
+        updatedAt: '2024-01-01',
+        object: 'user',
+      } as User,
+    };
+
+    const context = getSessionErrorContext(session);
+    expect(context).toEqual({});
+  });
+});

package/src/errors.ts

@@ -0,0 +1,46 @@
+import type { Session } from './interfaces.js';
+import { decodeJwt } from './jwt.js';
+
+export class AuthKitError extends Error {
+  data?: Record<string, unknown>;
+
+  constructor(message: string, cause?: unknown, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'AuthKitError';
+    this.cause = cause;
+    this.data = data;
+  }
+}
+
+export interface TokenRefreshErrorContext {
+  userId?: string;
+  sessionId?: string;
+}
+
+export class TokenRefreshError extends AuthKitError {
+  readonly userId?: string;
+  readonly sessionId?: string;
+
+  constructor(message: string, cause?: unknown, context?: TokenRefreshErrorContext) {
+    super(message, cause);
+    this.name = 'TokenRefreshError';
+    this.userId = context?.userId;
+    this.sessionId = context?.sessionId;
+  }
+}
+
+export function getSessionErrorContext(session?: Session | null): TokenRefreshErrorContext {
+  if (!session?.accessToken) {
+    return {};
+  }
+
+  try {
+    const { payload } = decodeJwt(session.accessToken);
+    return {
+      userId: payload.sub,
+      sessionId: payload.sid,
+    };
+  } catch {
+    return {};
+  }
+}

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

@@ -1,25 +1,24 @@
-import { describe, it, expect, beforeEach, jest } from '@jest/globals';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import { headers } from 'next/headers';
 import { getWorkOS } from './workos.js';
 
-jest.mock('next/headers');
-
 // Mock dependencies
-const fakeWorkosInstance = {
-  userManagement: {
-    getAuthorizationUrl: jest.fn(),
+const { fakeWorkosInstance } = vi.hoisted(() => ({
+  fakeWorkosInstance: {
+    userManagement: {
+      getAuthorizationUrl: vi.fn(),
+    },
   },
-};
+}));
 
-jest.mock('./workos', () => ({
-  getWorkOS: jest.fn(() => fakeWorkosInstance),
+vi.mock('./workos', () => ({
+  getWorkOS: vi.fn(() => fakeWorkosInstance),
 }));
 
 describe('getAuthorizationUrl', () => {
   const workos = getWorkOS();
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   it('uses x-redirect-uri header when redirectUri option is not provided', async () => {
@@ -27,7 +26,7 @@ describe('getAuthorizationUrl', () => {
     nextHeaders.set('x-redirect-uri', 'http://test-redirect.com');
 
     // Mock workos.userManagement.getAuthorizationUrl
-    jest.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
+    vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
     await getAuthorizationUrl({});
 
@@ -39,7 +38,7 @@ describe('getAuthorizationUrl', () => {
   });
 
   it('works when called with no arguments', async () => {
-    jest.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
+    vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
     await getAuthorizationUrl(); // Call with no arguments
 
@@ -47,7 +46,7 @@ describe('getAuthorizationUrl', () => {
   });
 
   it('works when prompt is provided', async () => {
-    jest.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
+    vi.mocked(workos.userManagement.getAuthorizationUrl).mockReturnValue('mock-url');
 
     await getAuthorizationUrl({ prompt: 'consent' });
 

package/src/get-authorization-url.ts

@@ -4,16 +4,12 @@ import { GetAuthURLOptions } from './interfaces.js';
 import { headers } from 'next/headers';
 
 async function getAuthorizationUrl(options: GetAuthURLOptions = {}) {
-  const headersList = await headers();
-  const {
-    returnPathname,
-    screenHint,
-    organizationId,
-    redirectUri = headersList.get('x-redirect-uri'),
-    loginHint,
-    prompt,
-    state: customState,
-  } = options;
+  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;
+  }
 
   const internalState = returnPathname
     ? btoa(JSON.stringify({ returnPathname })).replace(/\+/g, '-').replace(/\//g, '_')

package/src/index.ts

@@ -1,6 +1,18 @@
 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';
+export {
+  applyResponseHeaders,
+  handleAuthkitHeaders,
+  partitionAuthkitHeaders,
+  isAuthkitRequestHeader,
+  AUTHKIT_REQUEST_HEADERS,
+  type AuthkitHeadersResult,
+  type AuthkitRedirectStatus,
+  type AuthkitRequestHeader,
+  type HandleAuthkitHeadersOptions,
+} from './middleware-helpers.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
 import { getWorkOS } from './workos.js';
@@ -8,17 +20,19 @@ import { getWorkOS } from './workos.js';
 export * from './interfaces.js';
 
 export {
+  AuthKitError,
+  TokenRefreshError,
   authkit,
   authkitMiddleware,
   getSignInUrl,
   getSignUpUrl,
+  getTokenClaims,
   getWorkOS,
   handleAuth,
   refreshSession,
   saveSession,
   signOut,
   switchToOrganization,
-  withAuth,
-  getTokenClaims,
   validateApiKey,
+  withAuth,
 };

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);
+}