@workos-inc/authkit-nextjs 3.0.0-beta.1 → 3.0.1

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

@@ -0,0 +1,27 @@
+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 handleAuthkitProxy(request: NextRequest, authkitHeaders: Headers, options?: HandleAuthkitHeadersOptions): NextResponse;
+/** @deprecated Use `handleAuthkitProxy` instead. */
+export declare const handleAuthkitHeaders: typeof handleAuthkitProxy;

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

@@ -1,4 +1,6 @@
 import { NextMiddleware, NextRequest } from 'next/server';
 import { AuthkitMiddlewareOptions, AuthkitOptions, AuthkitResponse } from './interfaces.js';
-export declare function authkitMiddleware({ debug, middlewareAuth, redirectUri, signUpPaths, eagerAuth, }?: AuthkitMiddlewareOptions): NextMiddleware;
+export declare function authkitProxy({ debug, middlewareAuth, redirectUri, signUpPaths, eagerAuth, }?: AuthkitMiddlewareOptions): NextMiddleware;
+/** @deprecated Use `authkitProxy` instead. */
+export declare const authkitMiddleware: typeof authkitProxy;
 export declare function authkit(request: NextRequest, options?: AuthkitOptions): Promise<AuthkitResponse>;

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

@@ -0,0 +1,17 @@
+import { State } from './interfaces.js';
+export declare const PKCE_COOKIE_NAME = "wos-auth-verifier";
+/**
+ * Derive a flow-specific cookie name so concurrent auth flows don't overwrite
+ * each other's PKCE cookies. Uses an FNV-1a hash of the full sealed state
+ */
+export declare function getPKCECookieNameForState(state: string): string;
+/**
+ * Set the PKCE verifier cookie in server action context.
+ * In middleware context, callers must set the cookie via Set-Cookie headers instead.
+ */
+export declare function setPKCECookie(sealedState: string): Promise<void>;
+/**
+ * Read and unseal the auth cookie containing PKCE code verifier and OAuth state.
+ * Throws if the cookie is not in the required state
+ */
+export declare function getStateFromPKCECookieValue(cookieValue: string): Promise<State>;

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.js").NextResponse<unknown>>;
 declare function updateSession(request: NextRequest, options?: AuthkitOptions): Promise<AuthkitResponse>;
 declare function refreshSession(options: {
     organizationId?: string;

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

@@ -1,3 +1,8 @@
+/**
+ * Sets cache prevention headers to prevent CDN/proxy caching.
+ * @param headers - The Headers object to set the cache prevention headers on.
+ */
+export declare function setCachePreventionHeaders(headers: Headers): void;
 export declare function redirectWithFallback(redirectUri: string, headers?: Headers): Response;
 export declare function errorResponseWithFallback(errorBody: {
     error: {

package/dist/esm/types/validate-api-key.d.ts

@@ -0,0 +1 @@
+export declare function validateApiKey(): Promise<import("@workos-inc/node").ValidateApiKeyResponse>;

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

@@ -1,5 +1,5 @@
 import { WorkOS } from '@workos-inc/node';
-export declare const VERSION = "2.10.0";
+export declare const VERSION = "2.14.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

@@ -1,17 +1,25 @@
 import { NextResponse } from 'next/server';
+/**
+ * Sets cache prevention headers to prevent CDN/proxy caching.
+ * @param headers - The Headers object to set the cache prevention headers on.
+ */
+export function setCachePreventionHeaders(headers) {
+    headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate, max-age=0');
+    headers.set('x-middleware-cache', 'no-cache');
+}
 export function redirectWithFallback(redirectUri, headers) {
     const newHeaders = headers ? new Headers(headers) : new Headers();
     newHeaders.set('Location', redirectUri);
     // Fall back to standard Response if NextResponse is not available.
     // This is to support Next.js 13.
-    return (NextResponse === null || NextResponse === void 0 ? void 0 : NextResponse.redirect)
+    return NextResponse?.redirect
         ? NextResponse.redirect(redirectUri, { headers })
         : new Response(null, { status: 307, headers: newHeaders });
 }
 export function errorResponseWithFallback(errorBody) {
     // Fall back to standard Response if NextResponse is not available.
     // This is to support Next.js 13.
-    return (NextResponse === null || NextResponse === void 0 ? void 0 : NextResponse.json)
+    return NextResponse?.json
         ? NextResponse.json(errorBody, { status: 500 })
         : new Response(JSON.stringify(errorBody), {
             status: 500,

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,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,YAAY,EAAE,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,YAAY,EAAE,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/validate-api-key.js

@@ -0,0 +1,16 @@
+'use server';
+import { getWorkOS } from './workos.js';
+import { headers } from 'next/headers';
+export async function validateApiKey() {
+    const headersList = await headers();
+    const authorizationHeader = headersList.get('authorization');
+    if (!authorizationHeader) {
+        return { apiKey: null };
+    }
+    const value = authorizationHeader.match(/Bearer\s+(.*)/i)?.[1];
+    if (!value) {
+        return { apiKey: null };
+    }
+    return getWorkOS().apiKeys.validateApiKey({ value });
+}
+//# sourceMappingURL=validate-api-key.js.map

package/dist/esm/validate-api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-api-key.js","sourceRoot":"","sources":["../../src/validate-api-key.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;IACpC,MAAM,mBAAmB,GAAG,WAAW,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7D,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,OAAO,SAAS,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACvD,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.10.0';
+export const VERSION = '2.14.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": "3.0.0-beta.1",
+  "version": "3.0.1",
   "description": "Authentication and session helpers for using WorkOS & AuthKit with Next.js",
   "sideEffects": false,
   "type": "module",
@@ -22,47 +22,34 @@
       "import": "./dist/esm/index.js"
     }
   },
-  "scripts": {
-    "clean": "rm -rf dist",
-    "prebuild": "npm run clean",
-    "build": "tsc --project tsconfig.json",
-    "prepublishOnly": "npm run lint",
-    "lint": "eslint \"src/**/*.ts*\"",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "prettier": "prettier \"src/**/*.{js,ts,tsx}\" --check",
-    "format": "prettier \"src/**/*.{js,ts,tsx}\" --write",
-    "type-check": "tsc --project tsconfig.json --noEmit"
-  },
   "dependencies": {
-    "@workos-inc/node": "^8.0.0-rc.1",
-    "iron-session": "^8.0.1",
-    "jose": "^5.2.3",
-    "path-to-regexp": "^6.2.2"
+    "@sindresorhus/fnv1a": "^3.1.0",
+    "@workos-inc/node": "^8.9.0",
+    "iron-session": "^8.0.4",
+    "jose": "^5.10.0",
+    "path-to-regexp": "^6.3.0",
+    "valibot": "^1.2.0"
   },
   "peerDependencies": {
-    "next": "^13.5.9 || ^14.2.26 || ^15.2.3",
+    "next": "^13.5.9 || ^14.2.26 || ^15.2.3 || ^16",
     "react": "^18.0 || ^19.0.0",
     "react-dom": "^18.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.0.1",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^20.11.28",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20.19.35",
     "@types/react": "18.2.67",
     "@types/react-dom": "18.2.22",
-    "eslint": "^8.29.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-require-extensions": "^0.1.3",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "next": "^15.0.1",
-    "prettier": "^3.3.3",
-    "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
-    "typescript": "5.4.2",
-    "typescript-eslint": "^7.2.0"
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "next": "^16.2.1",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "tslib": "^2.8.1",
+    "typescript": "6.0.2",
+    "typescript-eslint": "^7.18.0",
+    "vitest": "^3.2.4"
   },
   "license": "MIT",
   "homepage": "https://github.com/workos/authkit-nextjs#readme",
@@ -72,5 +59,17 @@
   },
   "bugs": {
     "url": "https://github.com/workos/authkit-nextjs/issues"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "pnpm run clean",
+    "build": "tsc --project tsconfig.app.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "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

@@ -8,31 +8,50 @@ import {
   getAccessTokenAction,
   refreshAccessTokenAction,
 } from '../src/actions.js';
-import { signOut, switchToOrganization } from './auth.js';
+import { getSignInUrl, signOut, switchToOrganization } from './auth.js';
 import { getWorkOS } from '../src/workos.js';
 import { withAuth, refreshSession } from '../src/session.js';
 
-jest.mock('../src/auth.js', () => ({
-  signOut: jest.fn().mockResolvedValue(true),
-  switchToOrganization: jest.fn().mockResolvedValue({ organizationId: 'org_123' }),
+vi.mock('../src/auth.js', () => ({
+  getSignInUrl: vi.fn().mockResolvedValue('https://api.workos.com/authorize?...'),
+  signOut: vi.fn().mockResolvedValue(true),
+  switchToOrganization: vi.fn().mockResolvedValue({ organizationId: 'org_123' }),
 }));
 
-const fakeWorkosInstance = {
-  organizations: {
-    getOrganization: jest.fn().mockResolvedValue({ id: 'org_123', name: 'Test Org' }),
+const { fakeWorkosInstance } = vi.hoisted(() => ({
+  fakeWorkosInstance: {
+    organizations: {
+      getOrganization: vi.fn().mockResolvedValue({ id: 'org_123', name: 'Test Org' }),
+    },
   },
-};
-jest.mock('../src/workos.js', () => ({
-  getWorkOS: jest.fn(() => fakeWorkosInstance),
+}));
+vi.mock('../src/workos.js', () => ({
+  getWorkOS: vi.fn(() => fakeWorkosInstance),
 }));
 
-jest.mock('../src/session.js', () => ({
-  withAuth: jest.fn().mockResolvedValue({ user: 'testUser', accessToken: 'access_token' }),
-  refreshSession: jest.fn().mockResolvedValue({ session: 'newSession', accessToken: 'refreshed_token' }),
+vi.mock('../src/session.js', () => ({
+  withAuth: vi.fn().mockResolvedValue({ user: 'testUser', accessToken: 'access_token' }),
+  refreshSession: vi.fn().mockResolvedValue({ user: 'testUser', accessToken: 'refreshed_token' }),
 }));
 
 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();
@@ -60,16 +79,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(getSignInUrl).toHaveBeenCalled();
+      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(getSignInUrl).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(getSignInUrl).toHaveBeenCalled();
+      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(getSignInUrl).not.toHaveBeenCalled();
+      expect(result).toEqual({ user: 'testUser', sessionId: 'session_123' });
     });
   });
 
@@ -94,7 +149,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

@@ -1,10 +1,15 @@
 'use server';
 
-import { signOut, switchToOrganization } from './auth.js';
+import { getSignInUrl, signOut, switchToOrganization } from './auth.js';
 import { NoUserInfo, UserInfo, SwitchToOrganizationOptions } from './interfaces.js';
 import { refreshSession, withAuth } from './session.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 +40,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 getSignInUrl();
+    return { ...sanitized, signInUrl };
+  }
+
+  return sanitized;
 };
 
 export const refreshAuthAction = async ({
@@ -45,7 +62,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 getSignInUrl();
+    return { ...sanitized, signInUrl };
+  }
+
+  return sanitized;
 };
 
 export const switchToOrganizationAction = async (organizationId: string, options?: SwitchToOrganizationOptions) => {
@@ -64,8 +91,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',
+    };
+  }
 }