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

package/README.md

@@ -94,11 +94,15 @@ If your application needs to persist data upon a successful authentication, like
 
 ```ts
 export const GET = handleAuth({
-  onSuccess: async ({ user, oauthTokens, authenticationMethod, organizationId }) => {
+  onSuccess: async ({ user, oauthTokens, authenticationMethod, organizationId, state }) => {
     await saveTokens(oauthTokens);
     if (authenticationMethod) {
       await saveAuthMethod(user.id, authenticationMethod);
     }
+    // Access custom state data passed through the auth flow
+    if (state?.teamId) {
+      await addUserToTeam(user.id, state.teamId);
+    }
   },
 });
 ```
@@ -124,15 +128,16 @@ 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                                                             |
+| 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                                           |
 
 **Note**: `authenticationMethod` is only provided during the initial authentication callback. It will not be available in subsequent requests or session refreshes.
 
@@ -217,6 +222,14 @@ export default async function HomePage() {
     // Get the URL to redirect the user to AuthKit to sign up
     const signUpUrl = await getSignUpUrl();
 
+    // You can also pass custom state data through the auth flow
+    const signInUrlWithState = await getSignInUrl({
+      state: {
+        teamId: 'team_123',
+        referrer: 'homepage',
+      },
+    });
+
     return (
       <>
         <Link href={signInUrl}>Log in</Link>
@@ -244,7 +257,7 @@ export default async function HomePage() {
 For client components, use the `useAuth` hook to get the current user session.
 
 ```jsx
-'use client'
+'use client';
 // Note the updated import path
 import { useAuth } from '@workos-inc/authkit-nextjs/components';
 
@@ -260,6 +273,14 @@ export default function MyComponent() {
 }
 ```
 
+### Get the enabled flags for the logged in user
+
+For situations where you need access to the authenticated user's currently active feature flags, use `withAuth` to retrieve the flags from the WorkOS session.
+
+```jsx
+const { featureFlags } = await withAuth();
+```
+
 ### Requiring auth
 
 For pages where a signed-in user is mandatory, you can use the `ensureSignedIn` option:
@@ -380,6 +401,50 @@ JWT tokens are sensitive credentials and should be handled carefully:
 - Don't store tokens in localStorage or sessionStorage
 - Be cautious about exposing tokens in your application state
 
+### 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:
+
+```ts
+// When generating sign-in/sign-up URLs
+const signInUrl = await getSignInUrl({
+  state: {
+    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 }) => {
+    // Access your custom state data
+    if (state?.teamId) {
+      await addUserToTeam(user.id, state.teamId);
+    }
+
+    if (state?.feature) {
+      await trackFeatureActivation(user.id, state.feature);
+    }
+
+    // Track where the user came from
+    await analytics.track('sign_in_completed', {
+      userId: user.id,
+      referrer: state?.referrer,
+      timestamp: state?.timestamp,
+    });
+  },
+});
+```
+
+This is useful for:
+
+- Tracking user journey and referral sources
+- Maintaining context about what the user was trying to do before authentication
+- Implementing custom onboarding flows
+- Analytics and attribution tracking
+
 ### Session Refresh Callbacks
 
 When using the `authkit` function directly, you can provide callbacks to be notified when a session is refreshed:
@@ -461,10 +526,10 @@ Then access the token synchronously in your client components:
 ```tsx
 'use client';
 
-import { useAuth } from '@workos-inc/authkit-nextjs';
+import { useAccessToken } from '@workos-inc/authkit-nextjs/components';
 
 function MyComponent() {
-  const { getAccessToken } = useAuth();
+  const { getAccessToken } = useAccessToken();
 
   // Token is available immediately on initial page load
   const token = getAccessToken();
@@ -704,6 +769,6 @@ export default authkitMiddleware({ debug: true });
 
 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).
 
-#### Module build failed: UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme).
+#### Module build failed: UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme)
 
 You may encounter this error if you attempt to import server side code from authkit-nextjs into a client component. Likely you are using `withAuth` in a client component instead of the `useAuth` hook. Either move the code to a server component or use the `useAuth` hook.

package/dist/esm/auth.js

@@ -8,11 +8,11 @@ import { getCookieOptions } from './cookie.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import { getSessionFromCookie, refreshSession, withAuth } from './session.js';
 import { getWorkOS } from './workos.js';
-export async function getSignInUrl({ organizationId, loginHint, redirectUri, prompt, } = {}) {
-    return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri, prompt });
+export async function getSignInUrl({ organizationId, loginHint, redirectUri, prompt, state, } = {}) {
+    return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri, prompt, state });
 }
-export async function getSignUpUrl({ organizationId, loginHint, redirectUri, prompt, } = {}) {
-    return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri, prompt });
+export async function getSignUpUrl({ organizationId, loginHint, redirectUri, prompt, state, } = {}) {
+    return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri, prompt, state });
 }
 /**
  * Sign out the user and delete the session cookie.

package/dist/esm/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/esm/authkit-callback-route.js

@@ -2,6 +2,40 @@ import { WORKOS_CLIENT_ID } from './env-variables.js';
 import { saveSession } from './session.js';
 import { errorResponseWithFallback, redirectWithFallback } from './utils.js';
 import { getWorkOS } from './workos.js';
+function handleState(state) {
+    let returnPathname = undefined;
+    let userState;
+    if (state === null || state === void 0 ? void 0 : state.includes('.')) {
+        const [internal, ...rest] = state.split('.');
+        userState = rest.join('.');
+        try {
+            // Reverse URL-safe base64 encoding
+            const decoded = internal.replace(/-/g, '+').replace(/_/g, '/');
+            returnPathname = JSON.parse(atob(decoded)).returnPathname;
+        }
+        catch (_a) {
+            // Malformed internal part, ignore it
+        }
+    }
+    else if (state) {
+        try {
+            const decoded = JSON.parse(atob(state));
+            if (decoded.returnPathname) {
+                returnPathname = decoded.returnPathname;
+            }
+            else {
+                userState = state;
+            }
+        }
+        catch (_b) {
+            userState = state;
+        }
+    }
+    return {
+        returnPathname,
+        state: userState,
+    };
+}
 export function handleAuth(options = {}) {
     const { returnPathname: returnPathnameOption = '/', baseURL, onSuccess, onError } = options;
     // Throw early if baseURL is provided but invalid
@@ -16,7 +50,7 @@ export function handleAuth(options = {}) {
     return async function GET(request) {
         const code = request.nextUrl.searchParams.get('code');
         const state = request.nextUrl.searchParams.get('state');
-        let returnPathname = state && state !== 'null' ? JSON.parse(atob(state)).returnPathname : null;
+        const { state: customState, returnPathname: returnPathnameState } = handleState(state);
         if (code) {
             try {
                 // Use the code returned to us by AuthKit and authenticate the user with WorkOS
@@ -32,7 +66,7 @@ export function handleAuth(options = {}) {
                 url.searchParams.delete('code');
                 url.searchParams.delete('state');
                 // Redirect to the requested path and store the session
-                returnPathname = returnPathname !== null && returnPathname !== void 0 ? returnPathname : returnPathnameOption;
+                const returnPathname = returnPathnameState !== null && returnPathnameState !== void 0 ? returnPathnameState : returnPathnameOption;
                 // Extract the search params if they are present
                 if (returnPathname.includes('?')) {
                     const newUrl = new URL(returnPathname, 'https://example.com');
@@ -59,6 +93,7 @@ export function handleAuth(options = {}) {
                         oauthTokens,
                         authenticationMethod,
                         organizationId,
+                        state: customState,
                     });
                 }
                 return response;

package/dist/esm/authkit-callback-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"authkit-callback-route.js","sourceRoot":"","sources":["../../src/authkit-callback-route.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authkit-callback-route.js","sourceRoot":"","sources":["../../src/authkit-callback-route.ts"],"names":[],"mappings":"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"}

package/dist/esm/get-authorization-url.js

@@ -3,12 +3,16 @@ import { WORKOS_CLIENT_ID, WORKOS_REDIRECT_URI } from './env-variables.js';
 import { headers } from 'next/headers';
 async function getAuthorizationUrl(options = {}) {
     const headersList = await headers();
-    const { returnPathname, screenHint, organizationId, redirectUri = headersList.get('x-redirect-uri'), loginHint, prompt, } = options;
+    const { returnPathname, screenHint, organizationId, redirectUri = headersList.get('x-redirect-uri'), loginHint, prompt, state: customState, } = options;
+    const internalState = returnPathname
+        ? btoa(JSON.stringify({ returnPathname })).replace(/\+/g, '-').replace(/\//g, '_')
+        : null;
+    const finalState = internalState && customState ? `${internalState}.${customState}` : internalState || customState || undefined;
     return getWorkOS().userManagement.getAuthorizationUrl({
         provider: 'authkit',
         clientId: WORKOS_CLIENT_ID,
         redirectUri: redirectUri !== null && redirectUri !== void 0 ? redirectUri : WORKOS_REDIRECT_URI,
-        state: returnPathname ? btoa(JSON.stringify({ returnPathname })) : undefined,
+        state: finalState,
         screenHint,
         organizationId,
         loginHint,

package/dist/esm/get-authorization-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-authorization-url.js","sourceRoot":"","sources":["../../src/get-authorization-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,KAAK,UAAU,mBAAmB,CAAC,UAA6B,EAAE;IAChE,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;IACpC,MAAM,EACJ,cAAc,EACd,UAAU,EACV,cAAc,EACd,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAC/C,SAAS,EACT,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,EAAE,CAAC,cAAc,CAAC,mBAAmB,CAAC;QACpD,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,gBAAgB;QAC1B,WAAW,EAAE,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,mBAAmB;QAC/C,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5E,UAAU;QACV,cAAc;QACd,SAAS;QACT,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"get-authorization-url.js","sourceRoot":"","sources":["../../src/get-authorization-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,KAAK,UAAU,mBAAmB,CAAC,UAA6B,EAAE;IAChE,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;IACpC,MAAM,EACJ,cAAc,EACd,UAAU,EACV,cAAc,EACd,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAC/C,SAAS,EACT,MAAM,EACN,KAAK,EAAE,WAAW,GACnB,GAAG,OAAO,CAAC;IAEZ,MAAM,aAAa,GAAG,cAAc;QAClC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QAClF,CAAC,CAAC,IAAI,CAAC;IAET,MAAM,UAAU,GACd,aAAa,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,aAAa,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,WAAW,IAAI,SAAS,CAAC;IAE/G,OAAO,SAAS,EAAE,CAAC,cAAc,CAAC,mBAAmB,CAAC;QACpD,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,gBAAgB;QAC1B,WAAW,EAAE,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,mBAAmB;QAC/C,KAAK,EAAE,UAAU;QACjB,UAAU;QACV,cAAc;QACd,SAAS;QACT,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/esm/test-helpers.js

@@ -35,6 +35,7 @@ export async function generateSession(overrides = {}) {
         createdAt: '2024-01-01T00:00:00Z',
         updatedAt: '2024-01-01T00:00:00Z',
         lastSignInAt: '2024-01-01T00:00:00Z',
+        locale: null,
         externalId: null,
         metadata: {},
         ...overrides,

package/dist/esm/test-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../../src/test-helpers.ts"],"names":[],"mappings":"AAAA,uBAAuB;AAEvB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAO,GAAG,EAAE,EAAE,OAAO,GAAG,KAAK;IACnE,MAAM,cAAc,GAAG;QACrB,GAAG,EAAE,aAAa;QAClB,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,CAAC,QAAQ,CAAC;QACjB,WAAW,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;QAC7C,YAAY,EAAE,CAAC,YAAY,CAAC;QAC5B,aAAa,EAAE,CAAC,4BAA4B,CAAC;KAC9C,CAAC;IAEF,MAAM,aAAa,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;IAExD,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAgC,CAAC,CAAC;IAEtF,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;SAC3C,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;SACpC,WAAW,EAAE;SACb,SAAS,CAAC,oBAAoB,CAAC;SAC/B,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;SACxC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,YAA2B,EAAE;IACjE,MAAM,QAAQ,GAAG;QACf,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,kBAAkB;QACzB,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;QACvB,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,sBAAsB;QACjC,SAAS,EAAE,sBAAsB;QACjC,YAAY,EAAE,sBAAsB;QACpC,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,EAAE;QACZ,GAAG,SAAS;KACE,CAAC;IAEjB,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC;QAC1C,GAAG,EAAE,aAAa;QAClB,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;IAEH,kCAAkC;IAClC,MAAM,gBAAgB,GAAG,MAAM,QAAQ,CACrC;QACE,WAAW;QACX,YAAY,EAAE,mBAAmB;QACjC,IAAI,EAAE,QAAQ;KACf,EACD;QACE,QAAQ,EAAE,sBAAgC;KAC3C,CACF,CAAC;IAEF,MAAM,UAAU,GAAG,kBAAkB,IAAI,aAAa,CAAC;IACvD,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;IACpC,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../../src/test-helpers.ts"],"names":[],"mappings":"AAAA,uBAAuB;AAEvB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAO,GAAG,EAAE,EAAE,OAAO,GAAG,KAAK;IACnE,MAAM,cAAc,GAAG;QACrB,GAAG,EAAE,aAAa;QAClB,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,CAAC,QAAQ,CAAC;QACjB,WAAW,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;QAC7C,YAAY,EAAE,CAAC,YAAY,CAAC;QAC5B,aAAa,EAAE,CAAC,4BAA4B,CAAC;KAC9C,CAAC;IAEF,MAAM,aAAa,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;IAExD,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAgC,CAAC,CAAC;IAEtF,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;SAC3C,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;SACpC,WAAW,EAAE;SACb,SAAS,CAAC,oBAAoB,CAAC;SAC/B,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;SACxC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,YAA2B,EAAE;IACjE,MAAM,QAAQ,GAAG;QACf,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,kBAAkB;QACzB,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;QACvB,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,sBAAsB;QACjC,SAAS,EAAE,sBAAsB;QACjC,YAAY,EAAE,sBAAsB;QACpC,MAAM,EAAE,IAAI;QACZ,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,EAAE;QACZ,GAAG,SAAS;KACE,CAAC;IAEjB,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC;QAC1C,GAAG,EAAE,aAAa;QAClB,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;IAEH,kCAAkC;IAClC,MAAM,gBAAgB,GAAG,MAAM,QAAQ,CACrC;QACE,WAAW;QACX,YAAY,EAAE,mBAAmB;QACjC,IAAI,EAAE,QAAQ;KACf,EACD;QACE,QAAQ,EAAE,sBAAgC;KAC3C,CACF,CAAC;IAEF,MAAM,UAAU,GAAG,kBAAkB,IAAI,aAAa,CAAC;IACvD,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;IACpC,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AAChD,CAAC"}

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

@@ -1,15 +1,17 @@
 import type { SwitchToOrganizationOptions, UserInfo } from './interfaces.js';
-export declare function getSignInUrl({ organizationId, loginHint, redirectUri, prompt, }?: {
+export declare function getSignInUrl({ organizationId, loginHint, redirectUri, prompt, state, }?: {
     organizationId?: string;
     loginHint?: string;
     redirectUri?: string;
     prompt?: 'consent';
+    state?: string;
 }): Promise<string>;
-export declare function getSignUpUrl({ organizationId, loginHint, redirectUri, prompt, }?: {
+export declare function getSignUpUrl({ organizationId, loginHint, redirectUri, prompt, state, }?: {
     organizationId?: string;
     loginHint?: string;
     redirectUri?: string;
     prompt?: 'consent';
+    state?: string;
 }): Promise<string>;
 /**
  * Sign out the user and delete the session cookie.

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

@@ -13,6 +13,7 @@ export interface HandleAuthSuccessData extends Session {
     oauthTokens?: OauthTokens;
     organizationId?: string;
     authenticationMethod?: AuthenticationResponse['authenticationMethod'];
+    state?: string | undefined;
 }
 export interface Impersonator {
     email: string;
@@ -64,6 +65,7 @@ export interface GetAuthURLOptions {
     redirectUri?: string;
     loginHint?: string;
     prompt?: 'consent';
+    state?: string;
 }
 export interface AuthkitMiddlewareAuth {
     enabled: boolean;

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

@@ -1,5 +1,5 @@
 import { WorkOS } from '@workos-inc/node';
-export declare const VERSION = "2.9.0";
+export declare const VERSION = "2.10.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/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.9.0';
+export const VERSION = '2.10.0';
 const options = {
     apiHostname: WORKOS_API_HOSTNAME,
     https: WORKOS_API_HTTPS ? WORKOS_API_HTTPS === 'true' : true,

package/dist/esm/workos.js.map

@@ -1 +1 @@
-{"version":3,"file":"workos.js","sourceRoot":"","sources":["../../src/workos.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,MAAM,OAAO,GAAG;IACd,WAAW,EAAE,mBAAmB;IAChC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;IAC5D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;IAC7D,OAAO,EAAE;QACP,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;KACjB;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC"}
+{"version":3,"file":"workos.js","sourceRoot":"","sources":["../../src/workos.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEhC,MAAM,OAAO,GAAG;IACd,WAAW,EAAE,mBAAmB;IAChC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;IAC5D,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;IAC7D,OAAO,EAAE;QACP,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;KACjB;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos-inc/authkit-nextjs",
-  "version": "2.9.0",
+  "version": "3.0.0-beta.1",
   "description": "Authentication and session helpers for using WorkOS & AuthKit with Next.js",
   "sideEffects": false,
   "type": "module",
@@ -35,7 +35,7 @@
     "type-check": "tsc --project tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@workos-inc/node": "^7.67.0",
+    "@workos-inc/node": "^8.0.0-rc.1",
     "iron-session": "^8.0.1",
     "jose": "^5.2.3",
     "path-to-regexp": "^6.2.2"

package/src/auth.ts

@@ -15,8 +15,15 @@ export async function getSignInUrl({
   loginHint,
   redirectUri,
   prompt,
-}: { organizationId?: string; loginHint?: string; redirectUri?: string; prompt?: 'consent' } = {}) {
-  return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri, prompt });
+  state,
+}: {
+  organizationId?: string;
+  loginHint?: string;
+  redirectUri?: string;
+  prompt?: 'consent';
+  state?: string;
+} = {}) {
+  return getAuthorizationUrl({ organizationId, screenHint: 'sign-in', loginHint, redirectUri, prompt, state });
 }
 
 export async function getSignUpUrl({
@@ -24,8 +31,15 @@ export async function getSignUpUrl({
   loginHint,
   redirectUri,
   prompt,
-}: { organizationId?: string; loginHint?: string; redirectUri?: string; prompt?: 'consent' } = {}) {
-  return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri, prompt });
+  state,
+}: {
+  organizationId?: string;
+  loginHint?: string;
+  redirectUri?: string;
+  prompt?: 'consent';
+  state?: string;
+} = {}) {
+  return getAuthorizationUrl({ organizationId, screenHint: 'sign-up', loginHint, redirectUri, prompt, state });
 }
 
 /**

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

@@ -34,6 +34,7 @@ describe('authkit-callback-route', () => {
       createdAt: '2024-01-01T00:00:00Z',
       updatedAt: '2024-01-01T00:00:00Z',
       lastSignInAt: '2024-01-01T00:00:00Z',
+      locale: null,
       externalId: null,
       metadata: {},
     },
@@ -275,5 +276,73 @@ describe('authkit-callback-route', () => {
       const session = await getSessionFromCookie();
       expect(session?.accessToken).toBe(newAccessToken);
     });
+
+    it('should pass custom state data to onSuccess callback', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Create state with new format: internal.user
+      const internalState = btoa(JSON.stringify({ returnPathname: '/dashboard' }))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+      const userState = 'custom-user-state-string';
+      const state = `${internalState}.${userState}`;
+
+      request.nextUrl.searchParams.set('code', 'test-code');
+      request.nextUrl.searchParams.set('state', state);
+
+      const onSuccess = jest.fn();
+      const handler = handleAuth({ onSuccess });
+      await handler(request);
+
+      // Verify onSuccess was called with the custom state string
+      expect(onSuccess).toHaveBeenCalledWith(
+        expect.objectContaining({
+          ...mockAuthResponse,
+          state: 'custom-user-state-string',
+        }),
+      );
+
+      // Verify the redirect went to the correct path
+      const response = await handler(request);
+      expect(response.headers.get('Location')).toContain('/dashboard');
+    });
+
+    it('should handle state without custom data', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // State with only returnPathname
+      const state = btoa(JSON.stringify({ returnPathname: '/profile' }));
+
+      request.nextUrl.searchParams.set('code', 'test-code');
+      request.nextUrl.searchParams.set('state', state);
+
+      const onSuccess = jest.fn();
+      const handler = handleAuth({ onSuccess });
+      await handler(request);
+
+      // Verify onSuccess was called without state property when no custom data exists
+      expect(onSuccess).toHaveBeenCalledWith(
+        expect.objectContaining({
+          ...mockAuthResponse,
+          state: undefined,
+        }),
+      );
+    });
+
+    it('should handle backward compatibility with old state format', async () => {
+      jest.mocked(workos.userManagement.authenticateWithCode).mockResolvedValue(mockAuthResponse);
+
+      // Old format: just returnPathname
+      const state = btoa(JSON.stringify({ returnPathname: '/old-path' }));
+
+      request.nextUrl.searchParams.set('code', 'test-code');
+      request.nextUrl.searchParams.set('state', state);
+
+      const handler = handleAuth();
+      const response = await handler(request);
+
+      // Should still redirect correctly
+      expect(response.headers.get('Location')).toContain('/old-path');
+    });
   });
 });

package/src/authkit-callback-route.ts

@@ -5,6 +5,37 @@ import { saveSession } from './session.js';
 import { errorResponseWithFallback, redirectWithFallback } from './utils.js';
 import { getWorkOS } from './workos.js';
 
+function handleState(state: string | null) {
+  let returnPathname: string | undefined = undefined;
+  let userState: string | undefined;
+  if (state?.includes('.')) {
+    const [internal, ...rest] = state.split('.');
+    userState = rest.join('.');
+    try {
+      // Reverse URL-safe base64 encoding
+      const decoded = internal.replace(/-/g, '+').replace(/_/g, '/');
+      returnPathname = JSON.parse(atob(decoded)).returnPathname;
+    } catch {
+      // Malformed internal part, ignore it
+    }
+  } else if (state) {
+    try {
+      const decoded = JSON.parse(atob(state));
+      if (decoded.returnPathname) {
+        returnPathname = decoded.returnPathname;
+      } else {
+        userState = state;
+      }
+    } catch {
+      userState = state;
+    }
+  }
+  return {
+    returnPathname,
+    state: userState,
+  };
+}
+
 export function handleAuth(options: HandleAuthOptions = {}) {
   const { returnPathname: returnPathnameOption = '/', baseURL, onSuccess, onError } = options;
 
@@ -20,7 +51,8 @@ export function handleAuth(options: HandleAuthOptions = {}) {
   return async function GET(request: NextRequest) {
     const code = request.nextUrl.searchParams.get('code');
     const state = request.nextUrl.searchParams.get('state');
-    let returnPathname = state && state !== 'null' ? JSON.parse(atob(state)).returnPathname : null;
+
+    const { state: customState, returnPathname: returnPathnameState } = handleState(state);
 
     if (code) {
       try {
@@ -41,7 +73,7 @@ export function handleAuth(options: HandleAuthOptions = {}) {
         url.searchParams.delete('state');
 
         // Redirect to the requested path and store the session
-        returnPathname = returnPathname ?? returnPathnameOption;
+        const returnPathname = returnPathnameState ?? returnPathnameOption;
 
         // Extract the search params if they are present
         if (returnPathname.includes('?')) {
@@ -72,6 +104,7 @@ export function handleAuth(options: HandleAuthOptions = {}) {
             oauthTokens,
             authenticationMethod,
             organizationId,
+            state: customState,
           });
         }
 

package/src/get-authorization-url.ts

@@ -12,13 +12,21 @@ async function getAuthorizationUrl(options: GetAuthURLOptions = {}) {
     redirectUri = headersList.get('x-redirect-uri'),
     loginHint,
     prompt,
+    state: customState,
   } = options;
 
+  const internalState = returnPathname
+    ? btoa(JSON.stringify({ returnPathname })).replace(/\+/g, '-').replace(/\//g, '_')
+    : null;
+
+  const finalState =
+    internalState && customState ? `${internalState}.${customState}` : internalState || customState || undefined;
+
   return getWorkOS().userManagement.getAuthorizationUrl({
     provider: 'authkit',
     clientId: WORKOS_CLIENT_ID,
     redirectUri: redirectUri ?? WORKOS_REDIRECT_URI,
-    state: returnPathname ? btoa(JSON.stringify({ returnPathname })) : undefined,
+    state: finalState,
     screenHint,
     organizationId,
     loginHint,

package/src/interfaces.ts

@@ -12,6 +12,7 @@ export interface HandleAuthSuccessData extends Session {
   oauthTokens?: OauthTokens;
   organizationId?: string;
   authenticationMethod?: AuthenticationResponse['authenticationMethod'];
+  state?: string | undefined;
 }
 
 export interface Impersonator {
@@ -67,6 +68,7 @@ export interface GetAuthURLOptions {
   redirectUri?: string;
   loginHint?: string;
   prompt?: 'consent';
+  state?: string;
 }
 
 export interface AuthkitMiddlewareAuth {

package/src/session.spec.ts

@@ -42,6 +42,10 @@ describe('session.ts', () => {
       profilePictureUrl: null,
       firstName: null,
       lastName: null,
+      lastSignInAt: null,
+      locale: null,
+      externalId: null,
+      metadata: {},
       createdAt: '2024-01-01',
       updatedAt: '2024-01-01',
     } as User,
@@ -146,7 +150,12 @@ describe('session.ts', () => {
 
       await withAuth({ ensureSignedIn: true });
 
-      const pathname = encodeURIComponent(btoa(JSON.stringify({ returnPathname: '/protected?test=123' })));
+      // URL-safe base64 encoding
+      const pathname = encodeURIComponent(
+        btoa(JSON.stringify({ returnPathname: '/protected?test=123' }))
+          .replace(/\+/g, '-')
+          .replace(/\//g, '_'),
+      );
 
       expect(redirect).toHaveBeenCalledWith(expect.stringContaining(pathname));
     });

package/src/test-helpers.ts

@@ -43,6 +43,7 @@ export async function generateSession(overrides: Partial<User> = {}) {
     createdAt: '2024-01-01T00:00:00Z',
     updatedAt: '2024-01-01T00:00:00Z',
     lastSignInAt: '2024-01-01T00:00:00Z',
+    locale: null,
     externalId: null,
     metadata: {},
     ...overrides,

package/src/workos.ts

@@ -2,7 +2,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.9.0';
+export const VERSION = '2.10.0';
 
 const options = {
   apiHostname: WORKOS_API_HOSTNAME,