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

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,75 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect,
 } from '@imtbl/auth';
-import { IMMUTABLE_PROVIDER_ID } from './constants';
+import { deriveDefaultRedirectUri } from './defaultConfig';
+import {
+  IMMUTABLE_PROVIDER_ID,
+  TOKEN_EXPIRY_BUFFER_MS,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_SCOPE,
+  DEFAULT_AUDIENCE,
+} from './constants';
+import { storeIdToken, getStoredIdToken, clearStoredIdToken } from './idTokenStorage';
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// Sandbox defaults for zero-config (no config or full config - no merge)
+// ---------------------------------------------------------------------------
+
+function getSandboxLoginConfig(): LoginConfig {
+  const redirectUri = deriveDefaultRedirectUri();
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    redirectUri,
+    popupRedirectUri: redirectUri,
+    scope: DEFAULT_SCOPE,
+    audience: DEFAULT_AUDIENCE,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
+  };
+}
+
+function getSandboxLogoutConfig(): LogoutConfig {
+  if (typeof window === 'undefined') {
+    throw new Error(
+      '[auth-next-client] getSandboxLogoutConfig requires window. '
+      + 'Logout runs in the browser when the user triggers it.',
+    );
+  }
+  const logoutRedirectUri = window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    logoutRedirectUri,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
+  };
+}
+
+/**
+ * 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 +95,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 +127,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 +173,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 +195,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 +206,44 @@ 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]);
+
+  // ---------------------------------------------------------------------------
+  // Sync idToken to localStorage
+  // ---------------------------------------------------------------------------
+
+  // The idToken is stripped from the cookie by jwt.encode on the server to avoid
+  // CloudFront 413 errors. It is only present in the session response transiently
+  // after sign-in or token refresh. When present, persist it in localStorage so
+  // that getUser() can always return it (used by wallet's MagicTEESigner).
+  useEffect(() => {
+    if (session?.idToken) {
+      storeIdToken(session.idToken);
+    }
+  }, [session?.idToken]);
+
   /**
    * Get user function for wallet integration.
    * Returns a User object compatible with @imtbl/wallet's getUser option.
@@ -135,7 +254,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,10 +264,14 @@ 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;
+          // Immediately persist fresh idToken to localStorage (avoids race with useEffect)
+          if (currentSession.idToken) {
+            storeIdToken(currentSession.idToken);
+          }
         }
       } catch (error) {
         // eslint-disable-next-line no-console
@@ -158,6 +281,20 @@ 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;
+        // Persist fresh idToken to localStorage immediately
+        if (currentSession.idToken) {
+          storeIdToken(currentSession.idToken);
+        }
+      } else {
+        currentSession = sessionRef.current;
+      }
     } else {
       // Read from ref - instant, no network call
       // The ref is always updated on each render with the latest session
@@ -178,7 +315,9 @@ export function useImmutableSession(): UseImmutableSessionReturn {
     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 ?? undefined,
@@ -188,26 +327,71 @@ 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,
   };
 }
 
 /**
  * Return type for useLogin hook
+ *
+ * Config is optional - when omitted, defaults are auto-derived (clientId, redirectUri, etc.).
+ * When provided, must be a complete LoginConfig.
  */
 export interface UseLoginReturn {
   /** Start login with popup flow */
-  loginWithPopup: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+  loginWithPopup: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
   /** Start login with embedded modal flow */
-  loginWithEmbedded: (config: LoginConfig) => Promise<void>;
+  loginWithEmbedded: (config?: LoginConfig) => Promise<void>;
   /** Start login with redirect flow (navigates away from page) */
-  loginWithRedirect: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+  loginWithRedirect: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
   /** Whether login is currently in progress */
   isLoggingIn: boolean;
   /** Error message from the last login attempt, or null if none */
@@ -215,39 +399,70 @@ export interface UseLoginReturn {
 }
 
 /**
- * Hook to handle Immutable authentication login flows.
+ * Hook to handle Immutable authentication login flows with automatic defaults.
  *
  * Provides login functions that:
  * 1. Handle OAuth authentication via popup, embedded modal, or redirect
  * 2. Automatically sign in to NextAuth after successful authentication
  * 3. Track loading and error states
+ * 4. Auto-detect clientId and redirectUri if not provided (uses defaults)
  *
- * Config is passed at call time to allow different configurations for different
- * login methods (e.g., different redirectUri vs popupRedirectUri).
+ * Config can be passed at call time or omitted to use sensible defaults:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `redirectUri`: Auto-derived from `window.location.origin + '/callback'`
+ * - `popupRedirectUri`: Auto-derived from `window.location.origin + '/callback'` (same as redirectUri)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ * - `scope`: `'openid profile email offline_access transact'`
+ * - `audience`: `'platform_api'`
+ * - `authenticationDomain`: `'https://auth.immutable.com'`
  *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const config = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
- *   popupRedirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback/popup`,
- * };
+ * function LoginButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { loginWithPopup, isLoggingIn, error } = useLogin();
+ *
+ *   if (isAuthenticated) {
+ *     return <p>You are logged in!</p>;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => loginWithPopup()} disabled={isLoggingIn}>
+ *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LoginButton() {
  *   const { isAuthenticated } = useImmutableSession();
  *   const { loginWithPopup, isLoggingIn, error } = useLogin();
  *
+ *   const handleLogin = () => {
+ *     loginWithPopup({
+ *       clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *       redirectUri: `${window.location.origin}/callback`,
+ *     });
+ *   };
+ *
  *   if (isAuthenticated) {
  *     return <p>You are logged in!</p>;
  *   }
  *
  *   return (
  *     <>
- *       <button onClick={() => loginWithPopup(config)} disabled={isLoggingIn}>
+ *       <button onClick={handleLogin} disabled={isLoggingIn}>
  *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
@@ -271,6 +486,12 @@ export function useLogin(): UseLoginReturn {
     profile: { sub: string; email?: string; nickname?: string };
     zkEvm?: ZkEvmInfo;
   }) => {
+    // Persist idToken to localStorage before signIn so it's available immediately.
+    // The cookie won't contain idToken (stripped by jwt.encode on the server).
+    if (tokens.idToken) {
+      storeIdToken(tokens.idToken);
+    }
+
     const result = await signIn(IMMUTABLE_PROVIDER_ID, {
       tokens: JSON.stringify(tokens),
       redirect: false,
@@ -287,16 +508,18 @@ export function useLogin(): UseLoginReturn {
   /**
    * Login with a popup window.
    * Opens a popup for OAuth authentication, then signs in to NextAuth.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
   const loginWithPopup = useCallback(async (
-    config: LoginConfig,
+    config?: LoginConfig,
     options?: StandaloneLoginOptions,
   ): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      const tokens = await rawLoginWithPopup(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithPopup(fullConfig, options);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -310,13 +533,15 @@ export function useLogin(): UseLoginReturn {
   /**
    * Login with an embedded modal.
    * Shows a modal for login method selection, then opens a popup for OAuth.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
-  const loginWithEmbedded = useCallback(async (config: LoginConfig): Promise<void> => {
+  const loginWithEmbedded = useCallback(async (config?: LoginConfig): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      const tokens = await rawLoginWithEmbedded(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithEmbedded(fullConfig);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -332,16 +557,18 @@ export function useLogin(): UseLoginReturn {
    * Redirects the page to OAuth authentication.
    * After authentication, the user will be redirected to your callback page.
    * Use the CallbackPage component to complete the flow.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
   const loginWithRedirect = useCallback(async (
-    config: LoginConfig,
+    config?: LoginConfig,
     options?: StandaloneLoginOptions,
   ): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      await rawLoginWithRedirect(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      await rawLoginWithRedirect(fullConfig, options);
       // Note: The page will redirect, so this code may not run
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -371,9 +598,11 @@ export interface UseLogoutReturn {
    * This ensures that when the user logs in again, they will be prompted to select
    * an account instead of being automatically logged in with the previous account.
    *
-   * @param config - Logout configuration with clientId and optional redirectUri
+   * Config is optional - defaults will be auto-derived if not provided.
+   *
+   * @param config - Optional logout configuration with clientId and optional redirectUri
    */
-  logout: (config: LogoutConfig) => Promise<void>;
+  logout: (config?: LogoutConfig) => Promise<void>;
   /** Whether logout is currently in progress */
   isLoggingOut: boolean;
   /** Error message from the last logout attempt, or null if none */
@@ -391,16 +620,38 @@ export interface UseLogoutReturn {
  * an account (for social logins like Google) instead of being automatically logged
  * in with the previous account.
  *
+ * Config is optional - defaults will be auto-derived if not provided:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const logoutConfig = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   logoutRedirectUri: process.env.NEXT_PUBLIC_BASE_URL!,
- * };
+ * function LogoutButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { logout, isLoggingOut, error } = useLogout();
+ *
+ *   if (!isAuthenticated) {
+ *     return null;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => logout()} disabled={isLoggingOut}>
+ *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LogoutButton() {
  *   const { isAuthenticated } = useImmutableSession();
@@ -412,7 +663,13 @@ export interface UseLogoutReturn {
  *
  *   return (
  *     <>
- *       <button onClick={() => logout(logoutConfig)} disabled={isLoggingOut}>
+ *       <button
+ *         onClick={() => logout({
+ *           clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *           logoutRedirectUri: `${window.location.origin}/custom-logout`,
+ *         })}
+ *         disabled={isLoggingOut}
+ *       >
  *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
@@ -428,20 +685,27 @@ export function useLogout(): UseLogoutReturn {
   /**
    * Logout with federated logout.
    * First clears the NextAuth session, then redirects to the auth domain's logout endpoint.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
-  const logout = useCallback(async (config: LogoutConfig): Promise<void> => {
+  const logout = useCallback(async (config?: LogoutConfig): Promise<void> => {
     setIsLoggingOut(true);
     setError(null);
 
     try {
+      // Clear idToken from localStorage before clearing session
+      clearStoredIdToken();
+
       // First, clear the NextAuth session (this clears the JWT cookie)
       // We use redirect: false to handle the redirect ourselves for federated logout
       await signOut({ redirect: false });
 
+      // Create full config with defaults
+      const fullConfig = config ?? getSandboxLogoutConfig();
+
       // Redirect to the auth domain's logout endpoint using the standalone function
       // This clears the upstream session (Auth0/Immutable) so that on next login,
       // the user will be prompted to select an account instead of auto-logging in
-      rawLogoutWithRedirect(config);
+      rawLogoutWithRedirect(fullConfig);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Logout failed';
       setError(errorMessage);

package/src/idTokenStorage.ts

@@ -0,0 +1,56 @@
+/**
+ * Utility for persisting idToken in localStorage.
+ *
+ * The idToken is stripped from the NextAuth session cookie (via a custom
+ * jwt.encode in @imtbl/auth-next-server) to keep cookie size under CDN header
+ * limits (CloudFront 20 KB). Instead, the client stores idToken in
+ * localStorage so that wallet operations (e.g., MagicTEESigner) can still
+ * access it via getUser().
+ *
+ * All functions are safe to call during SSR or in restricted environments
+ * (e.g., incognito mode with localStorage disabled) -- they silently no-op.
+ */
+
+const ID_TOKEN_STORAGE_KEY = 'imtbl_id_token';
+
+/**
+ * Store the idToken in localStorage.
+ * @param idToken - The raw ID token JWT string
+ */
+export function storeIdToken(idToken: string): void {
+  try {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      window.localStorage.setItem(ID_TOKEN_STORAGE_KEY, idToken);
+    }
+  } catch {
+    // Silently ignore -- localStorage may be unavailable (SSR, incognito, etc.)
+  }
+}
+
+/**
+ * Retrieve the idToken from localStorage.
+ * @returns The stored idToken, or undefined if not available.
+ */
+export function getStoredIdToken(): string | undefined {
+  try {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      return window.localStorage.getItem(ID_TOKEN_STORAGE_KEY) ?? undefined;
+    }
+  } catch {
+    // Silently ignore
+  }
+  return undefined;
+}
+
+/**
+ * Remove the idToken from localStorage (e.g., on logout).
+ */
+export function clearStoredIdToken(): void {
+  try {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      window.localStorage.removeItem(ID_TOKEN_STORAGE_KEY);
+    }
+  } catch {
+    // Silently ignore
+  }
+}

package/src/index.ts

@@ -59,3 +59,15 @@ export type {
   LogoutConfig,
 } from '@imtbl/auth';
 export { MarketingConsentStatus } from '@imtbl/auth';
+
+// Re-export constants and default config helpers for consumer convenience
+export {
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_AUDIENCE,
+  DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_REDIRECT_URI_PATH,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+} from './constants';
+export { deriveDefaultRedirectUri } from './defaultConfig';