@imtbl/auth-next-client 2.12.7-alpha.0 → 2.12.7-alpha.10

package/README.md

@@ -10,7 +10,7 @@ This package provides minimal client-side utilities for Next.js applications usi
 
 - `useLogin` - Hook for login flows with state management (loading, error)
 - `useLogout` - Hook for logout with federated logout support (clears both local and upstream sessions)
-- `useImmutableSession` - Hook that provides session state and a `getUser` function for wallet integration
+- `useImmutableSession` - Hook that provides session state, `getAccessToken()` for guaranteed-fresh tokens, and `getUser` for wallet integration
 - `CallbackPage` - OAuth callback handler component
 
 For server-side utilities, use [`@imtbl/auth-next-server`](../auth-next-server).
@@ -395,7 +395,11 @@ With federated logout, the auth server's session is also cleared, so users can s
 
 ### `useImmutableSession()`
 
-A convenience hook that wraps `next-auth/react`'s `useSession` with a `getUser` function for wallet integration.
+A convenience hook that wraps `next-auth/react`'s `useSession` with:
+
+- `getAccessToken()` -- async function that returns a **guaranteed-fresh** access token
+- `getUser()` -- function for wallet integration
+- Automatic token refresh -- detects expired tokens and refreshes on demand
 
 ```tsx
 "use client";
@@ -404,10 +408,12 @@ import { useImmutableSession } from "@imtbl/auth-next-client";
 
 function MyComponent() {
   const {
-    session, // Session with tokens
+    session, // Session metadata (user info, zkEvm, error) -- does NOT include accessToken
     status, // 'loading' | 'authenticated' | 'unauthenticated'
     isLoading, // True during initial load
     isAuthenticated, // True when logged in
+    isRefreshing, // True during token refresh
+    getAccessToken, // Async function: returns a guaranteed-fresh access token
     getUser, // Function for wallet integration
   } = useImmutableSession();
 
@@ -420,13 +426,131 @@ function MyComponent() {
 
 #### Return Value
 
-| Property          | Type                                                | Description                                                      |
-| ----------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
-| `session`         | `ImmutableSession \| null`                          | Session with access/refresh tokens                               |
-| `status`          | `string`                                            | Auth status: `'loading'`, `'authenticated'`, `'unauthenticated'` |
-| `isLoading`       | `boolean`                                           | Whether initial auth state is loading                            |
-| `isAuthenticated` | `boolean`                                           | Whether user is authenticated                                    |
-| `getUser`         | `(forceRefresh?: boolean) => Promise<User \| null>` | Get user function for wallet integration                         |
+| Property          | Type                                                | Description                                                                             |
+| ----------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `session`         | `ImmutableSession \| null`                          | Session metadata (user, zkEvm, error). Does **not** include `accessToken` -- see below. |
+| `status`          | `string`                                            | Auth status: `'loading'`, `'authenticated'`, `'unauthenticated'`                        |
+| `isLoading`       | `boolean`                                           | Whether initial auth state is loading                                                   |
+| `isAuthenticated` | `boolean`                                           | Whether user is authenticated                                                           |
+| `isRefreshing`    | `boolean`                                           | Whether a token refresh is in progress                                                  |
+| `getAccessToken`  | `() => Promise<string>`                             | Get a guaranteed-fresh access token. Throws if not authenticated or refresh fails.      |
+| `getUser`         | `(forceRefresh?: boolean) => Promise<User \| null>` | Get user function for wallet integration                                                |
+
+#### Why no `accessToken` on `session`?
+
+The `session` object intentionally does **not** expose `accessToken`. This is a deliberate design choice to prevent consumers from accidentally using a stale/expired token.
+
+**Always use `getAccessToken()`** to obtain a token for authenticated requests:
+
+```tsx
+// ✅ Correct - always fresh
+const token = await getAccessToken();
+await authenticatedGet("/api/data", token);
+
+// ❌ Incorrect - session.accessToken does not exist on the type
+const token = session?.accessToken; // TypeScript error
+```
+
+`getAccessToken()` guarantees freshness:
+
+- **Fast path**: If the current token is valid, returns immediately (no network call).
+- **Slow path**: If the token is expired, triggers a server-side refresh and **blocks** (awaits) until the fresh token is available.
+- **Deduplication**: Multiple concurrent calls share a single refresh request.
+
+#### Checking Authentication Status
+
+**Always use `isAuthenticated` to determine if a user is logged in.** Do not use the `session` object or `status` field directly for this purpose.
+
+**Why not `!!session`?**
+
+A `session` object can exist but be **unusable**. For example, the session may be present but the access token is missing, or a token refresh may have failed (indicated by `session.error === "RefreshTokenError"`). Checking `!!session` would incorrectly treat these broken sessions as authenticated.
+
+**Why not `status === 'authenticated'`?**
+
+The `status` field comes directly from NextAuth's `useSession` and only reflects whether NextAuth considers the session valid at the cookie/JWT level. It does **not** account for whether the access token is actually present or whether a token refresh has failed. A session can have `status === 'authenticated'` while `session.error` is set to `"RefreshTokenError"`, meaning the tokens are no longer usable.
+
+**What `isAuthenticated` checks:**
+
+The `isAuthenticated` boolean validates all of the following:
+
+1. NextAuth reports `'authenticated'` status
+2. The session object exists
+3. A valid access token is present in the session
+4. No session-level error exists (e.g., `RefreshTokenError`)
+
+It also handles transient states gracefully — during session refetches (e.g., window focus) or manual refreshes (e.g., after wallet registration via `getUser(true)`), `isAuthenticated` remains `true` if the user was previously authenticated, preventing UI flicker.
+
+```tsx
+// ✅ Correct - uses isAuthenticated
+const { isAuthenticated } = useImmutableSession();
+if (!isAuthenticated) return <div>Please log in</div>;
+
+// ❌ Incorrect - session can exist with expired/invalid tokens
+const { session } = useImmutableSession();
+if (!session) return <div>Please log in</div>;
+
+// ❌ Incorrect - status doesn't account for token errors
+const { status } = useImmutableSession();
+if (status !== "authenticated") return <div>Please log in</div>;
+```
+
+#### Using `getAccessToken()` in Practice
+
+**SWR fetcher:**
+
+```tsx
+import useSWR from "swr";
+import { useImmutableSession } from "@imtbl/auth-next-client";
+
+function useProfile() {
+  const { getAccessToken, isAuthenticated } = useImmutableSession();
+
+  return useSWR(
+    isAuthenticated ? "/passport-profile/v1/profile" : null,
+    async (path) => {
+      const token = await getAccessToken(); // blocks until fresh
+      return authenticatedGet(path, token);
+    },
+  );
+}
+```
+
+**Event handler:**
+
+```tsx
+import { useImmutableSession } from "@imtbl/auth-next-client";
+
+function ClaimRewardButton({ questId }: { questId: string }) {
+  const { getAccessToken } = useImmutableSession();
+
+  const handleClaim = async () => {
+    const token = await getAccessToken(); // blocks until fresh
+    await authenticatedPost("/v1/quests/claim", token, { questId });
+  };
+
+  return <button onClick={handleClaim}>Claim</button>;
+}
+```
+
+**Periodic polling:**
+
+```tsx
+import useSWR from "swr";
+import { useImmutableSession } from "@imtbl/auth-next-client";
+
+function ActivityFeed() {
+  const { getAccessToken, isAuthenticated } = useImmutableSession();
+
+  return useSWR(
+    isAuthenticated ? "/v1/activities" : null,
+    async (path) => {
+      const token = await getAccessToken();
+      return authenticatedGet(path, token);
+    },
+    { refreshInterval: 10000 }, // polls every 10s, always gets a fresh token
+  );
+}
+```
 
 #### The `getUser` Function
 
@@ -452,13 +576,13 @@ When `forceRefresh` is `true`:
 
 ### ImmutableSession
 
-The session type returned by `useImmutableSession`:
+The session type returned by `useImmutableSession`. Note that `accessToken` is intentionally **not** included -- use `getAccessToken()` instead to obtain a guaranteed-fresh token.
 
 ```typescript
 interface ImmutableSession {
-  accessToken: string;
+  // accessToken is NOT exposed -- use getAccessToken() instead
   refreshToken?: string;
-  idToken?: string;
+  idToken?: string; // Only present transiently after sign-in or token refresh (not stored in cookie)
   accessTokenExpires: number;
   zkEvm?: {
     ethAddress: string;
@@ -473,6 +597,8 @@ interface ImmutableSession {
 }
 ```
 
+> **Note:** The `idToken` is **not** stored in the session cookie (to avoid CloudFront 413 errors from oversized headers). It is only present in the session response transiently after sign-in or token refresh. `@imtbl/auth-next-client` automatically persists it in `localStorage` so that `getUser()` always returns a valid `idToken` for wallet operations. All data extracted from the idToken (`email`, `nickname`, `zkEvm`) remains in the cookie as separate fields and is always available in the session.
+
 ### LoginConfig
 
 Configuration for the `useLogin` hook's login functions:
@@ -531,17 +657,19 @@ interface LogoutConfig {
 
 The session may contain an `error` field indicating authentication issues:
 
-| Error                 | Description           | Handling                                      |
-| --------------------- | --------------------- | --------------------------------------------- |
-| `"TokenExpired"`      | Access token expired  | Server-side refresh will happen automatically |
-| `"RefreshTokenError"` | Refresh token invalid | Prompt user to sign in again                  |
+| Error                 | Description           | Handling                                     |
+| --------------------- | --------------------- | -------------------------------------------- |
+| `"TokenExpired"`      | Access token expired  | Proactive refresh handles this automatically |
+| `"RefreshTokenError"` | Refresh token invalid | Prompt user to sign in again                 |
+
+`getAccessToken()` throws an error if the token cannot be obtained (e.g., refresh failure). Handle it with try/catch:
 
 ```tsx
 import { useImmutableSession } from "@imtbl/auth-next-client";
-import { signIn, signOut } from "next-auth/react";
+import { signOut } from "next-auth/react";
 
 function ProtectedContent() {
-  const { session, isAuthenticated } = useImmutableSession();
+  const { session, isAuthenticated, getAccessToken } = useImmutableSession();
 
   if (session?.error === "RefreshTokenError") {
     return (
@@ -556,11 +684,20 @@ function ProtectedContent() {
     return (
       <div>
         <p>Please sign in to continue.</p>
-        <button onClick={() => signIn()}>Sign In</button>
       </div>
     );
   }
 
+  const handleFetch = async () => {
+    try {
+      const token = await getAccessToken();
+      // Use token for authenticated requests
+    } catch (error) {
+      // Token refresh failed -- session may be expired
+      console.error("Failed to get access token:", error);
+    }
+  };
+
   return <div>Protected content here</div>;
 }
 ```

package/dist/node/index.cjs

@@ -39,6 +39,35 @@ var import_auth = require("@imtbl/auth");
 var IMMUTABLE_PROVIDER_ID = "immutable";
 var DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
 var DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
+var TOKEN_EXPIRY_BUFFER_MS = 60 * 1e3;
+
+// src/idTokenStorage.ts
+var ID_TOKEN_STORAGE_KEY = "imtbl_id_token";
+function storeIdToken(idToken) {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      window.localStorage.setItem(ID_TOKEN_STORAGE_KEY, idToken);
+    }
+  } catch {
+  }
+}
+function getStoredIdToken() {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage.getItem(ID_TOKEN_STORAGE_KEY) ?? void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function clearStoredIdToken() {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      window.localStorage.removeItem(ID_TOKEN_STORAGE_KEY);
+    }
+  } catch {
+  }
+}
 
 // src/callback.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -89,6 +118,9 @@ function CallbackPage({
           window.close();
         } else {
           const tokenData = mapTokensToSignInData(tokens);
+          if (tokens.idToken) {
+            storeIdToken(tokens.idToken);
+          }
           const result = await (0, import_react2.signIn)(IMMUTABLE_PROVIDER_ID, {
             tokens: JSON.stringify(tokenData),
             redirect: false
@@ -181,22 +213,43 @@ function CallbackPage({
 var import_react3 = require("react");
 var import_react4 = require("next-auth/react");
 var import_auth2 = require("@imtbl/auth");
+var pendingRefresh = null;
+function deduplicatedUpdate(update) {
+  if (!pendingRefresh) {
+    pendingRefresh = update().finally(() => {
+      pendingRefresh = null;
+    });
+  }
+  return pendingRefresh;
+}
 function useImmutableSession() {
   const { data: sessionData, status, update } = (0, import_react4.useSession)();
   const [isRefreshing, setIsRefreshing] = (0, import_react3.useState)(false);
   const session = sessionData;
   const isLoading = status === "loading";
-  const hasSession = status === "authenticated" && !!session;
+  const hasValidSession = status === "authenticated" && !!session && !!session.accessToken && !session.error;
   const hadSessionRef = (0, import_react3.useRef)(false);
-  if (hasSession) hadSessionRef.current = true;
-  if (!hasSession && !isLoading && !isRefreshing) hadSessionRef.current = false;
-  const isAuthenticated = hasSession || (isLoading || isRefreshing) && hadSessionRef.current;
+  if (hasValidSession) hadSessionRef.current = true;
+  if (!hasValidSession && !isLoading && !isRefreshing) hadSessionRef.current = false;
+  const isAuthenticated = hasValidSession || (isLoading || isRefreshing) && hadSessionRef.current;
   const sessionRef = (0, import_react3.useRef)(session);
   sessionRef.current = session;
   const updateRef = (0, import_react3.useRef)(update);
   updateRef.current = update;
   const setIsRefreshingRef = (0, import_react3.useRef)(setIsRefreshing);
   setIsRefreshingRef.current = setIsRefreshing;
+  (0, import_react3.useEffect)(() => {
+    if (!session?.accessTokenExpires) return;
+    const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
+    if (timeUntilExpiry <= 0) {
+      deduplicatedUpdate(() => updateRef.current());
+    }
+  }, [session?.accessTokenExpires]);
+  (0, import_react3.useEffect)(() => {
+    if (session?.idToken) {
+      storeIdToken(session.idToken);
+    }
+  }, [session?.idToken]);
   const getUser = (0, import_react3.useCallback)(async (forceRefresh) => {
     let currentSession;
     if (forceRefresh) {
@@ -206,6 +259,9 @@ function useImmutableSession() {
         currentSession = updatedSession;
         if (currentSession) {
           sessionRef.current = currentSession;
+          if (currentSession.idToken) {
+            storeIdToken(currentSession.idToken);
+          }
         }
       } catch (error) {
         console.error("[auth-next-client] Force refresh failed:", error);
@@ -213,6 +269,17 @@ function useImmutableSession() {
       } finally {
         setIsRefreshingRef.current(false);
       }
+    } else if (pendingRefresh) {
+      const refreshed = await pendingRefresh;
+      if (refreshed) {
+        currentSession = refreshed;
+        sessionRef.current = currentSession;
+        if (currentSession.idToken) {
+          storeIdToken(currentSession.idToken);
+        }
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       currentSession = sessionRef.current;
     }
@@ -226,7 +293,9 @@ function useImmutableSession() {
     return {
       accessToken: currentSession.accessToken,
       refreshToken: currentSession.refreshToken,
-      idToken: currentSession.idToken,
+      // Prefer session idToken (fresh after sign-in or refresh, before useEffect
+      // stores it), fall back to localStorage for normal reads (cookie has no idToken).
+      idToken: currentSession.idToken || getStoredIdToken(),
       profile: {
         sub: currentSession.user?.sub ?? "",
         email: currentSession.user?.email ?? void 0,
@@ -235,19 +304,40 @@ function useImmutableSession() {
       zkEvm: currentSession.zkEvm
     };
   }, []);
+  const getAccessToken = (0, import_react3.useCallback)(async () => {
+    const currentSession = sessionRef.current;
+    if (currentSession?.accessToken && currentSession.accessTokenExpires && Date.now() < currentSession.accessTokenExpires - TOKEN_EXPIRY_BUFFER_MS && !currentSession.error) {
+      return currentSession.accessToken;
+    }
+    const refreshed = await deduplicatedUpdate(
+      () => updateRef.current()
+    );
+    if (!refreshed?.accessToken || refreshed.error) {
+      throw new Error(
+        `[auth-next-client] Failed to get access token: ${refreshed?.error || "no session"}`
+      );
+    }
+    sessionRef.current = refreshed;
+    return refreshed.accessToken;
+  }, []);
+  const publicSession = session;
   return {
-    session,
+    session: publicSession,
     status,
     isLoading,
     isAuthenticated,
     isRefreshing,
-    getUser
+    getUser,
+    getAccessToken
   };
 }
 function useLogin() {
   const [isLoggingIn, setIsLoggingIn] = (0, import_react3.useState)(false);
   const [error, setError] = (0, import_react3.useState)(null);
   const signInWithTokens = (0, import_react3.useCallback)(async (tokens) => {
+    if (tokens.idToken) {
+      storeIdToken(tokens.idToken);
+    }
     const result = await (0, import_react4.signIn)(IMMUTABLE_PROVIDER_ID, {
       tokens: JSON.stringify(tokens),
       redirect: false
@@ -314,6 +404,7 @@ function useLogout() {
     setIsLoggingOut(true);
     setError(null);
     try {
+      clearStoredIdToken();
       await (0, import_react4.signOut)({ redirect: false });
       (0, import_auth2.logoutWithRedirect)(config);
     } catch (err) {

package/dist/node/index.js

@@ -10,6 +10,35 @@ import { handleLoginCallback as handleAuthCallback } from "@imtbl/auth";
 var IMMUTABLE_PROVIDER_ID = "immutable";
 var DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
 var DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
+var TOKEN_EXPIRY_BUFFER_MS = 60 * 1e3;
+
+// src/idTokenStorage.ts
+var ID_TOKEN_STORAGE_KEY = "imtbl_id_token";
+function storeIdToken(idToken) {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      window.localStorage.setItem(ID_TOKEN_STORAGE_KEY, idToken);
+    }
+  } catch {
+  }
+}
+function getStoredIdToken() {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage.getItem(ID_TOKEN_STORAGE_KEY) ?? void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function clearStoredIdToken() {
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      window.localStorage.removeItem(ID_TOKEN_STORAGE_KEY);
+    }
+  } catch {
+  }
+}
 
 // src/callback.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -60,6 +89,9 @@ function CallbackPage({
           window.close();
         } else {
           const tokenData = mapTokensToSignInData(tokens);
+          if (tokens.idToken) {
+            storeIdToken(tokens.idToken);
+          }
           const result = await signIn(IMMUTABLE_PROVIDER_ID, {
             tokens: JSON.stringify(tokenData),
             redirect: false
@@ -149,7 +181,12 @@ function CallbackPage({
 }
 
 // src/hooks.tsx
-import { useCallback, useRef as useRef2, useState as useState2 } from "react";
+import {
+  useCallback,
+  useEffect as useEffect2,
+  useRef as useRef2,
+  useState as useState2
+} from "react";
 import { useSession, signIn as signIn2, signOut } from "next-auth/react";
 import {
   loginWithPopup as rawLoginWithPopup,
@@ -157,22 +194,43 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect
 } from "@imtbl/auth";
+var pendingRefresh = null;
+function deduplicatedUpdate(update) {
+  if (!pendingRefresh) {
+    pendingRefresh = update().finally(() => {
+      pendingRefresh = null;
+    });
+  }
+  return pendingRefresh;
+}
 function useImmutableSession() {
   const { data: sessionData, status, update } = useSession();
   const [isRefreshing, setIsRefreshing] = useState2(false);
   const session = sessionData;
   const isLoading = status === "loading";
-  const hasSession = status === "authenticated" && !!session;
+  const hasValidSession = status === "authenticated" && !!session && !!session.accessToken && !session.error;
   const hadSessionRef = useRef2(false);
-  if (hasSession) hadSessionRef.current = true;
-  if (!hasSession && !isLoading && !isRefreshing) hadSessionRef.current = false;
-  const isAuthenticated = hasSession || (isLoading || isRefreshing) && hadSessionRef.current;
+  if (hasValidSession) hadSessionRef.current = true;
+  if (!hasValidSession && !isLoading && !isRefreshing) hadSessionRef.current = false;
+  const isAuthenticated = hasValidSession || (isLoading || isRefreshing) && hadSessionRef.current;
   const sessionRef = useRef2(session);
   sessionRef.current = session;
   const updateRef = useRef2(update);
   updateRef.current = update;
   const setIsRefreshingRef = useRef2(setIsRefreshing);
   setIsRefreshingRef.current = setIsRefreshing;
+  useEffect2(() => {
+    if (!session?.accessTokenExpires) return;
+    const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
+    if (timeUntilExpiry <= 0) {
+      deduplicatedUpdate(() => updateRef.current());
+    }
+  }, [session?.accessTokenExpires]);
+  useEffect2(() => {
+    if (session?.idToken) {
+      storeIdToken(session.idToken);
+    }
+  }, [session?.idToken]);
   const getUser = useCallback(async (forceRefresh) => {
     let currentSession;
     if (forceRefresh) {
@@ -182,6 +240,9 @@ function useImmutableSession() {
         currentSession = updatedSession;
         if (currentSession) {
           sessionRef.current = currentSession;
+          if (currentSession.idToken) {
+            storeIdToken(currentSession.idToken);
+          }
         }
       } catch (error) {
         console.error("[auth-next-client] Force refresh failed:", error);
@@ -189,6 +250,17 @@ function useImmutableSession() {
       } finally {
         setIsRefreshingRef.current(false);
       }
+    } else if (pendingRefresh) {
+      const refreshed = await pendingRefresh;
+      if (refreshed) {
+        currentSession = refreshed;
+        sessionRef.current = currentSession;
+        if (currentSession.idToken) {
+          storeIdToken(currentSession.idToken);
+        }
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       currentSession = sessionRef.current;
     }
@@ -202,7 +274,9 @@ function useImmutableSession() {
     return {
       accessToken: currentSession.accessToken,
       refreshToken: currentSession.refreshToken,
-      idToken: currentSession.idToken,
+      // Prefer session idToken (fresh after sign-in or refresh, before useEffect
+      // stores it), fall back to localStorage for normal reads (cookie has no idToken).
+      idToken: currentSession.idToken || getStoredIdToken(),
       profile: {
         sub: currentSession.user?.sub ?? "",
         email: currentSession.user?.email ?? void 0,
@@ -211,19 +285,40 @@ function useImmutableSession() {
       zkEvm: currentSession.zkEvm
     };
   }, []);
+  const getAccessToken = useCallback(async () => {
+    const currentSession = sessionRef.current;
+    if (currentSession?.accessToken && currentSession.accessTokenExpires && Date.now() < currentSession.accessTokenExpires - TOKEN_EXPIRY_BUFFER_MS && !currentSession.error) {
+      return currentSession.accessToken;
+    }
+    const refreshed = await deduplicatedUpdate(
+      () => updateRef.current()
+    );
+    if (!refreshed?.accessToken || refreshed.error) {
+      throw new Error(
+        `[auth-next-client] Failed to get access token: ${refreshed?.error || "no session"}`
+      );
+    }
+    sessionRef.current = refreshed;
+    return refreshed.accessToken;
+  }, []);
+  const publicSession = session;
   return {
-    session,
+    session: publicSession,
     status,
     isLoading,
     isAuthenticated,
     isRefreshing,
-    getUser
+    getUser,
+    getAccessToken
   };
 }
 function useLogin() {
   const [isLoggingIn, setIsLoggingIn] = useState2(false);
   const [error, setError] = useState2(null);
   const signInWithTokens = useCallback(async (tokens) => {
+    if (tokens.idToken) {
+      storeIdToken(tokens.idToken);
+    }
     const result = await signIn2(IMMUTABLE_PROVIDER_ID, {
       tokens: JSON.stringify(tokens),
       redirect: false
@@ -290,6 +385,7 @@ function useLogout() {
     setIsLoggingOut(true);
     setError(null);
     try {
+      clearStoredIdToken();
       await signOut({ redirect: false });
       rawLogoutWithRedirect(config);
     } catch (err) {

package/dist/types/constants.d.ts

@@ -30,3 +30,8 @@ export declare const DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
  * Default token expiry in milliseconds
  */
 export declare const DEFAULT_TOKEN_EXPIRY_MS: number;
+/**
+ * Buffer time in milliseconds before token expiry to trigger refresh.
+ * Matches TOKEN_EXPIRY_BUFFER_SECONDS (60s) in @imtbl/auth-next-server.
+ */
+export declare const TOKEN_EXPIRY_BUFFER_MS: number;

package/dist/types/hooks.d.ts

@@ -2,9 +2,10 @@ import type { Session } from 'next-auth';
 import type { User, LoginConfig, StandaloneLoginOptions, LogoutConfig } from '@imtbl/auth';
 import type { ZkEvmInfo } from './types';
 /**
- * Extended session type with Immutable token data
+ * Internal session type with full token data (not exported).
+ * Used internally by the hook for token validation, refresh logic, and getUser/getAccessToken.
  */
-export interface ImmutableSession extends Session {
+interface ImmutableSessionInternal extends Session {
     accessToken: string;
     refreshToken?: string;
     idToken?: string;
@@ -12,6 +13,14 @@ export interface ImmutableSession extends Session {
     zkEvm?: ZkEvmInfo;
     error?: string;
 }
+/**
+ * Public session type exposed to consumers.
+ *
+ * Does **not** include `accessToken` -- consumers must use the `getAccessToken()`
+ * function returned by `useImmutableSession()` to obtain a guaranteed-fresh token.
+ * This prevents accidental use of stale/expired tokens.
+ */
+export type ImmutableSession = Omit<ImmutableSessionInternal, 'accessToken'>;
 /**
  * Return type for useImmutableSession hook
  */
@@ -35,6 +44,13 @@ export interface UseImmutableSessionReturn {
      *   The refreshed session will include updated zkEvm data if available.
      */
     getUser: (forceRefresh?: boolean) => Promise<User | null>;
+    /**
+     * Get a guaranteed-fresh access token.
+     * Returns immediately if the current token is valid.
+     * If expired, triggers a refresh and blocks (awaits) until the fresh token is available.
+     * Throws if the user is not authenticated or if refresh fails.
+     */
+    getAccessToken: () => Promise<string>;
 }
 /**
  * Hook to access Immutable session with a getUser function for wallet integration.
@@ -186,3 +202,4 @@ export interface UseLogoutReturn {
  * ```
  */
 export declare function useLogout(): UseLogoutReturn;
+export {};