@workos-inc/authkit-nextjs 2.5.0 → 2.7.0

package/src/auth.spec.ts

@@ -0,0 +1,347 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+
+import { getSignInUrl, getSignUpUrl, signOut, switchToOrganization } from './auth.js';
+import * as session from './session.js';
+import * as cache from 'next/cache';
+import * as workosModule from './workos.js';
+
+// These are mocked in jest.setup.ts
+import { cookies, headers } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { generateSession, generateTestToken } from './test-helpers.js';
+import { sealData } from 'iron-session';
+import { getWorkOS } from './workos.js';
+
+const workos = getWorkOS();
+
+jest.mock('next/cache', () => {
+  const actual = jest.requireActual<typeof cache>('next/cache');
+  return {
+    ...actual,
+    revalidateTag: jest.fn(),
+    revalidatePath: jest.fn(),
+  };
+});
+
+// Create a fake WorkOS instance that will be used only in the "on error" tests
+const fakeWorkosInstance = {
+  userManagement: {
+    authenticateWithRefreshToken: jest.fn(),
+    getAuthorizationUrl: jest.fn(),
+    getJwksUrl: jest.fn(() => 'https://api.workos.com/sso/jwks/client_1234567890'),
+    getLogoutUrl: jest.fn(),
+  },
+};
+
+const revalidatePath = jest.mocked(cache.revalidatePath);
+const revalidateTag = jest.mocked(cache.revalidateTag);
+// We'll only use these in the "on error" tests
+const authenticateWithRefreshToken = fakeWorkosInstance.userManagement.authenticateWithRefreshToken;
+const getAuthorizationUrl = fakeWorkosInstance.userManagement.getAuthorizationUrl;
+
+jest.mock('../src/session', () => {
+  const actual = jest.requireActual<typeof session>('../src/session');
+
+  return {
+    ...actual,
+    refreshSession: jest.fn(actual.refreshSession),
+  };
+});
+
+describe('auth.ts', () => {
+  beforeEach(async () => {
+    // Clear all mocks between tests
+    jest.clearAllMocks();
+
+    // Reset the cookie store
+    const nextCookies = await cookies();
+    // @ts-expect-error - _reset is part of the mock
+    nextCookies._reset();
+
+    const nextHeaders = await headers();
+    // @ts-expect-error - _reset is part of the mock
+    nextHeaders._reset();
+  });
+
+  describe('getSignInUrl', () => {
+    it('should return a valid URL', async () => {
+      const url = await getSignInUrl();
+      expect(url).toBeDefined();
+      expect(() => new URL(url)).not.toThrow();
+    });
+
+    it('should use the organizationId if provided', async () => {
+      const url = await getSignInUrl({ organizationId: 'org_123' });
+      expect(url).toContain('organization_id=org_123');
+      expect(url).toBeDefined();
+      expect(() => new URL(url)).not.toThrow();
+    });
+  });
+
+  it('should not include prompt when not specified for getSignInUrl', async () => {
+    const url = await getSignInUrl();
+    expect(url).not.toContain('prompt=');
+  });
+
+  it('should include prompt=consent when explicitly specified for getSignInUrl', async () => {
+    const url = await getSignInUrl({ prompt: 'consent' });
+    expect(url).toContain('prompt=consent');
+  });
+
+  describe('getSignUpUrl', () => {
+    it('should return a valid URL', async () => {
+      const url = await getSignUpUrl();
+      expect(url).toBeDefined();
+      expect(() => new URL(url)).not.toThrow();
+    });
+    it('should not include prompt when not specified for getSignUpUrl', async () => {
+      const url = await getSignUpUrl();
+      expect(url).not.toContain('prompt=');
+    });
+
+    it('should include prompt=consent when explicitly specified for getSignUpUrl', async () => {
+      const url = await getSignUpUrl({ prompt: 'consent' });
+      expect(url).toContain('prompt=consent');
+    });
+  });
+
+  describe('switchToOrganization', () => {
+    it('should refresh the session with the new organizationId', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('x-url', 'http://localhost/test');
+      await switchToOrganization('org_123');
+      expect(revalidatePath).toHaveBeenCalledWith('http://localhost/test');
+    });
+
+    it('should revalidate the path and refresh the session with the new organizationId', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('x-url', 'http://localhost/test');
+      await switchToOrganization('org_123', { returnTo: '/test' });
+      expect(session.refreshSession).toHaveBeenCalledTimes(1);
+      expect(session.refreshSession).toHaveBeenCalledWith({ organizationId: 'org_123', ensureSignedIn: true });
+      expect(revalidatePath).toHaveBeenCalledWith('/test');
+    });
+
+    it('should revalidate the provided tags and refresh the session with the new organizationId', async () => {
+      const nextHeaders = await headers();
+      nextHeaders.set('x-url', 'http://localhost/test');
+      await switchToOrganization('org_123', { revalidationStrategy: 'tag', revalidationTags: ['tag1', 'tag2'] });
+      expect(revalidateTag).toHaveBeenCalledTimes(2);
+    });
+
+    describe('on error', () => {
+      beforeEach(async () => {
+        const nextHeaders = await headers();
+        nextHeaders.set('x-url', 'http://localhost/test');
+        await generateSession();
+
+        // Create a WorkOS-like object that matches what our tests need
+        const mockWorkOS = {
+          userManagement: fakeWorkosInstance.userManagement,
+          // Add minimal properties to satisfy TypeScript
+          createHttpClient: jest.fn(),
+          createWebhookClient: jest.fn(),
+          createActionsClient: jest.fn(),
+          createIronSessionProvider: jest.fn(),
+          apiKey: 'test',
+          clientId: 'test',
+          host: 'test',
+          port: 443,
+          protocol: 'https',
+          headers: {},
+          version: '0.0.0',
+        };
+
+        // Apply the mock for these tests only
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        jest.spyOn(workosModule, 'getWorkOS').mockImplementation(() => mockWorkOS as any);
+      });
+
+      afterEach(() => {
+        // Restore all mocks after each test
+        jest.restoreAllMocks();
+      });
+
+      it('should redirect to sign in when error is "sso_required"', async () => {
+        authenticateWithRefreshToken.mockImplementation(() => {
+          return Promise.reject({
+            status: 500,
+            requestID: 'sso_required',
+            error: 'sso_required',
+            errorDescription: 'User must authenticate using one of the matching connections.',
+          });
+        });
+
+        await switchToOrganization('org_123');
+        expect(getAuthorizationUrl).toHaveBeenCalledWith(expect.objectContaining({ organizationId: 'org_123' }));
+        expect(redirect).toHaveBeenCalledTimes(1);
+      });
+
+      it('should redirect to sign in when error is "mfa_enrollment"', async () => {
+        authenticateWithRefreshToken.mockImplementation(() => {
+          return Promise.reject({
+            status: 500,
+            requestID: 'mfa_enrollment',
+            error: 'mfa_enrollment',
+            errorDescription: 'User must authenticate using one of the matching connections.',
+          });
+        });
+
+        await switchToOrganization('org_123');
+        expect(getAuthorizationUrl).toHaveBeenCalledWith(expect.objectContaining({ organizationId: 'org_123' }));
+        expect(redirect).toHaveBeenCalledTimes(1);
+      });
+
+      it('should redirect to the authkit_redirect_url when provided', async () => {
+        authenticateWithRefreshToken.mockImplementation(() => {
+          return Promise.reject({
+            rawData: {
+              authkit_redirect_url: 'http://localhost/test',
+            },
+          });
+        });
+        await switchToOrganization('org_123');
+        expect(redirect).toHaveBeenCalledWith('http://localhost/test');
+      });
+
+      it('throws other errors', async () => {
+        authenticateWithRefreshToken.mockImplementation(() => {
+          return Promise.reject(new Error('Fail'));
+        });
+        await expect(switchToOrganization('org_123')).rejects.toThrow('Fail');
+      });
+    });
+  });
+
+  describe('signOut', () => {
+    it('should delete the cookie and redirect', async () => {
+      const nextCookies = await cookies();
+      const nextHeaders = await headers();
+
+      nextHeaders.set('x-workos-middleware', 'true');
+      nextCookies.set('wos-session', 'foo');
+
+      await signOut();
+
+      const sessionCookie = nextCookies.get('wos-session');
+
+      expect(sessionCookie).toBeUndefined();
+      expect(redirect).toHaveBeenCalledTimes(1);
+      expect(redirect).toHaveBeenCalledWith('/');
+    });
+
+    it('should delete the cookie with a specific domain', async () => {
+      const nextCookies = await cookies();
+      const nextHeaders = await headers();
+
+      nextHeaders.set('x-workos-middleware', 'true');
+      nextCookies.set('wos-session', 'foo', { domain: 'example.com' });
+
+      await signOut();
+
+      const sessionCookie = nextCookies.get('wos-session');
+      expect(sessionCookie).toBeUndefined();
+    });
+
+    describe('when given a `returnTo` parameter', () => {
+      it('passes the `returnTo` through to the `getLogoutUrl` call', async () => {
+        jest
+          .spyOn(workos.userManagement, 'getLogoutUrl')
+          .mockReturnValue('https://user-management-logout.com/signed-out');
+        const mockSession = {
+          accessToken: await generateTestToken(),
+          sessionId: 'session_123',
+        } as const;
+
+        const nextHeaders = await headers();
+        nextHeaders.set(
+          'x-workos-session',
+          await sealData(mockSession, { password: process.env.WORKOS_COOKIE_PASSWORD as string }),
+        );
+
+        nextHeaders.set('x-workos-middleware', 'true');
+
+        await signOut({ returnTo: 'https://example.com/signed-out' });
+
+        expect(redirect).toHaveBeenCalledTimes(1);
+        expect(redirect).toHaveBeenCalledWith('https://user-management-logout.com/signed-out');
+        expect(workos.userManagement.getLogoutUrl).toHaveBeenCalledWith(
+          expect.objectContaining({
+            returnTo: 'https://example.com/signed-out',
+          }),
+        );
+      });
+
+      describe('when there is no session', () => {
+        it('returns to the `returnTo`', async () => {
+          const nextHeaders = await headers();
+
+          nextHeaders.set('x-workos-middleware', 'true');
+
+          await signOut({ returnTo: 'https://example.com/signed-out' });
+
+          expect(redirect).toHaveBeenCalledTimes(1);
+          expect(redirect).toHaveBeenCalledWith('https://example.com/signed-out');
+        });
+      });
+    });
+
+    describe('when called outside of middleware', () => {
+      it('should fall back to reading session from cookie and redirect to logout URL', async () => {
+        const nextCookies = await cookies();
+
+        // Don't set x-workos-middleware header to simulate being outside middleware
+        // This will cause withAuth to throw
+
+        // Set up a session cookie with a valid access token
+        const mockSession = {
+          accessToken: await generateTestToken(),
+          refreshToken: 'refresh_token',
+          user: { id: 'user_123' },
+        };
+
+        const encryptedSession = await sealData(mockSession, {
+          password: process.env.WORKOS_COOKIE_PASSWORD as string,
+        });
+
+        nextCookies.set('wos-session', encryptedSession);
+
+        jest
+          .spyOn(workos.userManagement, 'getLogoutUrl')
+          .mockReturnValue('https://api.workos.com/user_management/sessions/logout?session_id=session_123');
+
+        await signOut();
+
+        // Cookie should be deleted
+        const sessionCookie = nextCookies.get('wos-session');
+        expect(sessionCookie).toBeUndefined();
+
+        // Should redirect to WorkOS logout URL with session ID
+        expect(redirect).toHaveBeenCalledTimes(1);
+        expect(redirect).toHaveBeenCalledWith(
+          'https://api.workos.com/user_management/sessions/logout?session_id=session_123',
+        );
+        expect(workos.userManagement.getLogoutUrl).toHaveBeenCalledWith(
+          expect.objectContaining({
+            sessionId: expect.stringMatching(/^session_/),
+          }),
+        );
+      });
+
+      it('should throw the original error when no session cookie exists outside middleware', async () => {
+        const nextCookies = await cookies();
+
+        // Don't set x-workos-middleware header to simulate being outside middleware
+        // Set a cookie to verify it gets deleted
+        nextCookies.set('wos-session', 'dummy-value');
+
+        // Should throw the error from withAuth since we can't recover
+        await expect(signOut()).rejects.toThrow(/You are calling 'withAuth'/);
+
+        // Cookie should still be deleted even though it throws
+        const sessionCookie = nextCookies.get('wos-session');
+        expect(sessionCookie).toBeUndefined();
+      });
+    });
+  });
+});

package/src/auth.ts

@@ -1,28 +1,31 @@
 'use server';
 
+import { decodeJwt } from 'jose';
 import { revalidatePath, revalidateTag } from 'next/cache';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { WORKOS_COOKIE_NAME } from './env-variables.js';
 import { getCookieOptions } from './cookie.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
-import { SwitchToOrganizationOptions, UserInfo } from './interfaces.js';
-import { refreshSession, withAuth } from './session.js';
+import type { AccessToken, SwitchToOrganizationOptions, UserInfo } from './interfaces.js';
+import { getSessionFromCookie, refreshSession, withAuth } from './session.js';
 import { getWorkOS } from './workos.js';
 export async function getSignInUrl({
   organizationId,
   loginHint,
   redirectUri,
-}: { organizationId?: string; loginHint?: string; redirectUri?: string } = {}) {
-  return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri });
+  prompt,
+}: { organizationId?: string; loginHint?: string; redirectUri?: string; prompt?: 'consent' } = {}) {
+  return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri, prompt });
 }
 
 export async function getSignUpUrl({
   organizationId,
   loginHint,
   redirectUri,
-}: { organizationId?: string; loginHint?: string; redirectUri?: string } = {}) {
-  return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri });
+  prompt,
+}: { organizationId?: string; loginHint?: string; redirectUri?: string; prompt?: 'consent' } = {}) {
+  return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri, prompt });
 }
 
 /**
@@ -36,6 +39,16 @@ export async function signOut({ returnTo }: { returnTo?: string } = {}) {
   try {
     const { sessionId: sid } = await withAuth();
     sessionId = sid;
+  } catch (error) {
+    // Fall back to reading session directly from cookie when middleware isn't available
+    const session = await getSessionFromCookie();
+    if (session && session.accessToken) {
+      const { sid } = decodeJwt<AccessToken>(session.accessToken);
+      sessionId = sid;
+    } else {
+      // can't recover - throw the original error.
+      throw error;
+    }
   } finally {
     const nextCookies = await cookies();
     const cookieName = WORKOS_COOKIE_NAME || 'wos-session';

package/src/authkit-callback-route.spec.ts

@@ -0,0 +1,258 @@
+import { getWorkOS } from './workos.js';
+import { handleAuth } from './authkit-callback-route.js';
+import { NextRequest, NextResponse } from 'next/server';
+
+// Mocked in jest.setup.ts
+import { cookies, headers } from 'next/headers';
+
+// Mock dependencies
+const fakeWorkosInstance = {
+  userManagement: {
+    authenticateWithCode: jest.fn(),
+    getJwksUrl: jest.fn(() => 'https://api.workos.com/sso/jwks/client_1234567890'),
+  },
+};
+
+jest.mock('../src/workos', () => ({
+  getWorkOS: jest.fn(() => fakeWorkosInstance),
+}));
+
+describe('authkit-callback-route', () => {
+  const workos = getWorkOS();
+  const mockAuthResponse = {
+    accessToken: 'access123',
+    refreshToken: 'refresh123',
+    user: {
+      id: 'user_123',
+      email: 'test@example.com',
+      emailVerified: true,
+      profilePictureUrl: 'https://example.com/photo.jpg',
+      firstName: 'Test',
+      lastName: 'User',
+      object: 'user' as const,
+      createdAt: '2024-01-01T00:00:00Z',
+      updatedAt: '2024-01-01T00:00:00Z',
+      lastSignInAt: '2024-01-01T00:00:00Z',
+      externalId: null,
+      metadata: {},
+    },
+    oauthTokens: {
+      accessToken: 'access123',
+      refreshToken: 'refresh123',
+      expiresAt: 1719811200,
+      scopes: ['foo', 'bar'],
+    },
+  };
+
+  describe('handleAuth', () => {
+    let request: NextRequest;
+
+    beforeAll(() => {
+      // Silence console.error during tests
+      jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    beforeEach(async () => {
+      // Reset all mocks
+      jest.clearAllMocks();
+
+      // Create a new request with searchParams
+      request = new NextRequest(new URL('http://example.com/callback'));
+
+      // Reset the cookie store
+      const nextCookies = await cookies();
+      // @ts-expect-error - _reset is part of the mock
+      nextCookies._reset();
+
+      const nextHeaders = await headers();
+      // @ts-expect-error - _reset is part of the mock
+      nextHeaders._reset();
+    });
+
+    it('should handle successful authentication', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Set up request with code
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(workos.userManagement.authenticateWithCode).toHaveBeenCalledWith({
+        clientId: process.env.WORKOS_CLIENT_ID,
+        code: 'test-code',
+      });
+      expect(response).toBeInstanceOf(NextResponse);
+    });
+
+    it('should handle authentication failure', async () => {
+      // Mock authentication failure
+      (workos.userManagement.authenticateWithCode as jest.Mock).mockRejectedValue(new Error('Auth failed'));
+
+      request.nextUrl.searchParams.set('code', 'invalid-code');
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.status).toBe(500);
+      const data = await response.json();
+      expect(data.error.message).toBe('Something went wrong');
+    });
+
+    it('should handle authentication failure if a non-Error object is thrown', async () => {
+      // Mock authentication failure
+      jest.mocked(workos.userManagement.authenticateWithCode).mockRejectedValue('Auth failed');
+
+      request.nextUrl.searchParams.set('code', 'invalid-code');
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.status).toBe(500);
+      const data = await response.json();
+      expect(data.error.message).toBe('Something went wrong');
+    });
+
+    it('should handle authentication failure with custom onError handler', async () => {
+      // Mock authentication failure
+      jest.mocked(workos.userManagement.authenticateWithCode).mockRejectedValue('Auth failed');
+      request.nextUrl.searchParams.set('code', 'invalid-code');
+
+      const handler = handleAuth({
+        onError: () => {
+          return new Response(JSON.stringify({ error: { message: 'Custom error' } }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        },
+      });
+      const response = await handler(request);
+
+      expect(response.status).toBe(500);
+      const data = await response.json();
+      expect(data.error.message).toBe('Custom error');
+    });
+
+    it('should handle missing code parameter', async () => {
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.status).toBe(500);
+      const data = await response.json();
+      expect(data.error.message).toBe('Something went wrong');
+    });
+
+    it('should respect custom returnPathname', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const handler = handleAuth({ returnPathname: '/dashboard' });
+      const response = await handler(request);
+
+      expect(response.headers.get('Location')).toContain('/dashboard');
+    });
+
+    it('should handle state parameter with returnPathname', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      const state = btoa(JSON.stringify({ returnPathname: '/custom-path' }));
+      request.nextUrl.searchParams.set('code', 'test-code');
+      request.nextUrl.searchParams.set('state', state);
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.headers.get('Location')).toContain('/custom-path');
+    });
+
+    it('should extract custom search params from returnPathname', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      const state = btoa(JSON.stringify({ returnPathname: '/custom-path?foo=bar&baz=qux' }));
+      request.nextUrl.searchParams.set('code', 'test-code');
+      request.nextUrl.searchParams.set('state', state);
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.headers.get('Location')).toContain('/custom-path?foo=bar&baz=qux');
+    });
+
+    it('should use Response if NextResponse.redirect is not available', async () => {
+      const originalRedirect = NextResponse.redirect;
+      (NextResponse as Partial<typeof NextResponse>).redirect = undefined;
+
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Set up request with code
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response).toBeInstanceOf(Response);
+
+      // Restore the original redirect method
+      (NextResponse as Partial<typeof NextResponse>).redirect = originalRedirect;
+    });
+
+    it('should use Response if NextResponse.json is not available', async () => {
+      const originalJson = NextResponse.json;
+      (NextResponse as Partial<typeof NextResponse>).json = undefined;
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response).toBeInstanceOf(Response);
+
+      // Restore the original json method
+      (NextResponse as Partial<typeof NextResponse>).json = originalJson;
+    });
+
+    it('should throw an error if baseURL is provided but invalid', async () => {
+      expect(() => handleAuth({ baseURL: 'invalid-url' })).toThrow('Invalid baseURL: invalid-url');
+    });
+
+    it('should use baseURL if provided', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Set up request with code
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const handler = handleAuth({ baseURL: 'https://base.com' });
+      const response = await handler(request);
+
+      expect(response.headers.get('Location')).toContain('https://base.com');
+    });
+
+    it('should throw an error if response is missing tokens', async () => {
+      const mockAuthResponse = {
+        user: { id: 'user_123' },
+      };
+
+      (workos.userManagement.authenticateWithCode as jest.Mock).mockResolvedValue(mockAuthResponse);
+
+      // Set up request with code
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      expect(response.status).toBe(500);
+    });
+
+    it('should call onSuccess if provided', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Set up request with code
+      request.nextUrl.searchParams.set('code', 'test-code');
+
+      const onSuccess = jest.fn();
+      const handler = handleAuth({ onSuccess: onSuccess });
+      await handler(request);
+
+      expect(onSuccess).toHaveBeenCalledWith(mockAuthResponse);
+    });
+  });
+});