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

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
@@ -29,6 +30,16 @@ yarn add @imtbl/auth-next-server next-auth@5
 - `next` >= 14.0.0
 - `next-auth` >= 5.0.0-beta.25
 
+### Next.js 14 Compatibility
+
+This package is compatible with both Next.js 14 and 15. It uses only standard APIs available in both versions:
+
+- `next/server`: `NextRequest`, `NextResponse` (middleware)
+- `next/navigation`: `redirect` (Server Components)
+- NextAuth v5 with App Router
+
+No Next.js 15-only APIs are used (e.g. async `headers()`/`cookies()`, `unstable_after`).
+
 ## Quick Start
 
 ### 1. Create Auth Configuration
@@ -40,10 +51,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
@@ -66,37 +79,75 @@ NEXT_PUBLIC_BASE_URL=http://localhost:3000
 AUTH_SECRET=your-secret-key-min-32-characters
 ```
 
+## Default Auth (Zero Config)
+
+Policy: **provide nothing → full sandbox; provide config → provide everything.**
+
+With no configuration, `createAuthConfig()` uses sandbox defaults:
+- `clientId`: sandbox (public Immutable client ID)
+- `redirectUri`: from `window.location.origin + '/callback'` (path only on server)
+
+When providing config, pass `clientId` and `redirectUri` (and optionally `audience`, `scope`, `authenticationDomain`) to avoid conflicts.
+
+```typescript
+// lib/auth.ts
+import NextAuth from "next-auth";
+import { createAuthConfig } from "@imtbl/auth-next-server";
+
+// Zero config - only AUTH_SECRET required in .env
+export const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig());
+```
+
+With partial overrides:
+
+```typescript
+// With config - provide clientId and redirectUri
+export const { handlers, auth, signIn, signOut } = NextAuth(
+  createAuthConfig({
+    clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+    redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+  }),
+);
+```
+
+> **Note:** Default auth uses public Immutable client IDs. For production apps, use your own client ID from Immutable Hub.
+
 ## Configuration
 
-### `createAuthConfig(config)`
+### `createAuthConfig(config?)`
 
-Creates an Auth.js v5 configuration object for Immutable authentication. You pass this to `NextAuth()` to create your auth instance.
+Creates an Auth.js v5 configuration object for Immutable authentication. Config is optional—when omitted, sensible defaults are used. Pass this to `NextAuth()` to create your auth instance.
 
 ```typescript
 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
-}));
+// Zero config
+const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig());
+
+// Or with custom config
+const { handlers, auth, signIn, signOut } = NextAuth(
+  createAuthConfig({
+    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 (*required when config is provided) |
+| `redirectUri`          | `string` | Yes*     | OAuth redirect URI (*required when config is provided)                   |
+| `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 +168,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 +193,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 +220,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 +235,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 +263,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 +278,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 +302,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 +316,7 @@ export default async function DashboardPage() {
   const result = await getData(async (token) => {
     return fetchDashboardData(token);
   });
-  
+
   return <DashboardClient {...result} />;
 }
 ```
@@ -281,6 +338,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 +352,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 +382,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 +412,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 +455,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 +468,9 @@ export const transferAsset = withAuth(
       assetId,
       accessToken: session.accessToken,
     });
-    
+
     return result;
-  }
+  },
 );
 ```
 
@@ -420,22 +481,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 +516,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 +528,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 +540,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 +551,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