@workos-inc/authkit-nextjs 2.12.2 → 2.14.0

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
@@ -142,31 +142,41 @@ The `onSuccess` callback receives the following data:
 
 **Note**: `authenticationMethod` is only provided during the initial authentication callback. It will not be available in subsequent requests or session refreshes.
 
-### Middleware / Proxy
+### Proxy / Middleware
 
-This library relies on Next.js middleware to provide session management for routes.
+This library relies on Next.js proxy (called "middleware" in Next.js ≤15) to provide session management for routes.
 
-**For Next.js ≤15:** Create a `middleware.ts` file in the root of your project.
 **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.
 
-The code remains the same; only the filename changes:
+The code remains the same; only the filename and export name differ:
 
 ```ts
+// proxy.ts (Next.js 16+) or middleware.ts (Next.js ≤15)
 import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
 
 export default authkitMiddleware();
+// For Next.js 16+, you can also use: export { default as proxy } from './proxy';
 
 // 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. |
@@ -183,12 +193,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`
@@ -220,7 +341,7 @@ 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;
 
@@ -503,16 +624,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';
@@ -539,7 +660,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
@@ -547,7 +668,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';
@@ -601,62 +722,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.
-
-> **Note:** For Next.js 16+, name your file `proxy.ts` and the function `proxy` instead of `middleware`.
-
-```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');
-    return NextResponse.redirect(authorizationUrl);
-  }
-
-  // Forward the incoming request headers (mitigation) and pass AuthKit headers as request headers
-  const response = NextResponse.next({
-    request: { headers: authkitHeaders },
-  });
-
-  // Copy Set-Cookie and cache control headers to the response, but exclude the internal
-  // x-workos-session header which contains encrypted session data and should never appear
-  // in HTTP responses (it's only used to pass session data between middleware and page handlers)
-  for (const [key, value] of authkitHeaders) {
-    if (key.toLowerCase() === 'x-workos-session') {
-      continue; // Internal header - must not leak to response
-    }
-    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".
@@ -818,7 +883,7 @@ The library automatically sets appropriate cache headers on all authenticated re
 - `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 middleware result caching
+- `x-middleware-cache: no-cache` - Prevents Next.js proxy/middleware result caching
 
 These headers are applied automatically when:
 
@@ -834,7 +899,7 @@ These headers are applied automatically when:
 
 ### 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';

package/dist/esm/errors.js

@@ -0,0 +1,33 @@
+import { decodeJwt } from './jwt.js';
+export class AuthKitError extends Error {
+    constructor(message, cause, data) {
+        super(message);
+        this.name = 'AuthKitError';
+        this.cause = cause;
+        this.data = data;
+    }
+}
+export class TokenRefreshError extends AuthKitError {
+    constructor(message, cause, context) {
+        super(message, cause);
+        this.name = 'TokenRefreshError';
+        this.userId = context === null || context === void 0 ? void 0 : context.userId;
+        this.sessionId = context === null || context === void 0 ? void 0 : context.sessionId;
+    }
+}
+export function getSessionErrorContext(session) {
+    if (!(session === null || session === void 0 ? void 0 : session.accessToken)) {
+        return {};
+    }
+    try {
+        const { payload } = decodeJwt(session.accessToken);
+        return {
+            userId: payload.sub,
+            sessionId: payload.sid,
+        };
+    }
+    catch (_a) {
+        return {};
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGrC,YAAY,OAAe,EAAE,KAAe,EAAE,IAA8B;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAOD,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IAIjD,YAAY,OAAe,EAAE,KAAe,EAAE,OAAkC;QAC9E,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,CAAC;IACtC,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAwB;IAC7D,IAAI,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,CAAA,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACnD,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,GAAG;YACnB,SAAS,EAAE,OAAO,CAAC,GAAG;SACvB,CAAC;IACJ,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

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

@@ -2,8 +2,13 @@ import { getWorkOS } from './workos.js';
 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, state: customState, } = options;
+    var _a;
+    const { returnPathname, screenHint, organizationId, loginHint, prompt, state: customState } = options;
+    let redirectUri = options.redirectUri;
+    if (!redirectUri) {
+        const headersList = await headers();
+        redirectUri = (_a = headersList.get('x-redirect-uri')) !== null && _a !== void 0 ? _a : undefined;
+    }
     const internalState = returnPathname
         ? btoa(JSON.stringify({ returnPathname })).replace(/\+/g, '-').replace(/\//g, '_')
         : null;

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,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"}
+{"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,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IACtG,IAAI,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACtC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAC;QACpC,WAAW,GAAG,MAAA,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC,mCAAI,SAAS,CAAC;IAC/D,CAAC;IAED,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/index.js

@@ -1,9 +1,11 @@
 import { getSignInUrl, getSignUpUrl, signOut, switchToOrganization } from './auth.js';
 import { handleAuth } from './authkit-callback-route.js';
+import { AuthKitError, TokenRefreshError } from './errors.js';
 import { authkit, authkitMiddleware } from './middleware.js';
+export { applyResponseHeaders, handleAuthkitHeaders, partitionAuthkitHeaders, isAuthkitRequestHeader, AUTHKIT_REQUEST_HEADERS, } from './middleware-helpers.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
 import { getWorkOS } from './workos.js';
 export * from './interfaces.js';
-export { authkit, authkitMiddleware, getSignInUrl, getSignUpUrl, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, withAuth, getTokenClaims, validateApiKey, };
+export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, getSignInUrl, getSignUpUrl, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,cAAc,iBAAiB,CAAC;AAEhC,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,cAAc,GACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,GAKxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,cAAc,iBAAiB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,SAAS,EACT,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,cAAc,EACd,QAAQ,GACT,CAAC"}

package/dist/esm/middleware-helpers.js

@@ -0,0 +1,99 @@
+import { NextResponse } from 'next/server';
+/** Internal AuthKit headers - forwarded to downstream requests but never sent to browser. */
+export const AUTHKIT_REQUEST_HEADERS = [
+    'x-workos-middleware',
+    'x-url',
+    'x-redirect-uri',
+    'x-sign-up-paths',
+    'x-workos-session',
+];
+const ALLOWED_RESPONSE_HEADERS = [
+    'set-cookie',
+    'cache-control',
+    'vary',
+    'www-authenticate',
+    'proxy-authenticate',
+    'link',
+    'x-middleware-cache',
+];
+const MULTI_VALUE_HEADERS = ['set-cookie', 'www-authenticate', 'proxy-authenticate', 'link'];
+export function isAuthkitRequestHeader(name) {
+    const lower = name.toLowerCase();
+    return AUTHKIT_REQUEST_HEADERS.includes(lower) || lower.startsWith('x-workos-');
+}
+function setHeader(headers, name, value) {
+    const lower = name.toLowerCase();
+    if (MULTI_VALUE_HEADERS.includes(lower)) {
+        headers.append(name, value);
+    }
+    else if (lower === 'vary') {
+        const existing = headers.get(name);
+        const merged = new Set([
+            ...(existing ? existing.split(',').map((v) => v.trim()) : []),
+            ...value.split(',').map((v) => v.trim()),
+        ]);
+        headers.set(name, [...merged].join(', '));
+    }
+    else {
+        headers.set(name, value);
+    }
+}
+/**
+ * Partitions AuthKit headers into request headers (for withAuth) and response headers (for browser).
+ */
+export function partitionAuthkitHeaders(request, authkitHeaders) {
+    const headers = new Headers(authkitHeaders);
+    const requestHeaders = new Headers(request.headers);
+    // Strip any client-injected authkit headers, then apply trusted ones
+    for (const name of [...requestHeaders.keys()]) {
+        if (isAuthkitRequestHeader(name)) {
+            requestHeaders.delete(name);
+        }
+    }
+    for (const headerName of AUTHKIT_REQUEST_HEADERS) {
+        const value = headers.get(headerName);
+        if (value != null) {
+            requestHeaders.set(headerName, value);
+        }
+    }
+    // Build response headers from allowlist only
+    const responseHeaders = new Headers();
+    for (const [name, value] of headers) {
+        const lower = name.toLowerCase();
+        if (!isAuthkitRequestHeader(lower) && ALLOWED_RESPONSE_HEADERS.includes(lower)) {
+            setHeader(responseHeaders, name, value);
+        }
+    }
+    // Auto-add cache-control when setting cookies
+    if (responseHeaders.has('set-cookie') && !responseHeaders.has('cache-control')) {
+        responseHeaders.set('cache-control', 'no-store');
+    }
+    return { requestHeaders, responseHeaders };
+}
+export function applyResponseHeaders(response, responseHeaders) {
+    for (const [name, value] of responseHeaders) {
+        setHeader(response.headers, name, value);
+    }
+    return response;
+}
+/**
+ * Creates a NextResponse with properly merged AuthKit headers.
+ */
+export function handleAuthkitHeaders(request, authkitHeaders, options = {}) {
+    const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+    const { redirect, redirectStatus } = options;
+    if (redirect != null && redirect !== '') {
+        let redirectUrl;
+        try {
+            redirectUrl = redirect instanceof URL ? redirect : new URL(redirect, request.url);
+        }
+        catch (_a) {
+            throw new Error(`Invalid redirect URL: "${redirect}". Must be a valid absolute or relative URL.`);
+        }
+        const method = request.method.toUpperCase();
+        const status = redirectStatus !== null && redirectStatus !== void 0 ? redirectStatus : (method === 'GET' || method === 'HEAD' ? 307 : 303);
+        return applyResponseHeaders(NextResponse.redirect(redirectUrl, status), responseHeaders);
+    }
+    return applyResponseHeaders(NextResponse.next({ request: { headers: requestHeaders } }), responseHeaders);
+}
+//# sourceMappingURL=middleware-helpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-helpers.js","sourceRoot":"","sources":["../../src/middleware-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,qBAAqB;IACrB,OAAO;IACP,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;CACV,CAAC;AAIX,MAAM,wBAAwB,GAAsB;IAClD,YAAY;IACZ,eAAe;IACf,MAAM;IACN,kBAAkB;IAClB,oBAAoB;IACpB,MAAM;IACN,oBAAoB;CACrB,CAAC;AAEF,MAAM,mBAAmB,GAAsB,CAAC,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,CAAC,CAAC;AAEhH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,OAAQ,uBAA6C,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AACzG,CAAC;AAED,SAAS,SAAS,CAAC,OAAgB,EAAE,IAAY,EAAE,KAAa;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,mBAAmB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;SAAM,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC;YACrB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACzC,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAoB,EAAE,cAAuB;IACnF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,cAAc,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpD,qEAAqE;IACrE,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9C,IAAI,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,KAAK,MAAM,UAAU,IAAI,uBAAuB,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,MAAM,eAAe,GAAG,IAAI,OAAO,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,IAAI,wBAAwB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/E,SAAS,CAAC,eAAe,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,IAAI,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QAC/E,eAAe,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAsB,EAAE,eAAwB;IACnF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,eAAe,EAAE,CAAC;QAC5C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAYD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAoB,EACpB,cAAuB,EACvB,UAAuC,EAAE;IAEzC,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,uBAAuB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC7F,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAE7C,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACxC,IAAI,WAAgB,CAAC;QACrB,IAAI,CAAC;YACH,WAAW,GAAG,QAAQ,YAAY,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QACpF,CAAC;QAAC,WAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,8CAA8C,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,cAAc,aAAd,cAAc,cAAd,cAAc,GAAI,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACrF,OAAO,oBAAoB,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO,oBAAoB,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;AAC5G,CAAC"}

package/dist/esm/session.js

@@ -3,13 +3,14 @@ import { sealData, unsealData } from 'iron-session';
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
-import { NextResponse } from 'next/server';
 import { getCookieOptions, getJwtCookie } from './cookie.js';
 import { WORKOS_CLIENT_ID, WORKOS_COOKIE_NAME, WORKOS_COOKIE_PASSWORD, WORKOS_REDIRECT_URI } from './env-variables.js';
+import { TokenRefreshError, getSessionErrorContext } from './errors.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import { getWorkOS } from './workos.js';
 import { parse, tokensToRegexp } from 'path-to-regexp';
-import { lazy, redirectWithFallback, setCachePreventionHeaders } from './utils.js';
+import { handleAuthkitHeaders } from './middleware-helpers.js';
+import { lazy, setCachePreventionHeaders } from './utils.js';
 const sessionHeaderName = 'x-workos-session';
 const middlewareHeaderName = 'x-workos-middleware';
 const signUpPathsHeaderName = 'x-sign-up-paths';
@@ -100,42 +101,19 @@ async function updateSessionMiddleware(request, debug, middlewareAuth, redirectU
         screenHint: getScreenHint(signUpPaths, request.nextUrl.pathname),
         eagerAuth,
     });
-    // If the user is logged out and this path isn't on the allowlist for logged out paths, redirect to AuthKit.
-    if (middlewareAuth.enabled && matchedPaths.length === 0 && !session.user) {
-        if (debug) {
-            console.log(`Unauthenticated user on protected route ${request.url}, redirecting to AuthKit`);
-        }
-        return redirectWithFallback(authorizationUrl, headers);
-    }
     // Record the sign up paths so we can use them later
     if (signUpPaths.length > 0) {
         headers.set(signUpPathsHeaderName, signUpPaths.join(','));
     }
     applyCacheSecurityHeaders(headers, request, session);
-    // Create a new request with modified headers (for page handlers)
-    const requestHeaders = new Headers(request.headers);
-    requestHeaders.set(middlewareHeaderName, headers.get(middlewareHeaderName));
-    requestHeaders.set('x-url', headers.get('x-url'));
-    if (headers.has('x-redirect-uri')) {
-        requestHeaders.set('x-redirect-uri', headers.get('x-redirect-uri'));
-    }
-    if (headers.has(signUpPathsHeaderName)) {
-        requestHeaders.set(signUpPathsHeaderName, headers.get(signUpPathsHeaderName));
-    }
-    // Pass session to page handlers via request header
-    // This ensures handlers see refreshed sessions immediately (before Set-Cookie reaches browser)
-    const sessionHeader = headers.get(sessionHeaderName);
-    if (sessionHeader) {
-        requestHeaders.set(sessionHeaderName, sessionHeader);
+    // If the user is logged out and this path isn't on the allowlist for logged out paths, redirect to AuthKit.
+    if (middlewareAuth.enabled && matchedPaths.length === 0 && !session.user) {
+        if (debug) {
+            console.log(`Unauthenticated user on protected route ${request.url}, redirecting to AuthKit`);
+        }
+        return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl });
     }
-    // Remove session header from response headers to prevent leakage
-    headers.delete(sessionHeaderName);
-    return NextResponse.next({
-        request: {
-            headers: requestHeaders,
-        },
-        headers,
-    });
+    return handleAuthkitHeaders(request, headers);
 }
 async function updateSession(request, options = { debug: false }) {
     var _a, _b;
@@ -288,9 +266,7 @@ async function refreshSession({ organizationId: nextOrganizationId, ensureSigned
         });
     }
     catch (error) {
-        throw new Error(`Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`, {
-            cause: error,
-        });
+        throw new TokenRefreshError(`Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`, error, getSessionErrorContext(session));
     }
     const headersList = await headers();
     const url = headersList.get('x-url');