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

package/README.md

@@ -9,7 +9,7 @@ The AuthKit library for Next.js provides convenient helpers for authentication a
 Install the package with:
 
 ```
-npm i @workos-inc/authkit-nextjs
+pnpm i @workos-inc/authkit-nextjs
 ```
 
 or
@@ -100,8 +100,9 @@ export const GET = handleAuth({
       await saveAuthMethod(user.id, authenticationMethod);
     }
     // Access custom state data passed through the auth flow
-    if (state?.teamId) {
-      await addUserToTeam(user.id, state.teamId);
+    const customData = state ? JSON.parse(state) : null;
+    if (customData?.teamId) {
+      await addUserToTeam(user.id, customData.teamId);
     }
   },
 });
@@ -128,39 +129,81 @@ export const GET = handleAuth({
 
 The `onSuccess` callback receives the following data:
 
-| Property               | Type                               | Description                                                                                        |
-| ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `user`                 | `User`                             | The authenticated user object                                                                      |
-| `accessToken`          | `string`                           | JWT access token                                                                                   |
-| `refreshToken`         | `string`                           | Refresh token for session renewal                                                                  |
-| `impersonator`         | `Impersonator \| undefined`        | Present if user is being impersonated                                                              |
-| `oauthTokens`          | `OauthTokens \| undefined`         | OAuth tokens from upstream provider                                                                |
-| `authenticationMethod` | `string \| undefined`              | How the user authenticated (e.g., 'password', 'google-oauth'). Only available during initial login |
-| `organizationId`       | `string \| undefined`              | Organization context of authentication                                                             |
-| `state`                | `Record<string, any> \| undefined` | Custom state data passed through the authentication flow                                           |
+| Property               | Type                        | Description                                                                                        |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `user`                 | `User`                      | The authenticated user object                                                                      |
+| `accessToken`          | `string`                    | JWT access token                                                                                   |
+| `refreshToken`         | `string`                    | Refresh token for session renewal                                                                  |
+| `impersonator`         | `Impersonator \| undefined` | Present if user is being impersonated                                                              |
+| `oauthTokens`          | `OauthTokens \| undefined`  | OAuth tokens from upstream provider                                                                |
+| `authenticationMethod` | `string \| undefined`       | How the user authenticated (e.g., 'password', 'google-oauth'). Only available during initial login |
+| `organizationId`       | `string \| undefined`       | Organization context of authentication                                                             |
+| `state`                | `string \| undefined`       | Custom state string passed through the authentication flow (parse with JSON.parse if needed)       |
 
 **Note**: `authenticationMethod` is only provided during the initial authentication callback. It will not be available in subsequent requests or session refreshes.
 
-### Middleware
+### Sign-in endpoint
 
-This library relies on [Next.js middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) to provide session management for routes. Put the following in your `middleware.ts` file in the root of your project:
+Create a route that initiates the AuthKit sign-in flow. This route is used as the **[Sign-in endpoint](https://workos.com/docs/authkit/nextjs/2-configure-your-project/configure-a-redirect-uri#sign-in-endpoint)** (also known as `initiate_login_uri`) in your WorkOS dashboard settings.
 
 ```ts
+// app/sign-in/route.ts (or app/login/route.ts)
+import { getSignInUrl } from '@workos-inc/authkit-nextjs';
+import { redirect } from 'next/navigation';
+
+export const GET = async () => {
+  const signInUrl = await getSignInUrl();
+  return redirect(signInUrl);
+};
+```
+
+In the [WorkOS dashboard](https://dashboard.workos.com), go to **Redirects** and set the **Sign-in endpoint** to match this route (e.g., `http://localhost:3000/sign-in`).
+
+> [!IMPORTANT]
+> The sign-in endpoint is required for features like [impersonation](https://workos.com/docs/user-management/impersonation) to work correctly. Without it, WorkOS-initiated flows (such as impersonating a user from the dashboard) will fail because they cannot complete the PKCE/CSRF verification that this library enforces on every callback.
+
+### Proxy / Middleware
+
+This library relies on Next.js proxy (called "middleware" in Next.js ≤15) to provide session management for routes.
+
+**For Next.js 16+:** Create a `proxy.ts` file in the root of your project.
+**For Next.js ≤15:** Create a `middleware.ts` file in the root of your project.
+
+```ts
+// proxy.ts (Next.js 16+)
+import { authkitProxy } from '@workos-inc/authkit-nextjs';
+
+export default authkitProxy();
+
+// Match against pages that require auth
+export const config = { matcher: ['/', '/admin'] };
+```
+
+```ts
+// middleware.ts (Next.js ≤15)
 import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
 
 export default authkitMiddleware();
 
 // Match against pages that require auth
-// Leave this out if you want auth on every resource (including images, css etc.)
 export const config = { matcher: ['/', '/admin'] };
 ```
 
-The middleware can be configured with several options.
+> [!WARNING]
+> Using a catch-all matcher pattern can intercept static assets (CSS, images, fonts), causing styles to break—particularly with Tailwind CSS v4. If you need a broad matcher, exclude Next.js static paths:
+>
+> ```ts
+> export const config = {
+>   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+> };
+> ```
+
+The proxy/middleware can be configured with several options.
 
 | Option           | Default     | Description                                                                                                             |
 | ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `redirectUri`    | `undefined` | Used in cases where you need your redirect URI to be set dynamically (e.g. Vercel preview deployments)                  |
-| `middlewareAuth` | `undefined` | Used to configure middleware auth options. See [middleware auth](#middleware-auth) for more details.                    |
+| `middlewareAuth` | `undefined` | Used to configure proxy/middleware auth options. See [middleware auth](#middleware-auth) for more details.              |
 | `debug`          | `false`     | Enables debug logs.                                                                                                     |
 | `signUpPaths`    | `[]`        | Used to specify paths that should use the 'sign-up' screen hint when redirecting to AuthKit.                            |
 | `eagerAuth`      | `false`     | Enables synchronous access token availability for third-party services. See [eager auth](#eager-auth) for more details. |
@@ -177,12 +220,123 @@ export default authkitMiddleware({
 });
 
 // Match against pages that require auth
-// Leave this out if you want auth on every resource (including images, css etc.)
 export const config = { matcher: ['/', '/admin'] };
 ```
 
 Custom redirect URIs will be used over a redirect URI configured in the environment variables.
 
+#### Composable proxy/middleware
+
+If you need to combine AuthKit with other proxy logic (rate limiting, redirects, etc.), use the `authkit()` function with `handleAuthkitHeaders()` helper:
+
+```ts
+// proxy.ts (Next.js 16+) or middleware.ts (Next.js ≤15)
+import { NextRequest } from 'next/server';
+import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';
+
+export default async function proxy(request: NextRequest) {
+  // For Next.js ≤15, use: export default async function middleware(request: NextRequest) {
+  // Get session, headers, and the WorkOS authorization URL for sign-in redirects
+  const { session, headers, authorizationUrl } = await authkit(request);
+
+  const { pathname } = request.nextUrl;
+
+  // Redirect unauthenticated users on protected routes
+  if (pathname.startsWith('/app') && !session.user && authorizationUrl) {
+    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl });
+  }
+
+  // Custom redirects (relative URLs supported)
+  if (pathname === '/old-path') {
+    return handleAuthkitHeaders(request, headers, { redirect: '/new-path' });
+  }
+
+  // Continue request with properly merged headers
+  return handleAuthkitHeaders(request, headers);
+}
+
+export const config = { matcher: ['/', '/app/:path*'] };
+```
+
+> [!IMPORTANT]
+> Always use `handleAuthkitHeaders()` when returning a response. This helper ensures:
+>
+> - AuthKit headers are properly passed to your pages (so `withAuth()` works)
+> - Internal headers (session data, URLs) are never leaked to the browser
+> - Only safe response headers (`Set-Cookie`, `Cache-Control`, `Vary`) are forwarded
+> - `Cache-Control: no-store` is automatically set when cookies are present
+> - `Vary` headers are properly merged when multiple values exist
+> - Relative redirect URLs are automatically normalized to absolute URLs
+> - POST/PUT redirects use 303 status to prevent form resubmission
+
+> [!NOTE]
+> The `redirect` option should only be used with trusted values (e.g., `authorizationUrl` from `authkit()` or hardcoded paths). Never pass user-controlled input directly to `redirect` without validation, as this could enable open redirect attacks.
+
+##### Redirect options
+
+```ts
+handleAuthkitHeaders(request, headers, {
+  redirect: '/login', // URL to redirect to (string or URL object)
+  redirectStatus: 307, // 302 | 303 | 307 | 308 (default: 307 for GET, 303 for POST)
+});
+```
+
+##### Advanced: Composing with rewrites
+
+For advanced use cases like rewrites, use the lower-level `partitionAuthkitHeaders()` and `applyResponseHeaders()`:
+
+```ts
+// proxy.ts (Next.js 16+) or middleware.ts (Next.js ≤15)
+import { NextRequest, NextResponse } from 'next/server';
+import { authkit, partitionAuthkitHeaders, applyResponseHeaders } from '@workos-inc/authkit-nextjs';
+
+export default async function proxy(request: NextRequest) {
+  // For Next.js ≤15, use: export default async function middleware(request: NextRequest) {
+  const { headers } = await authkit(request);
+  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, headers);
+
+  // Create your own response (rewrite, etc.)
+  const response = NextResponse.rewrite(new URL('/app/dashboard', request.url), {
+    request: { headers: requestHeaders },
+  });
+
+  // Apply AuthKit response headers (Set-Cookie, etc.)
+  applyResponseHeaders(response, responseHeaders);
+
+  return response;
+}
+```
+
+##### Internal headers reference
+
+AuthKit uses internal headers to pass data between proxy/middleware and server components. These are automatically handled by the helpers above, but understanding them helps with debugging.
+
+**Request headers** (passed to server components, never sent to browser):
+
+| Header                | Purpose                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `x-workos-middleware` | Flag indicating AuthKit proxy/middleware is active. Required for `withAuth()` to function. |
+| `x-workos-session`    | Encrypted session data. Contains user info, access token, and refresh token.               |
+| `x-url`               | Current request URL. Used for redirect-after-login and generating sign-in URLs.            |
+| `x-redirect-uri`      | OAuth callback URI. Used by `getAuthorizationUrl()` for the OAuth flow.                    |
+| `x-sign-up-paths`     | Paths configured to trigger sign-up instead of sign-in flow.                               |
+
+> **Security:** These headers contain sensitive session data. The `handleAuthkitHeaders()` helper ensures they're forwarded to your pages (so `withAuth()` works) but never leaked to the browser. Client-injected `x-workos-*` headers are stripped and replaced with trusted values.
+
+**Response headers** (safe to send to browser):
+
+| Header               | Purpose                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `Set-Cookie`         | Session cookies (e.g., `wos-session`). Multiple cookies are properly appended.         |
+| `Cache-Control`      | Caching directives. Auto-set to `no-store` when cookies are present.                   |
+| `Vary`               | Cache variation keys. Values are deduplicated when merging.                            |
+| `WWW-Authenticate`   | Authentication challenge for 401 responses (API auth flows).                           |
+| `Proxy-Authenticate` | Authentication challenge for proxy auth.                                               |
+| `Link`               | Pagination, preload hints, etc.                                                        |
+| `x-middleware-cache` | Next.js proxy/middleware result caching. Set to `no-cache` to prevent stale responses. |
+
+Only these allowlisted headers are forwarded to the browser. Any other headers from `authkit()` (including future `x-workos-*` headers) are filtered out for security.
+
 ## Usage
 
 ### Wrap your app in `AuthKitProvider`
@@ -203,6 +357,31 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+#### Optimizing with Server-Side Auth Data
+
+To avoid a server action call on mount, you can pass the initial auth data from the server to the `AuthKitProvider`.
+
+```jsx
+import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';
+import { withAuth } from '@workos-inc/authkit-nextjs';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  // Fetch auth data on the server
+  const auth = await withAuth();
+
+  // Remove the accessToken from the auth object as it is not needed on the client side
+  const { accessToken, ...initialAuth } = auth;
+
+  return (
+    <html lang="en">
+      <body>
+        <AuthKitProvider initialAuth={initialAuth}>{children}</AuthKitProvider>
+      </body>
+    </html>
+  );
+}
+```
+
 ### Get the current user in a server component
 
 For pages where you want to display a signed-in and signed-out view, use `withAuth` to retrieve the user session from WorkOS.
@@ -224,10 +403,10 @@ export default async function HomePage() {
 
     // You can also pass custom state data through the auth flow
     const signInUrlWithState = await getSignInUrl({
-      state: {
+      state: JSON.stringify({
         teamId: 'team_123',
         referrer: 'homepage',
-      },
+      }),
     });
 
     return (
@@ -403,41 +582,46 @@ JWT tokens are sensitive credentials and should be handled carefully:
 
 ### Passing Custom State Through Authentication
 
-You can pass custom state data through the authentication flow using the `state` parameter. This data will be available in the `onSuccess` callback after authentication:
+You can pass custom state data through the authentication flow using the `state` parameter. The state parameter is a string value that gets passed through OAuth and returned in the callback. To pass complex data, serialize it as JSON:
 
 ```ts
-// When generating sign-in/sign-up URLs
+// When generating sign-in/sign-up URLs, serialize your data as JSON
 const signInUrl = await getSignInUrl({
-  state: {
+  state: JSON.stringify({
     teamId: 'team_123',
     feature: 'billing',
     referrer: 'pricing-page',
     timestamp: Date.now(),
-  },
+  }),
 });
 
 // The state data is available in the callback handler
 export const GET = handleAuth({
   onSuccess: async ({ user, state }) => {
+    // Parse the state string back to an object
+    const customData = state ? JSON.parse(state) : null;
+
     // Access your custom state data
-    if (state?.teamId) {
-      await addUserToTeam(user.id, state.teamId);
+    if (customData?.teamId) {
+      await addUserToTeam(user.id, customData.teamId);
     }
 
-    if (state?.feature) {
-      await trackFeatureActivation(user.id, state.feature);
+    if (customData?.feature) {
+      await trackFeatureActivation(user.id, customData.feature);
     }
 
     // Track where the user came from
     await analytics.track('sign_in_completed', {
       userId: user.id,
-      referrer: state?.referrer,
-      timestamp: state?.timestamp,
+      referrer: customData?.referrer,
+      timestamp: customData?.timestamp,
     });
   },
 });
 ```
 
+> **Note**: The `state` parameter is an opaque string as defined by OAuth 2.0 (RFC 6749). If you need to pass structured data, you must serialize it yourself using `JSON.stringify()` and parse it with `JSON.parse()` in the callback.
+
 This is useful for:
 
 - Tracking user journey and referral sources
@@ -467,16 +651,16 @@ const { session, headers } = await authkit(request, {
 });
 ```
 
-These callbacks provide a way to perform side effects when sessions are refreshed in the middleware. Common use cases include:
+These callbacks provide a way to perform side effects when sessions are refreshed in the proxy/middleware. Common use cases include:
 
 - Logging authentication events
 - Updating last activity timestamps
 - Triggering organization-specific data prefetching
 - Recording failed refresh attempts
 
-### Middleware auth
+### Proxy / Middleware auth
 
-The default behavior of this library is to request authentication via the `withAuth` method on a per-page basis. There are some use cases where you don't want to call `withAuth` (e.g. you don't need user data for your page) or if you'd prefer a "secure by default" approach where every route defined in your middleware matcher is protected unless specified otherwise. In those cases you can opt-in to use middleware auth instead:
+The default behavior of this library is to request authentication via the `withAuth` method on a per-page basis. There are some use cases where you don't want to call `withAuth` (e.g. you don't need user data for your page) or if you'd prefer a "secure by default" approach where every route defined in your proxy/middleware matcher is protected unless specified otherwise. In those cases you can opt-in to use `middlewareAuth` instead:
 
 ```ts
 import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
@@ -503,7 +687,7 @@ The `eagerAuth` option enables synchronous access to authentication tokens on in
 
 #### How it works
 
-When `eagerAuth: true` is set, the middleware temporarily stores the access token in a short-lived cookie (30 seconds) that is:
+When `eagerAuth: true` is set, the proxy/middleware temporarily stores the access token in a short-lived cookie (30 seconds) that is:
 
 - Only set on initial page loads (not API or prefetch requests)
 - Immediately consumed and deleted by the client
@@ -511,7 +695,7 @@ When `eagerAuth: true` is set, the middleware temporarily stores the access toke
 
 #### Usage
 
-Enable eager auth in your middleware configuration:
+Enable eager auth in your proxy/middleware configuration:
 
 ```ts
 import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
@@ -531,16 +715,18 @@ import { useAccessToken } from '@workos-inc/authkit-nextjs/components';
 function MyComponent() {
   const { getAccessToken } = useAccessToken();
 
-  // Token is available immediately on initial page load
-  const token = getAccessToken();
+  async function handleClick() {
+    // Token is available immediately on initial page load
+    const token = await getAccessToken();
 
-  // Use with third-party services that need immediate token access
-  if (token) {
-    // Initialize your third-party client with the token
-    thirdPartyClient.authenticate(token);
+    // Use with third-party services that need immediate token access
+    if (token) {
+      // Initialize your third-party client with the token
+      thirdPartyClient.authenticate(token);
+    }
   }
 
-  return <div>...</div>;
+  return <button onClick={handleClick}>Authenticate</button>;
 }
 ```
 
@@ -565,64 +751,6 @@ Eager auth makes tokens briefly accessible via JavaScript (30-second window) to
 - Most API calls where a brief loading state is acceptable
 - When you don't need immediate token access on page load
 
-### Composing middleware
-
-> **Security note:** Always forward `request.headers` when returning `NextResponse.*` to mitigate SSRF issues in Next.js < 14.2.32 (14.x) or < 15.4.7 (15.x). This pattern is safe on all versions. We strongly recommend upgrading to the latest Next.js.
-
-If you don't want to use `authkitMiddleware` and instead want to compose your own middleware, you can use the `authkit` method. In this mode you are responsible to handling what to do when there's no session on a protected route.
-
-```ts
-export default async function middleware(request: NextRequest) {
-  // Perform logic before or after AuthKit
-
-  // Auth object contains the session, response headers and an authorization URL in the case that the session isn't valid
-  // This method will automatically handle setting the cookie and refreshing the session
-  const {
-    session,
-    headers: authkitHeaders,
-    authorizationUrl,
-  } = await authkit(request, {
-    debug: true,
-  });
-
-  const { pathname } = new URL(request.url);
-
-  // Control of what to do when there's no session on a protected route is left to the developer
-  if (pathname.startsWith('/account') && !session.user) {
-    console.log('No session on protected path');
-
-    // Preserve AuthKit headers on redirects (e.g., cookies)
-    const response = NextResponse.redirect(authorizationUrl);
-    for (const [key, value] of authkitHeaders) {
-      if (key.toLowerCase() === 'set-cookie') {
-        response.headers.append(key, value);
-      } else {
-        response.headers.set(key, value);
-      }
-    }
-    return response;
-  }
-
-  // Forward the incoming request headers (mitigation) and then add AuthKit's headers
-  const response = NextResponse.next({
-    request: { headers: new Headers(request.headers) },
-  });
-
-  for (const [key, value] of authkitHeaders) {
-    if (key.toLowerCase() === 'set-cookie') {
-      response.headers.append(key, value);
-    } else {
-      response.headers.set(key, value);
-    }
-  }
-
-  return response;
-}
-
-// Match against the pages
-export const config = { matcher: ['/', '/account/:path*'] };
-```
-
 ### Signing out
 
 Use the `signOut` method to sign out the current logged in user and redirect to your app's default Logout URI. The Logout URI is set in your WorkOS dashboard settings under "Redirect".
@@ -638,6 +766,9 @@ await signOut({ returnTo: 'https://your-app.com/signed-out' });
 Render the `Impersonation` component in your app so that it is clear when someone is [impersonating a user](https://workos.com/docs/user-management/impersonation).
 The component will display a frame with some information about the impersonated user, as well as a button to stop impersonating.
 
+> [!IMPORTANT]
+> Impersonation requires a configured **Sign-in endpoint** in your WorkOS dashboard. See the [sign-in endpoint](#sign-in-endpoint) setup instructions. Without it, impersonation from the WorkOS dashboard will fail with a `Missing required auth parameter` error.
+
 ```jsx
 import { Impersonation, AuthKitProvider } from '@workos-inc/authkit-nextjs/components';
 
@@ -689,6 +820,25 @@ export default authkitMiddleware({
 });
 ```
 
+### Validate an API key
+
+Use the `validateApiKey` function in your application's public API endpoints to parse a [Bearer Authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/) header and validate the [API key](https://workos.com/docs/authkit/api-keys) with WorkOS.
+
+```ts
+import { NextResponse } from 'next/server';
+import { validateApiKey } from '@workos-inc/authkit-nextjs';
+
+export async function GET() {
+  const { apiKey } = await validateApiKey();
+
+  if (!apiKey) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  return NextResponse.json({ success: true });
+}
+```
+
 ### Advanced: Direct access to the WorkOS client
 
 For advanced use cases or functionality not covered by the helper methods, you can access the underlying WorkOS client directly:
@@ -753,9 +903,35 @@ await saveSession(session, req);
 await saveSession(session, 'https://example.com/callback');
 ```
 
+### CDN Deployments and Caching
+
+AuthKit automatically implements cache security measures to protect against session leakage in CDN environments. This is particularly important when deploying to AWS with SST/OpenNext, Cloudflare, or other CDN configurations.
+
+#### How It Works
+
+The library automatically sets appropriate cache headers on all authenticated requests:
+
+- `Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0` - Aggressive cache prevention with multiple directives
+- `Pragma: no-cache` - HTTP/1.0 compatibility
+- `Expires: 0` - HTTP/1.0 cache expiration
+- `Vary: Cookie` - Ensures CDNs differentiate between different users (defense-in-depth)
+- `x-middleware-cache: no-cache` - Prevents Next.js proxy/middleware result caching
+
+These headers are applied automatically when:
+
+- A session cookie is present in the request
+- An Authorization header is detected
+- An active authenticated session exists
+
+#### Performance Considerations
+
+**Authenticated pages:** Will not be cached at the CDN level and will always hit your origin server. This is the correct and secure behavior for session-based authentication.
+
+**Public pages:** Unaffected by these security measures. Public routes without authentication context can still be cached normally.
+
 ### Debugging
 
-To enable debug logs, initialize the middleware with the debug flag enabled.
+To enable debug logs, initialize the proxy/middleware with the debug flag enabled.
 
 ```js
 import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
@@ -763,8 +939,35 @@ import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
 export default authkitMiddleware({ debug: true });
 ```
 
+### Security
+
+#### PKCE and CSRF protection
+
+This library uses [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) (Proof Key for Code Exchange) and a sealed (encrypted) OAuth state parameter on every authorization request. The state contains a cryptographic nonce for CSRF protection per [RFC 9700](https://datatracker.ietf.org/doc/rfc9700/) and a code verifier for protection against authorization code interception. During sign-in, a short-lived `wos-auth-verifier` cookie is set containing the sealed state. This cookie is automatically cleaned up after the callback completes.
+
+> [!NOTE]
+> **Upgrading to v3:** PKCE is now always enabled. The `WORKOS_ENABLE_PKCE` environment variable is no longer needed and can be removed from your configuration.
+
+#### Cookie requirements
+
+The `wos-auth-verifier` cookie must survive the round-trip from sign-in initiation to the callback. On callback, the library verifies that the cookie is present and matches the URL `state` parameter — this two-channel check is what prevents CSRF attacks.
+
+If the cookie is missing or doesn't match, authentication will fail with one of:
+
+- `Auth cookie missing` — the cookie was not sent back with the callback request. This typically happens when a reverse proxy or CDN strips `Set-Cookie` headers on redirects.
+- `OAuth state mismatch` — the cookie and URL `state` parameter don't match, indicating a possible CSRF attack or cookie corruption.
+
+> [!IMPORTANT]
+> **Upgrading to v3:** Previous versions would silently fall back to verifying only the URL `state` parameter when the cookie was missing. This fallback has been removed because it disabled CSRF protection. If you see `Auth cookie missing` errors after upgrading, ensure that `Set-Cookie` headers are propagated on redirects between your application and the user's browser.
+
 ### Troubleshooting
 
+#### `Missing required auth parameter` when impersonating from the WorkOS dashboard
+
+This error occurs when WorkOS-initiated flows (like dashboard impersonation) redirect directly to your callback URL without going through your application's sign-in flow. Because this library enforces PKCE/CSRF verification on every callback, the request is rejected when the required `state` parameter is missing.
+
+**Fix:** Configure a [sign-in endpoint](#sign-in-endpoint) in your WorkOS dashboard so that impersonation flows route through your app first, allowing PKCE/state to be set up before redirecting to WorkOS.
+
 #### NEXT_REDIRECT error when using try/catch blocks
 
 Wrapping a `withAuth({ ensureSignedIn: true })` call in a try/catch block will cause a `NEXT_REDIRECT` error. This is because `withAuth` will attempt to redirect the user to AuthKit if no session is detected and redirects in Next must be [called outside a try/catch](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations#redirecting).

package/dist/esm/actions.js

@@ -1,5 +1,5 @@
 'use server';
-import { signOut, switchToOrganization } from './auth.js';
+import { getSignInUrl, signOut, switchToOrganization } from './auth.js';
 import { refreshSession, withAuth } from './session.js';
 import { getWorkOS } from './workos.js';
 /**
@@ -28,10 +28,28 @@ export const getOrganizationAction = async (organizationId) => {
     return await getWorkOS().organizations.getOrganization(organizationId);
 };
 export const getAuthAction = async (options) => {
-    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 ({ ensureSignedIn, organizationId, }) => {
-    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, options) => {
     return sanitize(await switchToOrganization(organizationId, options));
@@ -47,9 +65,21 @@ 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;
+    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',
+        };
+    }
 }
 //# sourceMappingURL=actions.js.map

package/dist/esm/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/actions.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;GAKG;AACH,SAAS,QAAQ,CAAkC,KAAQ;IACzD,6DAA6D;IAC7D,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,EAAE,GAAG,KAAK,CAAC;IAC5C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,IAAI,EAAE;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EAAE,EAAE,QAAQ,KAA4B,EAAE,EAAE,EAAE;IACpF,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EAAE,cAAsB,EAAE,EAAE;IACpE,OAAO,MAAM,SAAS,EAAE,CAAC,aAAa,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;AACzE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAAsC,EAAE,EAAE;IAC5E,OAAO,QAAQ,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,EACtC,cAAc,EACd,cAAc,GAIf,EAAE,EAAE;IACH,OAAO,QAAQ,CAAC,MAAM,cAAc,CAAC,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;AAC5E,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,EAAE,cAAsB,EAAE,OAAqC,EAAE,EAAE;IAChH,OAAO,QAAQ,CAAC,MAAM,oBAAoB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;AACvE,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,IAAI,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,WAAW,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,IAAI,GAAG,MAAM,cAAc,EAAE,CAAC;IACpC,OAAO,IAAI,CAAC,WAAW,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/actions.ts"],"names":[],"mappings":"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"}