@imtbl/auth-next-client 2.12.7-alpha.5 → 2.12.7-alpha.7

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,36 @@ 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
 
@@ -465,6 +494,64 @@ 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
 
 The `getUser` function returns fresh tokens from the session. It accepts an optional `forceRefresh` parameter:
@@ -489,11 +576,11 @@ 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;
   accessTokenExpires: number;
@@ -568,17 +655,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 (
@@ -593,11 +682,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,7 @@ 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/callback.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -181,6 +182,15 @@ 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);
@@ -197,6 +207,13 @@ function useImmutableSession() {
   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]);
   const getUser = (0, import_react3.useCallback)(async (forceRefresh) => {
     let currentSession;
     if (forceRefresh) {
@@ -213,6 +230,14 @@ function useImmutableSession() {
       } finally {
         setIsRefreshingRef.current(false);
       }
+    } else if (pendingRefresh) {
+      const refreshed = await pendingRefresh;
+      if (refreshed) {
+        currentSession = refreshed;
+        sessionRef.current = currentSession;
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       currentSession = sessionRef.current;
     }
@@ -235,13 +260,31 @@ 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() {

package/dist/node/index.js

@@ -10,6 +10,7 @@ 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/callback.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -149,7 +150,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,6 +163,15 @@ 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);
@@ -173,6 +188,13 @@ function useImmutableSession() {
   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]);
   const getUser = useCallback(async (forceRefresh) => {
     let currentSession;
     if (forceRefresh) {
@@ -189,6 +211,14 @@ function useImmutableSession() {
       } finally {
         setIsRefreshingRef.current(false);
       }
+    } else if (pendingRefresh) {
+      const refreshed = await pendingRefresh;
+      if (refreshed) {
+        currentSession = refreshed;
+        sessionRef.current = currentSession;
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       currentSession = sessionRef.current;
     }
@@ -211,13 +241,31 @@ 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() {

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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-next-client",
-  "version": "2.12.7-alpha.5",
+  "version": "2.12.7-alpha.7",
   "description": "Immutable Auth.js v5 integration for Next.js - Client-side components",
   "author": "Immutable",
   "license": "Apache-2.0",
@@ -27,8 +27,8 @@
     }
   },
   "dependencies": {
-    "@imtbl/auth": "2.12.7-alpha.5",
-    "@imtbl/auth-next-server": "2.12.7-alpha.5"
+    "@imtbl/auth": "2.12.7-alpha.7",
+    "@imtbl/auth-next-server": "2.12.7-alpha.7"
   },
   "peerDependencies": {
     "next": "^15.0.0",
@@ -49,6 +49,8 @@
   "devDependencies": {
     "@swc/core": "^1.4.2",
     "@swc/jest": "^0.2.37",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^13.4.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.10.7",
     "@types/react": "^18.3.5",

package/src/constants.ts

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

package/src/hooks.test.tsx

@@ -0,0 +1,317 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable import/first */
+import { renderHook, act } from '@testing-library/react';
+import { TOKEN_EXPIRY_BUFFER_MS } from './constants';
+
+// ---------------------------------------------------------------------------
+// Mocks -- must be declared before importing the modules that use them
+// ---------------------------------------------------------------------------
+
+const mockUpdate = jest.fn();
+const mockUseSession = jest.fn();
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => mockUseSession(),
+  signIn: jest.fn(),
+  signOut: jest.fn(),
+}));
+
+jest.mock('@imtbl/auth', () => ({
+  loginWithPopup: jest.fn(),
+  loginWithEmbedded: jest.fn(),
+  loginWithRedirect: jest.fn(),
+  logoutWithRedirect: jest.fn(),
+}));
+
+import { useImmutableSession } from './hooks';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Full session shape matching what NextAuth returns at runtime.
+ * The public ImmutableSession type intentionally omits accessToken,
+ * but the underlying data still has it -- tests need the full shape
+ * to set up mock sessions correctly.
+ */
+interface TestSession {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  accessTokenExpires: number;
+  zkEvm?: { ethAddress: string; userAdminAddress: string };
+  error?: string;
+  user?: any;
+  expires: string;
+}
+
+function createSession(overrides: Partial<TestSession> = {}): TestSession {
+  return {
+    accessToken: 'valid-token',
+    refreshToken: 'refresh-token',
+    idToken: 'id-token',
+    accessTokenExpires: Date.now() + 10 * 60 * 1000, // 10 min from now
+    user: { sub: 'user-1', email: 'test@test.com' },
+    expires: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+    ...overrides,
+  };
+}
+
+function setupUseSession(session: TestSession | null, status: string = 'authenticated') {
+  mockUseSession.mockReturnValue({
+    data: session,
+    status,
+    update: mockUpdate,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('useImmutableSession', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUpdate.mockReset();
+  });
+
+  describe('session type safety', () => {
+    it('does not expose accessToken on the public session type', () => {
+      const session = createSession();
+      setupUseSession(session);
+      mockUpdate.mockResolvedValue(session);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      // TypeScript prevents accessing accessToken, but at runtime the
+      // underlying object still has it. Verify the hook returns a session
+      // and that the public type doesn't advertise accessToken.
+      expect(result.current.session).toBeDefined();
+      expect(result.current.session?.error).toBeUndefined();
+      // The property exists at runtime (it's the same object) but the type
+      // system hides it -- this is a compile-time guard, not a runtime one.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((result.current.session as any).accessToken).toBeDefined();
+    });
+  });
+
+  describe('getAccessToken()', () => {
+    it('returns the token immediately when it is valid (fast path)', async () => {
+      const session = createSession();
+      setupUseSession(session);
+      mockUpdate.mockResolvedValue(session); // in case proactive timer fires
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      const token = await result.current.getAccessToken();
+      expect(token).toBe('valid-token');
+    });
+
+    it('triggers refresh and returns fresh token when expired', async () => {
+      const expiredSession = createSession({
+        accessTokenExpires: Date.now() - 1000, // already expired
+      });
+      setupUseSession(expiredSession);
+
+      const freshSession = createSession({
+        accessToken: 'fresh-token',
+        accessTokenExpires: Date.now() + 10 * 60 * 1000,
+      });
+      mockUpdate.mockResolvedValue(freshSession);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      let token: string = '';
+      await act(async () => {
+        token = await result.current.getAccessToken();
+      });
+      expect(token).toBe('fresh-token');
+      expect(mockUpdate).toHaveBeenCalled();
+    });
+
+    it('triggers refresh when token is within the buffer window', async () => {
+      const almostExpiredSession = createSession({
+        accessTokenExpires: Date.now() + TOKEN_EXPIRY_BUFFER_MS - 1000, // within buffer
+      });
+      setupUseSession(almostExpiredSession);
+
+      const freshSession = createSession({
+        accessToken: 'refreshed-token',
+        accessTokenExpires: Date.now() + 10 * 60 * 1000,
+      });
+      mockUpdate.mockResolvedValue(freshSession);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      let token: string = '';
+      await act(async () => {
+        token = await result.current.getAccessToken();
+      });
+      expect(token).toBe('refreshed-token');
+      expect(mockUpdate).toHaveBeenCalled();
+    });
+
+    it('throws when refresh fails (no accessToken in response)', async () => {
+      const expiredSession = createSession({
+        accessTokenExpires: Date.now() - 1000,
+      });
+      setupUseSession(expiredSession);
+
+      mockUpdate.mockResolvedValue(null);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      await expect(
+        act(async () => {
+          await result.current.getAccessToken();
+        }),
+      ).rejects.toThrow('[auth-next-client] Failed to get access token');
+    });
+
+    it('throws when refresh returns a session with error', async () => {
+      const expiredSession = createSession({
+        accessTokenExpires: Date.now() - 1000,
+      });
+      setupUseSession(expiredSession);
+
+      const errorSession = createSession({ error: 'RefreshTokenError' });
+      mockUpdate.mockResolvedValue(errorSession);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      await expect(
+        act(async () => {
+          await result.current.getAccessToken();
+        }),
+      ).rejects.toThrow('RefreshTokenError');
+    });
+
+    it('deduplicates concurrent calls (only one update())', async () => {
+      const expiredSession = createSession({
+        accessTokenExpires: Date.now() - 1000,
+      });
+      setupUseSession(expiredSession);
+
+      const freshSession = createSession({
+        accessToken: 'deduped-token',
+        accessTokenExpires: Date.now() + 10 * 60 * 1000,
+      });
+
+      // Track how many times update is actually invoked
+      let updateCallCount = 0;
+      mockUpdate.mockImplementation(() => {
+        updateCallCount++;
+        return Promise.resolve(freshSession);
+      });
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      let token1: string = '';
+      let token2: string = '';
+      await act(async () => {
+        [token1, token2] = await Promise.all([
+          result.current.getAccessToken(),
+          result.current.getAccessToken(),
+        ]);
+      });
+
+      expect(token1).toBe('deduped-token');
+      expect(token2).toBe('deduped-token');
+      // The proactive effect may also trigger one call, so we check
+      // that concurrent getAccessToken calls are deduped (not doubled)
+      // The key invariant: at most 1 update() call per pending refresh cycle
+      expect(updateCallCount).toBeLessThanOrEqual(2); // 1 from effect + 1 from getAccessToken (deduped)
+    });
+  });
+
+  describe('reactive refresh on mount', () => {
+    it('triggers refresh when token is already expired on mount', async () => {
+      const session = createSession({
+        accessTokenExpires: Date.now() - 1000, // already expired
+      });
+      setupUseSession(session);
+
+      const freshSession = createSession({
+        accessToken: 'immediate-refresh',
+      });
+      mockUpdate.mockResolvedValue(freshSession);
+
+      await act(async () => {
+        renderHook(() => useImmutableSession());
+      });
+
+      // The proactive useEffect should have called update
+      expect(mockUpdate).toHaveBeenCalled();
+    });
+
+    it('does not set isRefreshing during reactive refresh (prevents UI flicker)', async () => {
+      const session = createSession({
+        accessTokenExpires: Date.now() - 1000, // already expired
+      });
+      setupUseSession(session);
+
+      const freshSession = createSession({
+        accessToken: 'immediate-refresh',
+      });
+      mockUpdate.mockResolvedValue(freshSession);
+
+      const capturedIsRefreshing: boolean[] = [];
+      const { result } = renderHook(() => {
+        const hook = useImmutableSession();
+        capturedIsRefreshing.push(hook.isRefreshing);
+        return hook;
+      });
+
+      await act(async () => {
+        // Let the reactive refresh effect run and complete
+        await mockUpdate.mock.results[0]?.value;
+      });
+
+      // isRefreshing should NEVER have been true during reactive refresh.
+      // It is reserved for explicit user-triggered refreshes (getUser(true)).
+      expect(capturedIsRefreshing.every((v) => v === false)).toBe(true);
+      expect(result.current.isRefreshing).toBe(false);
+    });
+
+    it('does not trigger refresh when token is valid and far from expiry', async () => {
+      const session = createSession({
+        accessTokenExpires: Date.now() + 10 * 60 * 1000, // 10 min from now, well beyond buffer
+      });
+      setupUseSession(session);
+
+      await act(async () => {
+        renderHook(() => useImmutableSession());
+      });
+
+      // Should NOT have called update -- token is still valid
+      expect(mockUpdate).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getUser() respects pending refresh', () => {
+    it('waits for in-flight refresh before returning user', async () => {
+      const expiredSession = createSession({
+        accessTokenExpires: Date.now() - 1000,
+      });
+      setupUseSession(expiredSession);
+
+      const freshSession = createSession({
+        accessToken: 'user-fresh-token',
+        accessTokenExpires: Date.now() + 10 * 60 * 1000,
+      });
+
+      mockUpdate.mockResolvedValue(freshSession);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      let user: any;
+      await act(async () => {
+        user = await result.current.getUser();
+      });
+
+      // getUser() should have waited for the refresh and gotten the fresh token
+      expect(user?.accessToken).toBe('user-fresh-token');
+    });
+  });
+});

package/src/hooks.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { useCallback, useRef, useState } from 'react';
+import {
+  useCallback, useEffect, useRef, useState,
+} from 'react';
 import { useSession, signIn, signOut } from 'next-auth/react';
 import type { Session } from 'next-auth';
 import type {
@@ -16,12 +18,34 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect,
 } from '@imtbl/auth';
-import { IMMUTABLE_PROVIDER_ID } from './constants';
+import { IMMUTABLE_PROVIDER_ID, TOKEN_EXPIRY_BUFFER_MS } from './constants';
+
+// ---------------------------------------------------------------------------
+// Module-level deduplication for session refresh
+// ---------------------------------------------------------------------------
 
 /**
- * Extended session type with Immutable token data
+ * Deduplicates concurrent session refresh calls.
+ * Multiple components may mount useImmutableSession simultaneously; without
+ * deduplication each would trigger its own update() call, which could fail
+ * if the auth server rotates refresh tokens.
  */
-export interface ImmutableSession extends Session {
+let pendingRefresh: Promise<Session | null | undefined> | null = null;
+
+function deduplicatedUpdate(
+  update: () => Promise<Session | null | undefined>,
+): Promise<Session | null | undefined> {
+  if (!pendingRefresh) {
+    pendingRefresh = update().finally(() => { pendingRefresh = null; });
+  }
+  return pendingRefresh;
+}
+
+/**
+ * Internal session type with full token data (not exported).
+ * Used internally by the hook for token validation, refresh logic, and getUser/getAccessToken.
+ */
+interface ImmutableSessionInternal extends Session {
   accessToken: string;
   refreshToken?: string;
   idToken?: string;
@@ -30,6 +54,15 @@ export interface ImmutableSession extends Session {
   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
  */
@@ -53,6 +86,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>;
 }
 
 /**
@@ -92,8 +132,8 @@ export function useImmutableSession(): UseImmutableSessionReturn {
   // Track when a manual refresh is in progress (via getUser(true))
   const [isRefreshing, setIsRefreshing] = useState(false);
 
-  // Cast session to our extended type
-  const session = sessionData as ImmutableSession | null;
+  // Cast session to our internal type (includes accessToken for internal logic)
+  const session = sessionData as ImmutableSessionInternal | null;
 
   const isLoading = status === 'loading';
 
@@ -114,7 +154,7 @@ export function useImmutableSession(): UseImmutableSessionReturn {
   // Use a ref to always have access to the latest session.
   // This avoids stale closure issues when the wallet stores the getUser function
   // and calls it later - the ref always points to the current session.
-  const sessionRef = useRef<ImmutableSession | null>(session);
+  const sessionRef = useRef<ImmutableSessionInternal | null>(session);
   sessionRef.current = session;
 
   // Also store update in a ref so the callback is stable
@@ -125,6 +165,30 @@ export function useImmutableSession(): UseImmutableSessionReturn {
   const setIsRefreshingRef = useRef(setIsRefreshing);
   setIsRefreshingRef.current = setIsRefreshing;
 
+  // ---------------------------------------------------------------------------
+  // Proactive token refresh
+  // ---------------------------------------------------------------------------
+
+  // Reactive refresh: when the effect runs and the token is already expired
+  // (e.g., after tab regains focus), trigger an immediate silent refresh.
+  // For tokens that are still valid, getAccessToken() handles refresh on demand.
+  //
+  // NOTE: This intentionally does NOT set isRefreshing. isRefreshing is reserved
+  // for explicit user-triggered refreshes (e.g., getUser(true) after wallet
+  // registration). Background token refreshes must be invisible to consumers --
+  // setting isRefreshing would cause downstream hooks that gate SWR keys on
+  // `!isRefreshing` to briefly lose their cached data, resulting in UI flicker.
+  useEffect(() => {
+    if (!session?.accessTokenExpires) return;
+
+    const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
+
+    if (timeUntilExpiry <= 0) {
+      // Already expired -- refresh silently
+      deduplicatedUpdate(() => updateRef.current());
+    }
+  }, [session?.accessTokenExpires]);
+
   /**
    * Get user function for wallet integration.
    * Returns a User object compatible with @imtbl/wallet's getUser option.
@@ -135,7 +199,7 @@ export function useImmutableSession(): UseImmutableSessionReturn {
    * @param forceRefresh - When true, triggers a server-side token refresh
    */
   const getUser = useCallback(async (forceRefresh?: boolean): Promise<User | null> => {
-    let currentSession: ImmutableSession | null;
+    let currentSession: ImmutableSessionInternal | null;
 
     // If forceRefresh is requested, trigger server-side refresh via NextAuth
     // This calls the jwt callback with trigger='update' and sessionUpdate.forceRefresh=true
@@ -145,7 +209,7 @@ export function useImmutableSession(): UseImmutableSessionReturn {
       try {
         // update() returns the refreshed session
         const updatedSession = await updateRef.current({ forceRefresh: true });
-        currentSession = updatedSession as ImmutableSession | null;
+        currentSession = updatedSession as ImmutableSessionInternal | null;
         // Also update the ref so subsequent calls get the fresh data
         if (currentSession) {
           sessionRef.current = currentSession;
@@ -158,6 +222,16 @@ export function useImmutableSession(): UseImmutableSessionReturn {
       } finally {
         setIsRefreshingRef.current(false);
       }
+    } else if (pendingRefresh) {
+      // If a refresh is in-flight (proactive timer or another getAccessToken call),
+      // wait for it and use the refreshed session rather than returning a stale token.
+      const refreshed = await pendingRefresh;
+      if (refreshed) {
+        currentSession = refreshed as ImmutableSessionInternal;
+        sessionRef.current = currentSession;
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       // Read from ref - instant, no network call
       // The ref is always updated on each render with the latest session
@@ -188,13 +262,55 @@ export function useImmutableSession(): UseImmutableSessionReturn {
     };
   }, []); // Empty deps - uses refs for latest values
 
+  /**
+   * Get a guaranteed-fresh access token.
+   * Returns immediately if the current token is valid (fast path, no network call).
+   * If expired, triggers a server-side refresh and blocks (awaits) until the fresh
+   * token is available. Piggybacks on any in-flight refresh to avoid duplicate calls.
+   *
+   * @throws Error if the user is not authenticated or if the refresh fails.
+   */
+  const getAccessToken = useCallback(async (): Promise<string> => {
+    const currentSession = sessionRef.current;
+
+    // Fast path: token is valid -- return immediately
+    if (
+      currentSession?.accessToken
+      && currentSession.accessTokenExpires
+      && Date.now() < currentSession.accessTokenExpires - TOKEN_EXPIRY_BUFFER_MS
+      && !currentSession.error
+    ) {
+      return currentSession.accessToken;
+    }
+
+    // Token is expired or missing -- wait for in-flight refresh or trigger one
+    const refreshed = await deduplicatedUpdate(
+      () => updateRef.current(),
+    ) as ImmutableSessionInternal | null;
+
+    if (!refreshed?.accessToken || refreshed.error) {
+      throw new Error(
+        `[auth-next-client] Failed to get access token: ${refreshed?.error || 'no session'}`,
+      );
+    }
+
+    // Update ref so subsequent sync reads get the fresh data
+    sessionRef.current = refreshed;
+    return refreshed.accessToken;
+  }, []); // Empty deps -- uses refs for latest values
+
+  // Cast to public type (omits accessToken) to prevent consumers from
+  // accidentally using a potentially stale token. Use getAccessToken() instead.
+  const publicSession = session as ImmutableSession | null;
+
   return {
-    session,
+    session: publicSession,
     status,
     isLoading,
     isAuthenticated,
     isRefreshing,
     getUser,
+    getAccessToken,
   };
 }