@workos-inc/authkit-nextjs 2.17.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos-inc/authkit-nextjs",
-  "version": "2.17.0",
+  "version": "3.0.0",
   "description": "Authentication and session helpers for using WorkOS & AuthKit with Next.js",
   "sideEffects": false,
   "type": "module",
@@ -26,7 +26,8 @@
     "@workos-inc/node": "^8.9.0",
     "iron-session": "^8.0.4",
     "jose": "^5.10.0",
-    "path-to-regexp": "^6.3.0"
+    "path-to-regexp": "^6.3.0",
+    "valibot": "^1.2.0"
   },
   "peerDependencies": {
     "next": "^13.5.9 || ^14.2.26 || ^15.2.3 || ^16",
@@ -40,14 +41,12 @@
     "@types/react": "18.2.67",
     "@types/react-dom": "18.2.22",
     "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.1.2",
-    "eslint-plugin-require-extensions": "^0.1.3",
     "jsdom": "^26.1.0",
-    "next": "^16.1.6",
-    "prettier": "^3.8.1",
+    "next": "^16.2.1",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
     "tslib": "^2.8.1",
-    "typescript": "5.4.2",
+    "typescript": "6.0.2",
     "typescript-eslint": "^7.18.0",
     "vitest": "^3.2.4"
   },
@@ -63,13 +62,13 @@
   "scripts": {
     "clean": "rm -rf dist",
     "prebuild": "pnpm run clean",
-    "build": "tsc --project tsconfig.json",
-    "lint": "eslint \"src/**/*.ts*\"",
+    "build": "tsc --project tsconfig.app.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "prettier": "prettier \"src/**/*.{js,ts,tsx}\" --check",
-    "format": "prettier \"src/**/*.{js,ts,tsx}\" --write",
-    "typecheck": "tsc --project tsconfig.json --noEmit"
+    "lint": "oxlint",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "typecheck": "tsc --project tsconfig.app.json --noEmit && tsc --project tsconfig.test.json --noEmit"
   }
 }

package/src/actions.spec.ts

@@ -11,6 +11,7 @@ import {
 import { signOut, switchToOrganization } from './auth.js';
 import { getWorkOS } from '../src/workos.js';
 import { withAuth, refreshSession } from '../src/session.js';
+import { getAuthorizationUrl } from '../src/get-authorization-url.js';
 
 vi.mock('../src/auth.js', () => ({
   signOut: vi.fn().mockResolvedValue(true),
@@ -30,11 +31,31 @@ vi.mock('../src/workos.js', () => ({
 
 vi.mock('../src/session.js', () => ({
   withAuth: vi.fn().mockResolvedValue({ user: 'testUser', accessToken: 'access_token' }),
-  refreshSession: vi.fn().mockResolvedValue({ session: 'newSession', accessToken: 'refreshed_token' }),
+  refreshSession: vi.fn().mockResolvedValue({ user: 'testUser', accessToken: 'refreshed_token' }),
+}));
+
+vi.mock('../src/get-authorization-url.js', () => ({
+  getAuthorizationUrl: vi.fn().mockResolvedValue('https://api.workos.com/authorize?...'),
 }));
 
 describe('actions', () => {
   const workos = getWorkOS();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Restore default mock implementations
+    vi.mocked(withAuth).mockResolvedValue({
+      user: 'testUser' as never,
+      sessionId: 'session_123',
+      accessToken: 'access_token',
+    });
+    vi.mocked(refreshSession).mockResolvedValue({
+      user: 'testUser' as never,
+      sessionId: 'session_123',
+      accessToken: 'refreshed_token',
+    });
+  });
+
   describe('checkSessionAction', () => {
     it('should return true for authenticated users', async () => {
       const result = await checkSessionAction();
@@ -62,16 +83,52 @@ describe('actions', () => {
     it('should return auth details', async () => {
       const result = await getAuthAction();
       expect(withAuth).toHaveBeenCalled();
-      expect(result).toEqual({ user: 'testUser' });
+      expect(result).toEqual({ user: 'testUser', sessionId: 'session_123' });
+    });
+
+    it('should not pass ensureSignedIn to withAuth', async () => {
+      await getAuthAction({ ensureSignedIn: true });
+      expect(withAuth).toHaveBeenCalledWith();
+    });
+
+    it('should return signInUrl when ensureSignedIn is true and no user', async () => {
+      vi.mocked(withAuth).mockResolvedValueOnce({ user: null });
+      const result = await getAuthAction({ ensureSignedIn: true });
+      expect(getAuthorizationUrl).toHaveBeenCalledWith({ screenHint: 'sign-in' });
+      expect(result).toEqual({ user: null, signInUrl: 'https://api.workos.com/authorize?...' });
+    });
+
+    it('should not return signInUrl when ensureSignedIn is true and user exists', async () => {
+      const result = await getAuthAction({ ensureSignedIn: true });
+      expect(getAuthorizationUrl).not.toHaveBeenCalled();
+      expect(result).toEqual({ user: 'testUser', sessionId: 'session_123' });
     });
   });
 
   describe('refreshAuthAction', () => {
     it('should refresh session', async () => {
-      const params = { ensureSignedIn: true, organizationId: 'org_123' };
+      const params = { ensureSignedIn: false, organizationId: 'org_123' };
       const result = await refreshAuthAction(params);
-      expect(refreshSession).toHaveBeenCalledWith(params);
-      expect(result).toEqual({ session: 'newSession' });
+      expect(refreshSession).toHaveBeenCalledWith({ organizationId: 'org_123' });
+      expect(result).toEqual({ user: 'testUser', sessionId: 'session_123' });
+    });
+
+    it('should not pass ensureSignedIn to refreshSession', async () => {
+      await refreshAuthAction({ ensureSignedIn: true, organizationId: 'org_123' });
+      expect(refreshSession).toHaveBeenCalledWith({ organizationId: 'org_123' });
+    });
+
+    it('should return signInUrl when ensureSignedIn is true and no user', async () => {
+      vi.mocked(refreshSession).mockResolvedValueOnce({ user: null });
+      const result = await refreshAuthAction({ ensureSignedIn: true });
+      expect(getAuthorizationUrl).toHaveBeenCalledWith({ screenHint: 'sign-in' });
+      expect(result).toEqual({ user: null, signInUrl: 'https://api.workos.com/authorize?...' });
+    });
+
+    it('should not return signInUrl when ensureSignedIn is true and user exists', async () => {
+      const result = await refreshAuthAction({ ensureSignedIn: true });
+      expect(getAuthorizationUrl).not.toHaveBeenCalled();
+      expect(result).toEqual({ user: 'testUser', sessionId: 'session_123' });
     });
   });
 
@@ -96,7 +153,25 @@ describe('actions', () => {
     it('should refresh access token', async () => {
       const result = await refreshAccessTokenAction();
       expect(refreshSession).toHaveBeenCalled();
-      expect(result).toEqual('refreshed_token');
+      expect(result).toEqual({ accessToken: 'refreshed_token' });
+    });
+
+    it('should catch errors and return a generic error instead of throwing', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      vi.mocked(refreshSession).mockRejectedValueOnce(new Error('Rate limit exceeded'));
+      const result = await refreshAccessTokenAction();
+      expect(result).toEqual({ accessToken: undefined, error: 'Failed to refresh access token' });
+      expect(warnSpy).toHaveBeenCalledWith('Failed to refresh access token:', 'Rate limit exceeded');
+      warnSpy.mockRestore();
+    });
+
+    it('should handle non-Error objects in catch', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      vi.mocked(refreshSession).mockRejectedValueOnce('string error');
+      const result = await refreshAccessTokenAction();
+      expect(result).toEqual({ accessToken: undefined, error: 'Failed to refresh access token' });
+      expect(warnSpy).toHaveBeenCalledWith('Failed to refresh access token:', 'string error');
+      warnSpy.mockRestore();
     });
   });
 });

package/src/actions.ts

@@ -3,8 +3,14 @@
 import { signOut, switchToOrganization } from './auth.js';
 import { NoUserInfo, UserInfo, SwitchToOrganizationOptions } from './interfaces.js';
 import { refreshSession, withAuth } from './session.js';
+import { getAuthorizationUrl } from './get-authorization-url.js';
 import { getWorkOS } from './workos.js';
 
+export interface RefreshAccessTokenActionResult {
+  accessToken: string | undefined;
+  error?: string;
+}
+
 /**
  * This function is used to sanitize the auth object.
  * Remove the accessToken from the auth object as it is not needed on the client side.
@@ -35,7 +41,19 @@ export const getOrganizationAction = async (organizationId: string) => {
 };
 
 export const getAuthAction = async (options?: { ensureSignedIn?: boolean }) => {
-  return sanitize(await withAuth(options));
+  // Never pass ensureSignedIn to withAuth from a server action, because withAuth
+  // would call redirect() to an external URL, which causes CORS errors when
+  // invoked via a client-side fetch. Instead, return the sign-in URL so the
+  // client can redirect via window.location.href.
+  const auth = await withAuth();
+  const sanitized = sanitize(auth);
+
+  if (options?.ensureSignedIn && !auth.user) {
+    const signInUrl = await getAuthorizationUrl({ screenHint: 'sign-in' });
+    return { ...sanitized, signInUrl };
+  }
+
+  return sanitized;
 };
 
 export const refreshAuthAction = async ({
@@ -45,7 +63,17 @@ export const refreshAuthAction = async ({
   ensureSignedIn?: boolean;
   organizationId?: string;
 }) => {
-  return sanitize(await refreshSession({ ensureSignedIn, organizationId }));
+  // Never pass ensureSignedIn to refreshSession from a server action for the
+  // same CORS reason as getAuthAction above.
+  const auth = await refreshSession({ organizationId });
+  const sanitized = sanitize(auth);
+
+  if (ensureSignedIn && !auth.user) {
+    const signInUrl = await getAuthorizationUrl({ screenHint: 'sign-in' });
+    return { ...sanitized, signInUrl };
+  }
+
+  return sanitized;
 };
 
 export const switchToOrganizationAction = async (organizationId: string, options?: SwitchToOrganizationOptions) => {
@@ -64,8 +92,19 @@ export async function getAccessTokenAction() {
 /**
  * This action is used to refresh the access token from the auth object.
  * It is used to fetch the access token from the server.
+ *
+ * Errors are caught and returned as data rather than thrown, to prevent
+ * Next.js from returning 500 responses for server action failures.
  */
-export async function refreshAccessTokenAction() {
-  const auth = await refreshSession();
-  return auth.accessToken;
+export async function refreshAccessTokenAction(): Promise<RefreshAccessTokenActionResult> {
+  try {
+    const auth = await refreshSession();
+    return { accessToken: auth.accessToken };
+  } catch (error) {
+    console.warn('Failed to refresh access token:', error instanceof Error ? error.message : String(error));
+    return {
+      accessToken: undefined,
+      error: 'Failed to refresh access token',
+    };
+  }
 }

package/src/auth.spec.ts

@@ -9,6 +9,7 @@ import { redirect } from 'next/navigation';
 import { generateSession, generateTestToken } from './test-helpers.js';
 import { sealData } from 'iron-session';
 import { getWorkOS } from './workos.js';
+import { getStateFromPKCECookieValue } from './pkce.js';
 
 const workos = getWorkOS();
 
@@ -87,7 +88,7 @@ describe('auth.ts', () => {
       const parsedUrl = new URL(url);
       const state = parsedUrl.searchParams.get('state');
       expect(state).toBeDefined();
-      const decoded = JSON.parse(atob(state!.replace(/-/g, '+').replace(/_/g, '/')));
+      const decoded = await getStateFromPKCECookieValue(state!);
       expect(decoded.returnPathname).toBe('/dashboard');
     });
   });
@@ -123,7 +124,7 @@ describe('auth.ts', () => {
       const parsedUrl = new URL(url);
       const state = parsedUrl.searchParams.get('state');
       expect(state).toBeDefined();
-      const decoded = JSON.parse(atob(state!.replace(/-/g, '+').replace(/_/g, '/')));
+      const decoded = await getStateFromPKCECookieValue(state!);
       expect(decoded.returnPathname).toBe('/welcome');
     });
   });

package/src/auth.ts

@@ -22,60 +22,29 @@ function revalidateTagCompat(tag: string): void {
 }
 
 async function getAuthURLAndSetPKCECookie(options: GetAuthURLOptions): Promise<string> {
-  const { url, pkceCookieValue } = await getAuthorizationUrl(options);
-  await setPKCECookie(pkceCookieValue);
+  const { url, sealedState } = await getAuthorizationUrl(options);
+  await setPKCECookie(sealedState);
+
   return url;
 }
 
-export async function getSignInUrl({
-  organizationId,
-  loginHint,
-  redirectUri,
-  prompt,
-  state,
-  returnTo,
-}: {
-  organizationId?: string;
-  loginHint?: string;
-  redirectUri?: string;
-  prompt?: 'consent';
-  state?: string;
+type GetSignUrlOptions = Omit<GetAuthURLOptions, 'screenHint' | 'returnPathname'> & {
   returnTo?: string;
-} = {}) {
+};
+
+export async function getSignInUrl(authUrlOptions: GetSignUrlOptions = {}) {
   return getAuthURLAndSetPKCECookie({
-    organizationId,
+    ...authUrlOptions,
+    returnPathname: authUrlOptions.returnTo,
     screenHint: 'sign-in',
-    loginHint,
-    redirectUri,
-    prompt,
-    state,
-    returnPathname: returnTo,
   });
 }
 
-export async function getSignUpUrl({
-  organizationId,
-  loginHint,
-  redirectUri,
-  prompt,
-  state,
-  returnTo,
-}: {
-  organizationId?: string;
-  loginHint?: string;
-  redirectUri?: string;
-  prompt?: 'consent';
-  state?: string;
-  returnTo?: string;
-} = {}) {
+export async function getSignUpUrl(authUrlOptions: GetSignUrlOptions = {}) {
   return getAuthURLAndSetPKCECookie({
-    organizationId,
+    ...authUrlOptions,
+    returnPathname: authUrlOptions.returnTo,
     screenHint: 'sign-up',
-    loginHint,
-    redirectUri,
-    prompt,
-    state,
-    returnPathname: returnTo,
   });
 }