@workos-inc/authkit-nextjs 2.12.1 → 2.13.0

package/dist/esm/types/index.d.ts

@@ -1,8 +1,10 @@
 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';
 export * from './interfaces.js';
-export { authkit, authkitMiddleware, getSignInUrl, getSignUpUrl, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, withAuth, getTokenClaims, validateApiKey, };
+export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, getSignInUrl, getSignUpUrl, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };

package/dist/esm/types/middleware-helpers.d.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from 'next/server';
+/** Internal AuthKit headers - forwarded to downstream requests but never sent to browser. */
+export declare const AUTHKIT_REQUEST_HEADERS: readonly ["x-workos-middleware", "x-url", "x-redirect-uri", "x-sign-up-paths", "x-workos-session"];
+export type AuthkitRequestHeader = (typeof AUTHKIT_REQUEST_HEADERS)[number];
+export declare function isAuthkitRequestHeader(name: string): boolean;
+export interface AuthkitHeadersResult {
+    requestHeaders: Headers;
+    responseHeaders: Headers;
+}
+/**
+ * Partitions AuthKit headers into request headers (for withAuth) and response headers (for browser).
+ */
+export declare function partitionAuthkitHeaders(request: NextRequest, authkitHeaders: Headers): AuthkitHeadersResult;
+export declare function applyResponseHeaders(response: NextResponse, responseHeaders: Headers): NextResponse;
+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 declare function handleAuthkitHeaders(request: NextRequest, authkitHeaders: Headers, options?: HandleAuthkitHeadersOptions): NextResponse;

package/dist/esm/types/session.d.ts

@@ -3,7 +3,7 @@ import { NextRequest } from 'next/server';
 import { AuthkitMiddlewareAuth, AuthkitOptions, AuthkitResponse, NoUserInfo, Session, UserInfo } from './interfaces.js';
 import type { AuthenticationResponse } from '@workos-inc/node';
 declare function encryptSession(session: Session): Promise<string>;
-declare function updateSessionMiddleware(request: NextRequest, debug: boolean, middlewareAuth: AuthkitMiddlewareAuth, redirectUri: string, signUpPaths: string[], eagerAuth?: boolean): Promise<Response>;
+declare function updateSessionMiddleware(request: NextRequest, debug: boolean, middlewareAuth: AuthkitMiddlewareAuth, redirectUri: string, signUpPaths: string[], eagerAuth?: boolean): Promise<import("next/server").NextResponse<unknown>>;
 declare function updateSession(request: NextRequest, options?: AuthkitOptions): Promise<AuthkitResponse>;
 declare function refreshSession(options: {
     organizationId?: string;

package/dist/esm/types/workos.d.ts

@@ -1,5 +1,5 @@
 import { WorkOS } from '@workos-inc/node';
-export declare const VERSION = "2.12.1";
+export declare const VERSION = "2.13.0";
 /**
  * Create a WorkOS instance with the provided API key and options.
  * If an instance already exists, it returns the existing instance.

package/dist/esm/utils.js

@@ -5,8 +5,6 @@ import { NextResponse } from 'next/server';
  */
 export function setCachePreventionHeaders(headers) {
     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');
 }
 export function redirectWithFallback(redirectUri, headers) {

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,yDAAyD,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,OAAiB;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAClE,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAExC,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,QAAQ;QAC3B,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC;QACjD,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAA8D;IACtG,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,IAAI;QACvB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE;YACtC,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAI,EAAW;IACjC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,MAAS,CAAC;IACd,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,EAAE,EAAE,CAAC;YACd,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,yDAAyD,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,OAAiB;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAClE,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAExC,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,QAAQ;QAC3B,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC;QACjD,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAA8D;IACtG,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,IAAI;QACvB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE;YACtC,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAI,EAAW;IACjC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,MAAS,CAAC;IACd,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,EAAE,EAAE,CAAC;YACd,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/workos.js

@@ -1,7 +1,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,
     https: WORKOS_API_HTTPS ? WORKOS_API_HTTPS === 'true' : true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos-inc/authkit-nextjs",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "description": "Authentication and session helpers for using WorkOS & AuthKit with Next.js",
   "sideEffects": false,
   "type": "module",
@@ -57,7 +57,7 @@
     "eslint-plugin-require-extensions": "^0.1.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "next": "^16.0.9",
+    "next": "^16.0.10",
     "prettier": "^3.3.3",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",

package/src/components/authkit-provider.spec.tsx

@@ -227,63 +227,59 @@ describe('AuthKitProvider', () => {
     });
   });
 
-  it('should reload the page when session is expired and no onSessionExpired handler is provided', async () => {
-    (checkSessionAction as jest.Mock).mockRejectedValueOnce(new Error('Failed to fetch'));
-
-    const originalLocation = window.location;
-
-    // @ts-expect-error - we're deleting the property to test the mock
-    delete window.location;
-
-    window.location = { ...window.location, reload: jest.fn() };
-
-    render(
-      <AuthKitProvider>
-        <div>Test Child</div>
-      </AuthKitProvider>,
-    );
-
-    act(() => {
-      // Simulate visibility change
-      window.dispatchEvent(new Event('visibilitychange'));
+  describe('window.location.reload behavior', () => {
+    let originalLocation: Location;
+
+    beforeEach(() => {
+      originalLocation = window.location;
+      // @ts-expect-error - deleting window.location to mock it
+      delete window.location;
+      window.location = { reload: jest.fn() } as unknown as Location;
     });
 
-    await waitFor(() => {
-      expect(window.location.reload).toHaveBeenCalled();
+    afterEach(() => {
+      window.location = originalLocation;
     });
 
-    // Restore original reload function
-    window.location = originalLocation;
-  });
+    it('should reload the page when session is expired and no onSessionExpired handler is provided', async () => {
+      (checkSessionAction as jest.Mock).mockRejectedValueOnce(new Error('Failed to fetch'));
 
-  it('should not call onSessionExpired or reload the page if session is valid', async () => {
-    (checkSessionAction as jest.Mock).mockResolvedValueOnce(true);
-    const onSessionExpired = jest.fn();
+      render(
+        <AuthKitProvider>
+          <div>Test Child</div>
+        </AuthKitProvider>,
+      );
 
-    const originalLocation = window.location;
+      act(() => {
+        // Simulate visibility change
+        window.dispatchEvent(new Event('visibilitychange'));
+      });
 
-    // @ts-expect-error - we're deleting the property to test the mock
-    delete window.location;
+      await waitFor(() => {
+        expect(window.location.reload).toHaveBeenCalled();
+      });
+    });
 
-    window.location = { ...window.location, reload: jest.fn() };
+    it('should not call onSessionExpired or reload the page if session is valid', async () => {
+      (checkSessionAction as jest.Mock).mockResolvedValueOnce(true);
+      const onSessionExpired = jest.fn();
 
-    render(
-      <AuthKitProvider onSessionExpired={onSessionExpired}>
-        <div>Test Child</div>
-      </AuthKitProvider>,
-    );
+      render(
+        <AuthKitProvider onSessionExpired={onSessionExpired}>
+          <div>Test Child</div>
+        </AuthKitProvider>,
+      );
 
-    act(() => {
-      // Simulate visibility change
-      window.dispatchEvent(new Event('visibilitychange'));
-    });
+      act(() => {
+        // Simulate visibility change
+        window.dispatchEvent(new Event('visibilitychange'));
+      });
 
-    await waitFor(() => {
-      expect(onSessionExpired).not.toHaveBeenCalled();
-      expect(window.location.reload).not.toHaveBeenCalled();
+      await waitFor(() => {
+        expect(onSessionExpired).not.toHaveBeenCalled();
+        expect(window.location.reload).not.toHaveBeenCalled();
+      });
     });
-
-    window.location = originalLocation;
   });
 });
 

package/src/components/min-max-button.spec.tsx

@@ -14,6 +14,7 @@ describe('MinMaxButton', () => {
   afterEach(() => {
     // Clean up after each test
     document.body.innerHTML = '';
+    jest.restoreAllMocks();
   });
 
   it('sets minimized value when clicked', () => {

package/src/cookie.spec.ts

@@ -147,11 +147,17 @@ describe('cookie.ts', () => {
   });
 
   describe('getJwtCookie', () => {
+    const originalEnv = process.env;
+
     beforeEach(() => {
-      // Reset NODE_ENV for each test
+      process.env = { ...originalEnv };
       delete process.env.NODE_ENV;
     });
 
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
     it('should create JWT cookie with Secure flag for HTTPS URLs', async () => {
       const { getJwtCookie } = await import('./cookie');
 

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.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,
 };