@imtbl/auth-next-server 2.12.7-alpha.1 → 2.12.7-alpha.10

package/README.md

@@ -7,6 +7,7 @@ Server-side utilities for Immutable authentication with Auth.js v5 (NextAuth) in
 This package provides server-side authentication utilities for Next.js applications using the App Router. It integrates with Auth.js v5 to handle OAuth authentication with Immutable's identity provider.
 
 **Key features:**
+
 - Auth.js v5 configuration for Immutable authentication
 - Route protection via middleware
 - Server utilities for authenticated data fetching
@@ -40,10 +41,12 @@ Create a file to configure Immutable authentication:
 import NextAuth from "next-auth";
 import { createAuthConfig } from "@imtbl/auth-next-server";
 
-export const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig({
-  clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
-  redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
-}));
+export const { handlers, auth, signIn, signOut } = NextAuth(
+  createAuthConfig({
+    clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+    redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+  }),
+);
 ```
 
 ### 2. Set Up API Route
@@ -76,27 +79,29 @@ Creates an Auth.js v5 configuration object for Immutable authentication. You pas
 import NextAuth from "next-auth";
 import { createAuthConfig } from "@imtbl/auth-next-server";
 
-const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig({
-  // Required
-  clientId: "your-client-id",
-  redirectUri: "https://your-app.com/callback",
-  
-  // Optional
-  audience: "platform_api",                           // Default: "platform_api"
-  scope: "openid profile email offline_access transact", // Default scope
-  authenticationDomain: "https://auth.immutable.com", // Default domain
-}));
+const { handlers, auth, signIn, signOut } = NextAuth(
+  createAuthConfig({
+    // Required
+    clientId: "your-client-id",
+    redirectUri: "https://your-app.com/callback",
+
+    // Optional
+    audience: "platform_api", // Default: "platform_api"
+    scope: "openid profile email offline_access transact", // Default scope
+    authenticationDomain: "https://auth.immutable.com", // Default domain
+  }),
+);
 ```
 
 #### Configuration Options
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `clientId` | `string` | Yes | Your Immutable application client ID |
-| `redirectUri` | `string` | Yes | OAuth redirect URI configured in Immutable Hub |
-| `audience` | `string` | No | OAuth audience (default: `"platform_api"`) |
-| `scope` | `string` | No | OAuth scopes (default: `"openid profile email offline_access transact"`) |
-| `authenticationDomain` | `string` | No | Auth domain (default: `"https://auth.immutable.com"`) |
+| Option                 | Type     | Required | Description                                                              |
+| ---------------------- | -------- | -------- | ------------------------------------------------------------------------ |
+| `clientId`             | `string` | Yes      | Your Immutable application client ID                                     |
+| `redirectUri`          | `string` | Yes      | OAuth redirect URI configured in Immutable Hub                           |
+| `audience`             | `string` | No       | OAuth audience (default: `"platform_api"`)                               |
+| `scope`                | `string` | No       | OAuth scopes (default: `"openid profile email offline_access transact"`) |
+| `authenticationDomain` | `string` | No       | Auth domain (default: `"https://auth.immutable.com"`)                    |
 
 #### Extending the Configuration
 
@@ -117,19 +122,20 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
   secret: process.env.AUTH_SECRET,
   trustHost: true,
   basePath: "/api/auth/custom",
-  
+
   // Extend callbacks (be sure to call the base callbacks first)
   callbacks: {
     ...baseConfig.callbacks,
     async jwt(params) {
       // Call base jwt callback first
-      const token = await baseConfig.callbacks?.jwt?.(params) ?? params.token;
+      const token = (await baseConfig.callbacks?.jwt?.(params)) ?? params.token;
       // Add your custom logic
       return token;
     },
     async session(params) {
       // Call base session callback first
-      const session = await baseConfig.callbacks?.session?.(params) ?? params.session;
+      const session =
+        (await baseConfig.callbacks?.session?.(params)) ?? params.session;
       // Add your custom logic
       return session;
     },
@@ -141,18 +147,19 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
 
 This package provides several utilities for handling authentication in Server Components. Choose the right one based on your needs:
 
-| Utility | Use Case | Data Fetching | Error Handling |
-|---------|----------|---------------|----------------|
-| `getAuthProps` | Pass auth state to client, fetch data client-side | No | Manual |
-| `getAuthenticatedData` | SSR data fetching with client fallback | Yes | Manual |
-| `createProtectedFetchers` | Multiple pages with same error handling | Optional | Centralized |
-| `getValidSession` | Custom logic for each auth state | No | Manual (detailed) |
+| Utility                   | Use Case                                          | Data Fetching | Error Handling    |
+| ------------------------- | ------------------------------------------------- | ------------- | ----------------- |
+| `getAuthProps`            | Pass auth state to client, fetch data client-side | No            | Manual            |
+| `getAuthenticatedData`    | SSR data fetching with client fallback            | Yes           | Manual            |
+| `createProtectedFetchers` | Multiple pages with same error handling           | Optional      | Centralized       |
+| `getValidSession`         | Custom logic for each auth state                  | No            | Manual (detailed) |
 
 ### `getAuthProps(auth)`
 
 **Use case:** You want to pass authentication state to a Client Component but handle data fetching entirely on the client side. This is the simplest approach when your page doesn't need SSR data fetching.
 
 **When to use:**
+
 - Pages where data is fetched client-side (e.g., infinite scroll, real-time updates)
 - Pages that show a loading skeleton while fetching
 - When you want full control over loading states in the client
@@ -167,11 +174,11 @@ import { DashboardClient } from "./DashboardClient";
 
 export default async function DashboardPage() {
   const authProps = await getAuthProps(auth);
-  
+
   if (authProps.authError) {
     redirect("/login");
   }
-  
+
   // DashboardClient will fetch its own data using useImmutableSession().getUser()
   return <DashboardClient {...authProps} />;
 }
@@ -182,11 +189,13 @@ export default async function DashboardPage() {
 **Use case:** You want to fetch data server-side for faster initial page loads (SSR), but gracefully fall back to client-side fetching when the token is expired.
 
 **When to use:**
+
 - Pages that benefit from SSR (SEO, faster first paint)
 - Profile pages, settings pages, or any page showing user-specific data
 - When you want the best of both worlds: SSR when possible, CSR as fallback
 
 **How it works:**
+
 1. If token is valid → fetches data server-side, returns `ssr: true`
 2. If token is expired → skips fetch, returns `ssr: false`, client refreshes and fetches
 3. Pair with `useHydratedData` hook on the client for seamless handling
@@ -208,11 +217,11 @@ async function fetchUserProfile(accessToken: string) {
 
 export default async function ProfilePage() {
   const result = await getAuthenticatedData(auth, fetchUserProfile);
-  
+
   if (result.authError) {
     redirect("/login");
   }
-  
+
   // ProfileClient uses useHydratedData() to handle both SSR data and client fallback
   return <ProfileClient {...result} />;
 }
@@ -223,11 +232,13 @@ export default async function ProfilePage() {
 **Use case:** You have multiple protected pages and want to define auth error handling once, rather than repeating `if (authError) redirect(...)` on every page.
 
 **When to use:**
+
 - Apps with many protected pages sharing the same error handling logic
 - When you want DRY (Don't Repeat Yourself) error handling
 - Teams that want consistent auth error behavior across the app
 
 **How it works:**
+
 - Define error handling once in a shared file
 - Use the returned `getAuthProps` and `getData` functions in your pages
 - Auth errors automatically trigger your handler (no manual checking needed)
@@ -245,7 +256,7 @@ export const { getAuthProps, getData } = createProtectedFetchers(
   (error) => {
     // This runs automatically when there's an auth error (e.g., RefreshTokenError)
     redirect(`/login?error=${error}`);
-  }
+  },
 );
 ```
 
@@ -259,7 +270,7 @@ export default async function DashboardPage() {
   const result = await getData(async (token) => {
     return fetchDashboardData(token);
   });
-  
+
   return <DashboardClient {...result} />;
 }
 ```
@@ -281,6 +292,7 @@ export default async function SettingsPage() {
 **Use case:** You need fine-grained control over different authentication states and want to handle each case with custom logic.
 
 **When to use:**
+
 - Complex pages that render completely different UI based on auth state
 - When you need to distinguish between "token expired" vs "not authenticated"
 - Analytics or logging that needs to track specific auth states
@@ -294,22 +306,22 @@ import { getValidSession } from "@imtbl/auth-next-server";
 
 export default async function AccountPage() {
   const result = await getValidSession(auth);
-  
+
   switch (result.status) {
     case "authenticated":
       // Full access - render the complete account page with SSR data
       const userData = await fetchUserData(result.session.accessToken);
       return <FullAccountPage user={userData} />;
-      
+
     case "token_expired":
       // Token expired but user has session - show skeleton, let client refresh
       // This avoids a flash of "please login" for users who are actually logged in
       return <AccountPageSkeleton session={result.session} />;
-      
+
     case "unauthenticated":
       // No session at all - show login prompt or redirect
       return <LoginPrompt message="Sign in to view your account" />;
-      
+
     case "error":
       // Auth system error (e.g., refresh token revoked) - needs re-login
       return <AuthErrorPage error={result.error} />;
@@ -324,11 +336,13 @@ export default async function AccountPage() {
 **Use case:** Protect entire sections of your app at the routing level, before pages even render. This is the most efficient way to block unauthenticated access.
 
 **When to use:**
+
 - You have groups of pages that all require authentication (e.g., `/dashboard/*`, `/settings/*`)
 - You want to redirect unauthenticated users before any page code runs
 - You need consistent protection across many routes without adding checks to each page
 
 **When NOT to use:**
+
 - Pages that show different content for authenticated vs unauthenticated users (use page-level checks instead)
 - Public pages with optional authenticated features
 
@@ -352,17 +366,18 @@ export const config = {
 
 #### Middleware Options
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `loginUrl` | `string` | URL to redirect unauthenticated users (default: `"/login"`) |
-| `protectedPaths` | `(string \| RegExp)[]` | Paths that require authentication |
-| `publicPaths` | `(string \| RegExp)[]` | Paths that skip authentication (takes precedence) |
+| Option           | Type                   | Description                                                 |
+| ---------------- | ---------------------- | ----------------------------------------------------------- |
+| `loginUrl`       | `string`               | URL to redirect unauthenticated users (default: `"/login"`) |
+| `protectedPaths` | `(string \| RegExp)[]` | Paths that require authentication                           |
+| `publicPaths`    | `(string \| RegExp)[]` | Paths that skip authentication (takes precedence)           |
 
 ### `withAuth(auth, handler)`
 
 **Use case:** Protect individual API Route Handlers or Server Actions. Ensures the handler only runs for authenticated users.
 
 **When to use:**
+
 - API routes that should only be accessible to authenticated users
 - Server Actions (form submissions, mutations) that require authentication
 - When you need the session/user info inside the handler
@@ -394,11 +409,11 @@ import { auth } from "@/lib/auth";
 import { withAuth } from "@imtbl/auth-next-server";
 
 export const transferAsset = withAuth(
-  auth, 
+  auth,
   async (session, formData: FormData) => {
     const assetId = formData.get("assetId") as string;
     const toAddress = formData.get("toAddress") as string;
-    
+
     // Use session.user.sub to identify the sender
     // Use session.accessToken to call Immutable APIs
     const result = await executeTransfer({
@@ -407,9 +422,9 @@ export const transferAsset = withAuth(
       assetId,
       accessToken: session.accessToken,
     });
-    
+
     return result;
-  }
+  },
 );
 ```
 
@@ -420,22 +435,24 @@ The package augments the Auth.js `Session` type with Immutable-specific fields:
 ```typescript
 interface Session {
   user: {
-    sub: string;        // Immutable user ID
+    sub: string; // Immutable user ID
     email?: string;
     nickname?: string;
   };
   accessToken: string;
   refreshToken?: string;
-  idToken?: string;
+  idToken?: string; // Only present transiently after sign-in or token refresh (not stored in cookie)
   accessTokenExpires: number;
   zkEvm?: {
     ethAddress: string;
     userAdminAddress: string;
   };
-  error?: string;       // "TokenExpired" or "RefreshTokenError"
+  error?: string; // "TokenExpired" or "RefreshTokenError"
 }
 ```
 
+> **Note:** The `idToken` is **not** stored in the session cookie. It is stripped by a custom `jwt.encode` to keep cookie size under CDN header limits. The `idToken` is only present in the session response transiently after sign-in or token refresh. On the client, `@imtbl/auth-next-client` automatically persists it in `localStorage` so that wallet operations (via `getUser()`) can always access it. All data extracted from the idToken (`email`, `nickname`, `zkEvm`) remains in the cookie as separate fields.
+
 ## Token Refresh
 
 ### Automatic Refresh on Token Expiry
@@ -453,10 +470,10 @@ import { useImmutableSession } from "@imtbl/auth-next-client";
 
 function MyComponent() {
   const { getUser } = useImmutableSession();
-  
+
   const handleRegistration = async () => {
     // After zkEVM registration completes...
-    
+
     // Force refresh to get updated zkEvm claims from IDP
     const freshUser = await getUser(true);
     console.log("Updated zkEvm:", freshUser?.zkEvm);
@@ -465,6 +482,7 @@ function MyComponent() {
 ```
 
 When `forceRefresh` is triggered:
+
 1. Client calls `update({ forceRefresh: true })` via NextAuth
 2. The `jwt` callback detects `trigger === 'update'` with `forceRefresh: true`
 3. Server performs a token refresh using the refresh token
@@ -476,10 +494,10 @@ When `forceRefresh` is triggered:
 The package also exports utilities for manual token handling:
 
 ```typescript
-import { 
-  isTokenExpired,         // Check if access token is expired
-  refreshAccessToken,     // Manually refresh tokens
-  extractZkEvmFromIdToken // Extract zkEvm claims from ID token
+import {
+  isTokenExpired, // Check if access token is expired
+  refreshAccessToken, // Manually refresh tokens
+  extractZkEvmFromIdToken, // Extract zkEvm claims from ID token
 } from "@imtbl/auth-next-server";
 ```
 
@@ -487,10 +505,10 @@ import {
 
 The session may contain an `error` field indicating authentication issues:
 
-| Error | Description | Recommended Action |
-|-------|-------------|-------------------|
-| `"TokenExpired"` | Access token expired, refresh token may be valid | Let client refresh via `@imtbl/auth-next-client` |
-| `"RefreshTokenError"` | Refresh token invalid/expired | Redirect to login |
+| Error                 | Description                                      | Recommended Action                               |
+| --------------------- | ------------------------------------------------ | ------------------------------------------------ |
+| `"TokenExpired"`      | Access token expired, refresh token may be valid | Let client refresh via `@imtbl/auth-next-client` |
+| `"RefreshTokenError"` | Refresh token invalid/expired                    | Redirect to login                                |
 
 ## TypeScript
 

package/dist/node/index.cjs

@@ -60,6 +60,7 @@ var import_next_auth = __toESM(require("next-auth"), 1);
 
 // src/config.ts
 var import_credentials = __toESM(require("next-auth/providers/credentials"), 1);
+var import_jwt = require("next-auth/jwt");
 
 // src/constants.ts
 var DEFAULT_AUTH_DOMAIN = "https://auth.immutable.com";
@@ -148,6 +149,7 @@ async function refreshAccessToken(refreshToken, clientId, authDomain = DEFAULT_A
 
 // src/config.ts
 var Credentials = import_credentials.default.default || import_credentials.default;
+var defaultJwtEncode = import_jwt.encode.default || import_jwt.encode;
 async function validateTokens(accessToken, authDomain) {
   try {
     const response = await fetch(`${authDomain}/userinfo`, {
@@ -169,6 +171,22 @@ async function validateTokens(accessToken, authDomain) {
 function createAuthConfig(config) {
   const authDomain = config.authenticationDomain || DEFAULT_AUTH_DOMAIN;
   return {
+    // Custom jwt.encode: strip idToken from the cookie to reduce size and avoid
+    // CloudFront 413 "Request Entity Too Large" errors. The idToken (~1-2 KB) is
+    // still available in session responses (after sign-in or token refresh) because
+    // the session callback runs BEFORE encode. All data extracted FROM idToken
+    // (email, nickname, zkEvm) remains in the cookie as separate fields.
+    // On the client, idToken is persisted in localStorage by @imtbl/auth-next-client.
+    jwt: {
+      async encode(params) {
+        const { token, ...rest } = params;
+        if (token) {
+          const { idToken, ...cookieToken } = token;
+          return defaultJwtEncode({ ...rest, token: cookieToken });
+        }
+        return defaultJwtEncode(params);
+      }
+    },
     providers: [
       Credentials({
         id: IMMUTABLE_PROVIDER_ID,
@@ -227,22 +245,63 @@ function createAuthConfig(config) {
         trigger,
         session: sessionUpdate
       }) {
-        if (user) {
-          return {
-            ...token,
-            sub: user.sub,
-            email: user.email,
-            nickname: user.nickname,
-            accessToken: user.accessToken,
-            refreshToken: user.refreshToken,
-            idToken: user.idToken,
-            accessTokenExpires: user.accessTokenExpires,
-            zkEvm: user.zkEvm
-          };
-        }
-        if (trigger === "update" && sessionUpdate) {
-          const update = sessionUpdate;
-          if (update.forceRefresh && token.refreshToken) {
+        try {
+          if (user) {
+            return {
+              ...token,
+              sub: user.sub,
+              email: user.email,
+              nickname: user.nickname,
+              accessToken: user.accessToken,
+              refreshToken: user.refreshToken,
+              idToken: user.idToken,
+              accessTokenExpires: user.accessTokenExpires,
+              zkEvm: user.zkEvm
+            };
+          }
+          if (trigger === "update" && sessionUpdate) {
+            const update = sessionUpdate;
+            if (update.forceRefresh && token.refreshToken) {
+              try {
+                const refreshed = await refreshAccessToken(
+                  token.refreshToken,
+                  config.clientId,
+                  authDomain
+                );
+                const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
+                return {
+                  ...token,
+                  accessToken: refreshed.accessToken,
+                  refreshToken: refreshed.refreshToken,
+                  idToken: refreshed.idToken,
+                  accessTokenExpires: refreshed.accessTokenExpires,
+                  zkEvm: zkEvm ?? token.zkEvm,
+                  // Keep existing zkEvm if not in new token
+                  error: void 0
+                };
+              } catch (error) {
+                console.error("[auth-next-server] Force refresh failed:", error);
+                return {
+                  ...token,
+                  error: "RefreshTokenError"
+                };
+              }
+            }
+            return {
+              ...token,
+              ...update.accessToken ? { accessToken: update.accessToken } : {},
+              ...update.refreshToken ? { refreshToken: update.refreshToken } : {},
+              ...update.idToken ? { idToken: update.idToken } : {},
+              ...update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {},
+              ...update.zkEvm ? { zkEvm: update.zkEvm } : {},
+              // Clear any stale error when valid tokens are synced from client-side
+              error: void 0
+            };
+          }
+          if (!isTokenExpired(token.accessTokenExpires)) {
+            return token;
+          }
+          if (token.refreshToken) {
             try {
               const refreshed = await refreshAccessToken(
                 token.refreshToken,
@@ -259,9 +318,10 @@ function createAuthConfig(config) {
                 zkEvm: zkEvm ?? token.zkEvm,
                 // Keep existing zkEvm if not in new token
                 error: void 0
+                // Clear any previous error
               };
             } catch (error) {
-              console.error("[auth-next-server] Force refresh failed:", error);
+              console.error("[auth-next-server] Token refresh failed:", error);
               return {
                 ...token,
                 error: "RefreshTokenError"
@@ -270,67 +330,35 @@ function createAuthConfig(config) {
           }
           return {
             ...token,
-            ...update.accessToken ? { accessToken: update.accessToken } : {},
-            ...update.refreshToken ? { refreshToken: update.refreshToken } : {},
-            ...update.idToken ? { idToken: update.idToken } : {},
-            ...update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {},
-            ...update.zkEvm ? { zkEvm: update.zkEvm } : {},
-            // Clear any stale error when valid tokens are synced from client-side
-            error: void 0
+            error: "TokenExpired"
           };
+        } catch (error) {
+          console.error("[auth-next-server] JWT callback error:", error);
+          throw error;
         }
-        if (!isTokenExpired(token.accessTokenExpires)) {
-          return token;
-        }
-        if (token.refreshToken) {
-          try {
-            const refreshed = await refreshAccessToken(
-              token.refreshToken,
-              config.clientId,
-              authDomain
-            );
-            const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
-            return {
-              ...token,
-              accessToken: refreshed.accessToken,
-              refreshToken: refreshed.refreshToken,
-              idToken: refreshed.idToken,
-              accessTokenExpires: refreshed.accessTokenExpires,
-              zkEvm: zkEvm ?? token.zkEvm,
-              // Keep existing zkEvm if not in new token
-              error: void 0
-              // Clear any previous error
-            };
-          } catch (error) {
-            console.error("[auth-next-server] Token refresh failed:", error);
-            return {
-              ...token,
-              error: "RefreshTokenError"
-            };
-          }
-        }
-        return {
-          ...token,
-          error: "TokenExpired"
-        };
       },
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       async session({ session, token }) {
-        return {
-          ...session,
-          user: {
-            ...session.user,
-            sub: token.sub,
-            email: token.email,
-            nickname: token.nickname
-          },
-          accessToken: token.accessToken,
-          refreshToken: token.refreshToken,
-          idToken: token.idToken,
-          accessTokenExpires: token.accessTokenExpires,
-          zkEvm: token.zkEvm,
-          ...token.error && { error: token.error }
-        };
+        try {
+          return {
+            ...session,
+            user: {
+              ...session.user,
+              sub: token.sub,
+              email: token.email,
+              nickname: token.nickname
+            },
+            accessToken: token.accessToken,
+            refreshToken: token.refreshToken,
+            idToken: token.idToken,
+            accessTokenExpires: token.accessTokenExpires,
+            zkEvm: token.zkEvm,
+            ...token.error && { error: token.error }
+          };
+        } catch (error) {
+          console.error("[auth-next-server] Session callback error:", error);
+          throw error;
+        }
       }
     },
     session: {

package/dist/node/index.js

@@ -13,6 +13,7 @@ import { default as default2 } from "next-auth";
 
 // src/config.ts
 import CredentialsImport from "next-auth/providers/credentials";
+import { encode as encodeImport } from "next-auth/jwt";
 
 // src/constants.ts
 var DEFAULT_AUTH_DOMAIN = "https://auth.immutable.com";
@@ -101,6 +102,7 @@ async function refreshAccessToken(refreshToken, clientId, authDomain = DEFAULT_A
 
 // src/config.ts
 var Credentials = CredentialsImport.default || CredentialsImport;
+var defaultJwtEncode = encodeImport.default || encodeImport;
 async function validateTokens(accessToken, authDomain) {
   try {
     const response = await fetch(`${authDomain}/userinfo`, {
@@ -122,6 +124,22 @@ async function validateTokens(accessToken, authDomain) {
 function createAuthConfig(config) {
   const authDomain = config.authenticationDomain || DEFAULT_AUTH_DOMAIN;
   return {
+    // Custom jwt.encode: strip idToken from the cookie to reduce size and avoid
+    // CloudFront 413 "Request Entity Too Large" errors. The idToken (~1-2 KB) is
+    // still available in session responses (after sign-in or token refresh) because
+    // the session callback runs BEFORE encode. All data extracted FROM idToken
+    // (email, nickname, zkEvm) remains in the cookie as separate fields.
+    // On the client, idToken is persisted in localStorage by @imtbl/auth-next-client.
+    jwt: {
+      async encode(params) {
+        const { token, ...rest } = params;
+        if (token) {
+          const { idToken, ...cookieToken } = token;
+          return defaultJwtEncode({ ...rest, token: cookieToken });
+        }
+        return defaultJwtEncode(params);
+      }
+    },
     providers: [
       Credentials({
         id: IMMUTABLE_PROVIDER_ID,
@@ -180,22 +198,63 @@ function createAuthConfig(config) {
         trigger,
         session: sessionUpdate
       }) {
-        if (user) {
-          return {
-            ...token,
-            sub: user.sub,
-            email: user.email,
-            nickname: user.nickname,
-            accessToken: user.accessToken,
-            refreshToken: user.refreshToken,
-            idToken: user.idToken,
-            accessTokenExpires: user.accessTokenExpires,
-            zkEvm: user.zkEvm
-          };
-        }
-        if (trigger === "update" && sessionUpdate) {
-          const update = sessionUpdate;
-          if (update.forceRefresh && token.refreshToken) {
+        try {
+          if (user) {
+            return {
+              ...token,
+              sub: user.sub,
+              email: user.email,
+              nickname: user.nickname,
+              accessToken: user.accessToken,
+              refreshToken: user.refreshToken,
+              idToken: user.idToken,
+              accessTokenExpires: user.accessTokenExpires,
+              zkEvm: user.zkEvm
+            };
+          }
+          if (trigger === "update" && sessionUpdate) {
+            const update = sessionUpdate;
+            if (update.forceRefresh && token.refreshToken) {
+              try {
+                const refreshed = await refreshAccessToken(
+                  token.refreshToken,
+                  config.clientId,
+                  authDomain
+                );
+                const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
+                return {
+                  ...token,
+                  accessToken: refreshed.accessToken,
+                  refreshToken: refreshed.refreshToken,
+                  idToken: refreshed.idToken,
+                  accessTokenExpires: refreshed.accessTokenExpires,
+                  zkEvm: zkEvm ?? token.zkEvm,
+                  // Keep existing zkEvm if not in new token
+                  error: void 0
+                };
+              } catch (error) {
+                console.error("[auth-next-server] Force refresh failed:", error);
+                return {
+                  ...token,
+                  error: "RefreshTokenError"
+                };
+              }
+            }
+            return {
+              ...token,
+              ...update.accessToken ? { accessToken: update.accessToken } : {},
+              ...update.refreshToken ? { refreshToken: update.refreshToken } : {},
+              ...update.idToken ? { idToken: update.idToken } : {},
+              ...update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {},
+              ...update.zkEvm ? { zkEvm: update.zkEvm } : {},
+              // Clear any stale error when valid tokens are synced from client-side
+              error: void 0
+            };
+          }
+          if (!isTokenExpired(token.accessTokenExpires)) {
+            return token;
+          }
+          if (token.refreshToken) {
             try {
               const refreshed = await refreshAccessToken(
                 token.refreshToken,
@@ -212,9 +271,10 @@ function createAuthConfig(config) {
                 zkEvm: zkEvm ?? token.zkEvm,
                 // Keep existing zkEvm if not in new token
                 error: void 0
+                // Clear any previous error
               };
             } catch (error) {
-              console.error("[auth-next-server] Force refresh failed:", error);
+              console.error("[auth-next-server] Token refresh failed:", error);
               return {
                 ...token,
                 error: "RefreshTokenError"
@@ -223,67 +283,35 @@ function createAuthConfig(config) {
           }
           return {
             ...token,
-            ...update.accessToken ? { accessToken: update.accessToken } : {},
-            ...update.refreshToken ? { refreshToken: update.refreshToken } : {},
-            ...update.idToken ? { idToken: update.idToken } : {},
-            ...update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {},
-            ...update.zkEvm ? { zkEvm: update.zkEvm } : {},
-            // Clear any stale error when valid tokens are synced from client-side
-            error: void 0
+            error: "TokenExpired"
           };
+        } catch (error) {
+          console.error("[auth-next-server] JWT callback error:", error);
+          throw error;
         }
-        if (!isTokenExpired(token.accessTokenExpires)) {
-          return token;
-        }
-        if (token.refreshToken) {
-          try {
-            const refreshed = await refreshAccessToken(
-              token.refreshToken,
-              config.clientId,
-              authDomain
-            );
-            const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
-            return {
-              ...token,
-              accessToken: refreshed.accessToken,
-              refreshToken: refreshed.refreshToken,
-              idToken: refreshed.idToken,
-              accessTokenExpires: refreshed.accessTokenExpires,
-              zkEvm: zkEvm ?? token.zkEvm,
-              // Keep existing zkEvm if not in new token
-              error: void 0
-              // Clear any previous error
-            };
-          } catch (error) {
-            console.error("[auth-next-server] Token refresh failed:", error);
-            return {
-              ...token,
-              error: "RefreshTokenError"
-            };
-          }
-        }
-        return {
-          ...token,
-          error: "TokenExpired"
-        };
       },
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       async session({ session, token }) {
-        return {
-          ...session,
-          user: {
-            ...session.user,
-            sub: token.sub,
-            email: token.email,
-            nickname: token.nickname
-          },
-          accessToken: token.accessToken,
-          refreshToken: token.refreshToken,
-          idToken: token.idToken,
-          accessTokenExpires: token.accessTokenExpires,
-          zkEvm: token.zkEvm,
-          ...token.error && { error: token.error }
-        };
+        try {
+          return {
+            ...session,
+            user: {
+              ...session.user,
+              sub: token.sub,
+              email: token.email,
+              nickname: token.nickname
+            },
+            accessToken: token.accessToken,
+            refreshToken: token.refreshToken,
+            idToken: token.idToken,
+            accessTokenExpires: token.accessTokenExpires,
+            zkEvm: token.zkEvm,
+            ...token.error && { error: token.error }
+          };
+        } catch (error) {
+          console.error("[auth-next-server] Session callback error:", error);
+          throw error;
+        }
       }
     },
     session: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-next-server",
-  "version": "2.12.7-alpha.1",
+  "version": "2.12.7-alpha.10",
   "description": "Immutable Auth.js v5 integration for Next.js - Server-side utilities",
   "author": "Immutable",
   "license": "Apache-2.0",

package/src/config.ts

@@ -3,6 +3,7 @@
 // @ts-ignore - Type exists in next-auth v5 but TS resolver may use stale types
 import type { NextAuthConfig } from 'next-auth';
 import CredentialsImport from 'next-auth/providers/credentials';
+import { encode as encodeImport } from 'next-auth/jwt';
 import type { ImmutableAuthConfig, ImmutableTokenData, UserInfoResponse } from './types';
 import { isTokenExpired, refreshAccessToken, extractZkEvmFromIdToken } from './refresh';
 import {
@@ -15,6 +16,8 @@ import {
 // may be nested under a 'default' property
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const Credentials = ((CredentialsImport as any).default || CredentialsImport) as typeof CredentialsImport;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const defaultJwtEncode = ((encodeImport as any).default || encodeImport) as typeof encodeImport;
 
 /**
  * Validate tokens by calling the userinfo endpoint.
@@ -72,6 +75,23 @@ export function createAuthConfig(config: ImmutableAuthConfig): NextAuthConfig {
   const authDomain = config.authenticationDomain || DEFAULT_AUTH_DOMAIN;
 
   return {
+    // Custom jwt.encode: strip idToken from the cookie to reduce size and avoid
+    // CloudFront 413 "Request Entity Too Large" errors. The idToken (~1-2 KB) is
+    // still available in session responses (after sign-in or token refresh) because
+    // the session callback runs BEFORE encode. All data extracted FROM idToken
+    // (email, nickname, zkEvm) remains in the cookie as separate fields.
+    // On the client, idToken is persisted in localStorage by @imtbl/auth-next-client.
+    jwt: {
+      async encode(params) {
+        const { token, ...rest } = params;
+        if (token) {
+          const { idToken, ...cookieToken } = token as Record<string, unknown>;
+          return defaultJwtEncode({ ...rest, token: cookieToken });
+        }
+        return defaultJwtEncode(params);
+      },
+    },
+
     providers: [
       Credentials({
         id: IMMUTABLE_PROVIDER_ID,
@@ -154,31 +174,80 @@ export function createAuthConfig(config: ImmutableAuthConfig): NextAuthConfig {
       async jwt({
         token, user, trigger, session: sessionUpdate,
       }: any) {
-        // Initial sign in - store all token data
-        if (user) {
-          return {
-            ...token,
-            sub: user.sub,
-            email: user.email,
-            nickname: user.nickname,
-            accessToken: user.accessToken,
-            refreshToken: user.refreshToken,
-            idToken: user.idToken,
-            accessTokenExpires: user.accessTokenExpires,
-            zkEvm: user.zkEvm,
-          };
-        }
+        try {
+          // Initial sign in - store all token data
+          if (user) {
+            return {
+              ...token,
+              sub: user.sub,
+              email: user.email,
+              nickname: user.nickname,
+              accessToken: user.accessToken,
+              refreshToken: user.refreshToken,
+              idToken: user.idToken,
+              accessTokenExpires: user.accessTokenExpires,
+              zkEvm: user.zkEvm,
+            };
+          }
+
+          // Handle session update (for client-side token sync or forceRefresh)
+          // When client-side Auth refreshes tokens via TOKEN_REFRESHED event,
+          // it calls updateSession() which triggers this callback with the new tokens.
+          // We clear any stale error (e.g., TokenExpired) on successful update.
+          if (trigger === 'update' && sessionUpdate) {
+            const update = sessionUpdate as Record<string, unknown>;
+
+            // If forceRefresh is requested, perform server-side token refresh
+            // This is used after zkEVM registration to get updated claims from IDP
+            if (update.forceRefresh && token.refreshToken) {
+              try {
+                const refreshed = await refreshAccessToken(
+                  token.refreshToken as string,
+                  config.clientId,
+                  authDomain,
+                );
+                // Extract zkEvm claims from the refreshed idToken
+                const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
+                return {
+                  ...token,
+                  accessToken: refreshed.accessToken,
+                  refreshToken: refreshed.refreshToken,
+                  idToken: refreshed.idToken,
+                  accessTokenExpires: refreshed.accessTokenExpires,
+                  zkEvm: zkEvm ?? token.zkEvm, // Keep existing zkEvm if not in new token
+                  error: undefined,
+                };
+              } catch (error) {
+              // eslint-disable-next-line no-console
+                console.error('[auth-next-server] Force refresh failed:', error);
+                return {
+                  ...token,
+                  error: 'RefreshTokenError',
+                };
+              }
+            }
+
+            // Standard session update - merge provided values
+            return {
+              ...token,
+              ...(update.accessToken ? { accessToken: update.accessToken } : {}),
+              ...(update.refreshToken ? { refreshToken: update.refreshToken } : {}),
+              ...(update.idToken ? { idToken: update.idToken } : {}),
+              ...(update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {}),
+              ...(update.zkEvm ? { zkEvm: update.zkEvm } : {}),
+              // Clear any stale error when valid tokens are synced from client-side
+              error: undefined,
+            };
+          }
 
-        // Handle session update (for client-side token sync or forceRefresh)
-        // When client-side Auth refreshes tokens via TOKEN_REFRESHED event,
-        // it calls updateSession() which triggers this callback with the new tokens.
-        // We clear any stale error (e.g., TokenExpired) on successful update.
-        if (trigger === 'update' && sessionUpdate) {
-          const update = sessionUpdate as Record<string, unknown>;
+          // Return token if not expired
+          if (!isTokenExpired(token.accessTokenExpires as number)) {
+            return token;
+          }
 
-          // If forceRefresh is requested, perform server-side token refresh
-          // This is used after zkEVM registration to get updated claims from IDP
-          if (update.forceRefresh && token.refreshToken) {
+          // Token expired - attempt server-side refresh
+          // This ensures clients always get fresh tokens from session callbacks
+          if (token.refreshToken) {
             try {
               const refreshed = await refreshAccessToken(
                 token.refreshToken as string,
@@ -194,11 +263,11 @@ export function createAuthConfig(config: ImmutableAuthConfig): NextAuthConfig {
                 idToken: refreshed.idToken,
                 accessTokenExpires: refreshed.accessTokenExpires,
                 zkEvm: zkEvm ?? token.zkEvm, // Keep existing zkEvm if not in new token
-                error: undefined,
+                error: undefined, // Clear any previous error
               };
             } catch (error) {
-              // eslint-disable-next-line no-console
-              console.error('[auth-next-server] Force refresh failed:', error);
+            // eslint-disable-next-line no-console
+              console.error('[auth-next-server] Token refresh failed:', error);
               return {
                 ...token,
                 error: 'RefreshTokenError',
@@ -206,79 +275,42 @@ export function createAuthConfig(config: ImmutableAuthConfig): NextAuthConfig {
             }
           }
 
-          // Standard session update - merge provided values
+          // No refresh token available
           return {
             ...token,
-            ...(update.accessToken ? { accessToken: update.accessToken } : {}),
-            ...(update.refreshToken ? { refreshToken: update.refreshToken } : {}),
-            ...(update.idToken ? { idToken: update.idToken } : {}),
-            ...(update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {}),
-            ...(update.zkEvm ? { zkEvm: update.zkEvm } : {}),
-            // Clear any stale error when valid tokens are synced from client-side
-            error: undefined,
+            error: 'TokenExpired',
           };
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error('[auth-next-server] JWT callback error:', error);
+          throw error;
         }
-
-        // Return token if not expired
-        if (!isTokenExpired(token.accessTokenExpires as number)) {
-          return token;
-        }
-
-        // Token expired - attempt server-side refresh
-        // This ensures clients always get fresh tokens from session callbacks
-        if (token.refreshToken) {
-          try {
-            const refreshed = await refreshAccessToken(
-              token.refreshToken as string,
-              config.clientId,
-              authDomain,
-            );
-            // Extract zkEvm claims from the refreshed idToken
-            const zkEvm = extractZkEvmFromIdToken(refreshed.idToken);
-            return {
-              ...token,
-              accessToken: refreshed.accessToken,
-              refreshToken: refreshed.refreshToken,
-              idToken: refreshed.idToken,
-              accessTokenExpires: refreshed.accessTokenExpires,
-              zkEvm: zkEvm ?? token.zkEvm, // Keep existing zkEvm if not in new token
-              error: undefined, // Clear any previous error
-            };
-          } catch (error) {
-            // eslint-disable-next-line no-console
-            console.error('[auth-next-server] Token refresh failed:', error);
-            return {
-              ...token,
-              error: 'RefreshTokenError',
-            };
-          }
-        }
-
-        // No refresh token available
-        return {
-          ...token,
-          error: 'TokenExpired',
-        };
       },
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       async session({ session, token }: any) {
-        // Expose token data to the session
-        return {
-          ...session,
-          user: {
-            ...session.user,
-            sub: token.sub as string,
-            email: token.email as string | undefined,
-            nickname: token.nickname as string | undefined,
-          },
-          accessToken: token.accessToken as string,
-          refreshToken: token.refreshToken as string | undefined,
-          idToken: token.idToken as string | undefined,
-          accessTokenExpires: token.accessTokenExpires as number,
-          zkEvm: token.zkEvm,
-          ...(token.error && { error: token.error as string }),
-        };
+        try {
+          // Expose token data to the session
+          return {
+            ...session,
+            user: {
+              ...session.user,
+              sub: token.sub as string,
+              email: token.email as string | undefined,
+              nickname: token.nickname as string | undefined,
+            },
+            accessToken: token.accessToken as string,
+            refreshToken: token.refreshToken as string | undefined,
+            idToken: token.idToken as string | undefined,
+            accessTokenExpires: token.accessTokenExpires as number,
+            zkEvm: token.zkEvm,
+            ...(token.error && { error: token.error as string }),
+          };
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error('[auth-next-server] Session callback error:', error);
+          throw error;
+        }
       },
     },