@imtbl/auth-next-client 2.12.5-alpha.13

package/src/provider.tsx

@@ -0,0 +1,547 @@
+'use client';
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useCallback,
+  useMemo,
+} from 'react';
+import {
+  SessionProvider, useSession, signIn, signOut,
+} from 'next-auth/react';
+import type { Session } from 'next-auth';
+import {
+  Auth, AuthEvents, type User, type LoginOptions, type UserRemovedReason,
+} from '@imtbl/auth';
+import type {
+  ImmutableAuthProviderProps,
+  UseImmutableAuthReturn,
+  ImmutableUserClient,
+  ImmutableTokenDataClient,
+} from './types';
+import { getTokenExpiry } from './utils/token';
+import {
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_AUDIENCE,
+  DEFAULT_SCOPE,
+  DEFAULT_NEXTAUTH_BASE_PATH,
+  IMMUTABLE_PROVIDER_ID,
+} from './constants';
+
+/**
+ * Internal context for Immutable auth state
+ */
+interface ImmutableAuthContextValue {
+  auth: Auth | null;
+  config: ImmutableAuthProviderProps['config'];
+  basePath: string;
+}
+
+const ImmutableAuthContext = createContext<ImmutableAuthContextValue | null>(null);
+
+/**
+ * Internal provider that manages Auth instance
+ */
+function ImmutableAuthInner({
+  children,
+  config,
+  basePath,
+}: {
+  children: React.ReactNode;
+  config: ImmutableAuthProviderProps['config'];
+  basePath: string;
+}) {
+  // Use state instead of ref so changes trigger re-renders and update context consumers
+  const [auth, setAuth] = useState<Auth | null>(null);
+  const prevConfigRef = useRef<string | null>(null);
+  // Track auth instance in a ref to check if it's still valid synchronously
+  // This is needed for React 18 Strict Mode compatibility
+  const authInstanceRef = useRef<Auth | null>(null);
+  const [isAuthReady, setIsAuthReady] = useState(false);
+  const { data: session, update: updateSession } = useSession();
+
+  // Initialize/reinitialize Auth instance when config changes (e.g., environment switch)
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+
+    // Create a config key to detect changes - include all properties used in Auth constructor
+    // to ensure the Auth instance is recreated when any config property changes
+    const configKey = [
+      config.clientId,
+      config.redirectUri,
+      config.popupRedirectUri || '',
+      config.logoutRedirectUri || '',
+      config.audience || DEFAULT_AUDIENCE,
+      config.scope || DEFAULT_SCOPE,
+      config.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+      config.passportDomain || '',
+    ].join(':');
+
+    // Only skip recreation if BOTH:
+    // 1. Config hasn't changed (same configKey)
+    // 2. Auth instance still exists (wasn't nullified by cleanup)
+    // This handles React 18 Strict Mode where effects run twice:
+    // setup → cleanup → setup. After cleanup, authInstanceRef is null,
+    // so we correctly recreate Auth on the second setup.
+    if (prevConfigRef.current === configKey && authInstanceRef.current !== null) {
+      return undefined;
+    }
+    prevConfigRef.current = configKey;
+
+    // Create new Auth instance with current config
+    const newAuth = new Auth({
+      clientId: config.clientId,
+      redirectUri: config.redirectUri,
+      popupRedirectUri: config.popupRedirectUri,
+      logoutRedirectUri: config.logoutRedirectUri,
+      audience: config.audience || DEFAULT_AUDIENCE,
+      scope: config.scope || DEFAULT_SCOPE,
+      authenticationDomain: config.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+      passportDomain: config.passportDomain,
+    });
+
+    authInstanceRef.current = newAuth;
+    setAuth(newAuth);
+    setIsAuthReady(true);
+
+    // Cleanup function: When config changes or component unmounts,
+    // clear the Auth instance to prevent memory leaks.
+    // The Auth class holds a UserManager from oidc-client-ts which may register
+    // window event listeners (storage, message). By setting auth to null,
+    // we allow garbage collection.
+    return () => {
+      authInstanceRef.current = null;
+      setAuth(null);
+      setIsAuthReady(false);
+    };
+  }, [config]);
+
+  // Listen for Auth events to sync tokens to NextAuth
+  useEffect(() => {
+    if (!auth || !isAuthReady) return undefined;
+
+    const handleLoggedIn = async (authUser: User) => {
+      // When Auth refreshes tokens, sync to NextAuth session
+      if (session?.accessToken && authUser.accessToken !== session.accessToken) {
+        await updateSession({
+          accessToken: authUser.accessToken,
+          refreshToken: authUser.refreshToken,
+          idToken: authUser.idToken,
+          accessTokenExpires: getTokenExpiry(authUser.accessToken),
+          zkEvm: authUser.zkEvm,
+        });
+      }
+    };
+
+    // Handle client-side token refresh - critical for refresh token rotation.
+    // When Auth refreshes tokens via signinSilent(), we must sync the new tokens
+    // (especially the new refresh token) to the NextAuth session. Without this,
+    // the server-side JWT callback may use a stale refresh token that Auth0 has
+    // already invalidated, causing "Unknown or invalid refresh token" errors.
+    const handleTokenRefreshed = async (authUser: User) => {
+      await updateSession({
+        accessToken: authUser.accessToken,
+        refreshToken: authUser.refreshToken,
+        idToken: authUser.idToken,
+        accessTokenExpires: getTokenExpiry(authUser.accessToken),
+        zkEvm: authUser.zkEvm,
+      });
+    };
+
+    // Handle user removal from Auth due to permanent auth errors
+    // (e.g., invalid_grant, login_required - refresh token is truly invalid).
+    // Transient errors (network, timeout, server errors) do NOT trigger this.
+    // When this happens, we must clear the NextAuth session to keep them in sync.
+    const handleUserRemoved = async (payload: { reason: UserRemovedReason; error?: string }) => {
+      // eslint-disable-next-line no-console
+      console.warn('[auth-next-client] User removed from Auth SDK:', payload.reason, payload.error);
+      // Sign out from NextAuth to clear the session cookie
+      // This prevents the state mismatch where session exists but Auth has no user
+      await signOut({ redirect: false });
+    };
+
+    // Handle explicit logout from Auth SDK (e.g., via auth.logout() or auth.getLogoutUrl())
+    // This ensures NextAuth session is always in sync with Auth SDK state
+    const handleLoggedOut = async () => {
+      // Sign out from NextAuth to clear the session cookie
+      await signOut({ redirect: false });
+    };
+
+    auth.eventEmitter.on(AuthEvents.LOGGED_IN, handleLoggedIn);
+    auth.eventEmitter.on(AuthEvents.TOKEN_REFRESHED, handleTokenRefreshed);
+    auth.eventEmitter.on(AuthEvents.USER_REMOVED, handleUserRemoved);
+    auth.eventEmitter.on(AuthEvents.LOGGED_OUT, handleLoggedOut);
+
+    return () => {
+      auth.eventEmitter.removeListener(AuthEvents.LOGGED_IN, handleLoggedIn);
+      auth.eventEmitter.removeListener(AuthEvents.TOKEN_REFRESHED, handleTokenRefreshed);
+      auth.eventEmitter.removeListener(AuthEvents.USER_REMOVED, handleUserRemoved);
+      auth.eventEmitter.removeListener(AuthEvents.LOGGED_OUT, handleLoggedOut);
+    };
+  }, [auth, isAuthReady, session, updateSession]);
+
+  const contextValue = useMemo(
+    () => ({ auth, config, basePath }),
+    [auth, config, basePath],
+  );
+
+  return (
+    <ImmutableAuthContext.Provider value={contextValue}>
+      {children}
+    </ImmutableAuthContext.Provider>
+  );
+}
+
+/**
+ * Provider component for Immutable authentication with Auth.js v5
+ *
+ * Wraps your app to provide authentication state via useImmutableAuth hook.
+ *
+ * @example App Router (recommended)
+ * ```tsx
+ * // app/providers.tsx
+ * "use client";
+ * import { ImmutableAuthProvider } from "@imtbl/auth-next-client";
+ *
+ * const config = {
+ *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+ *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+ * };
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <ImmutableAuthProvider config={config}>
+ *       {children}
+ *     </ImmutableAuthProvider>
+ *   );
+ * }
+ * ```
+ */
+export function ImmutableAuthProvider({
+  children,
+  config,
+  session,
+  basePath = DEFAULT_NEXTAUTH_BASE_PATH,
+}: ImmutableAuthProviderProps) {
+  return (
+    <SessionProvider session={session as Session | null | undefined} basePath={basePath}>
+      <ImmutableAuthInner config={config} basePath={basePath}>{children}</ImmutableAuthInner>
+    </SessionProvider>
+  );
+}
+
+/**
+ * Hook to access Immutable authentication state and methods
+ *
+ * Must be used within an ImmutableAuthProvider.
+ */
+export function useImmutableAuth(): UseImmutableAuthReturn {
+  const context = useContext(ImmutableAuthContext);
+  const { data: sessionData, status } = useSession();
+  const [isLoggingIn, setIsLoggingIn] = useState(false);
+
+  if (!context) {
+    throw new Error('useImmutableAuth must be used within ImmutableAuthProvider');
+  }
+
+  // Cast session to our augmented Session type
+  const session = sessionData as Session | null;
+
+  const { auth } = context;
+  const isLoading = status === 'loading';
+  const isAuthenticated = status === 'authenticated' && !!session;
+
+  // Extract user from session
+  const user: ImmutableUserClient | null = session?.user
+    ? {
+      sub: session.user.sub,
+      email: session.user.email,
+      nickname: session.user.nickname,
+    }
+    : null;
+
+  // Sign in with Immutable popup
+  const handleSignIn = useCallback(async (options?: LoginOptions) => {
+    if (!auth) {
+      throw new Error('Auth not initialized');
+    }
+
+    setIsLoggingIn(true);
+    try {
+      // Open popup login with optional login options
+      const authUser = await auth.login(options);
+      if (!authUser) {
+        throw new Error('Login failed');
+      }
+
+      // Build token data for NextAuth
+      const tokenData: ImmutableTokenDataClient = {
+        accessToken: authUser.accessToken,
+        refreshToken: authUser.refreshToken,
+        idToken: authUser.idToken,
+        accessTokenExpires: getTokenExpiry(authUser.accessToken),
+        profile: {
+          sub: authUser.profile.sub,
+          email: authUser.profile.email,
+          nickname: authUser.profile.nickname,
+        },
+        zkEvm: authUser.zkEvm,
+      };
+
+      // Sign in to NextAuth with the tokens
+      const result = await signIn(IMMUTABLE_PROVIDER_ID, {
+        tokens: JSON.stringify(tokenData),
+        redirect: false,
+      });
+
+      // signIn with redirect: false returns a result object instead of throwing
+      if (result?.error) {
+        throw new Error(`NextAuth sign-in failed: ${result.error}`);
+      }
+      if (!result?.ok) {
+        throw new Error('NextAuth sign-in failed: unknown error');
+      }
+    } finally {
+      setIsLoggingIn(false);
+    }
+  }, [auth]);
+
+  // Sign out from both NextAuth and Immutable
+  const handleSignOut = useCallback(async () => {
+    if (auth) {
+      try {
+        // Clear local Auth state - this emits LOGGED_OUT event which triggers
+        // handleLoggedOut listener to call signOut() from NextAuth
+        await auth.getLogoutUrl();
+      } catch (error) {
+        // If getLogoutUrl fails, fall back to direct signOut
+        // eslint-disable-next-line no-console
+        console.warn('[auth-next-client] Logout cleanup error:', error);
+        await signOut({ redirect: false });
+      }
+    } else {
+      // No auth instance, just sign out from NextAuth directly
+      await signOut({ redirect: false });
+    }
+  }, [auth]);
+
+  // Get access token (refreshes if needed)
+  const getAccessToken = useCallback(async (): Promise<string> => {
+    // First try to get from Auth instance (most up-to-date)
+    if (auth) {
+      try {
+        const token = await auth.getAccessToken();
+        if (token) {
+          return token;
+        }
+      } catch {
+        // Fall through to session
+      }
+    }
+
+    // Fall back to session token, but check for errors first.
+    // Session errors indicate authentication issues that require user action:
+    // - "TokenExpired": Access token expired and Auth instance couldn't refresh
+    //   (this happens if localStorage was cleared but session cookie remains)
+    // - "RefreshTokenError": Refresh token is invalid/expired, need re-login
+    if (session?.error) {
+      throw new Error(
+        session.error === 'TokenExpired'
+          ? 'Session expired. Please log in again.'
+          : `Authentication error: ${session.error}`,
+      );
+    }
+
+    if (session?.accessToken) {
+      return session.accessToken;
+    }
+
+    throw new Error('No access token available');
+  }, [auth, session]);
+
+  return {
+    user,
+    session,
+    isLoading,
+    isLoggingIn,
+    isAuthenticated,
+    signIn: handleSignIn,
+    signOut: handleSignOut,
+    getAccessToken,
+    auth,
+  };
+}
+
+/**
+ * Hook to get a function that returns a valid access token
+ */
+export function useAccessToken(): () => Promise<string> {
+  const { getAccessToken } = useImmutableAuth();
+  return getAccessToken;
+}
+
+/**
+ * Result from useHydratedData hook
+ */
+export interface UseHydratedDataResult<T> {
+  data: T | null;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+/**
+ * Props for useHydratedData hook - matches AuthPropsWithData from server
+ */
+export interface HydratedDataProps<T> {
+  session: Session | null;
+  ssr: boolean;
+  data: T | null;
+  fetchError?: string;
+  authError?: string;
+}
+
+/**
+ * Hook for hydrating server-fetched data with automatic client-side fallback.
+ *
+ * This is the recommended pattern for components that receive data from `getAuthenticatedData`:
+ * - When `ssr: true` and `data` exists: Uses pre-fetched server data immediately (no loading state)
+ * - When `ssr: false`: Refreshes token client-side and fetches data
+ * - When `fetchError` exists: Retries fetch client-side
+ */
+export function useHydratedData<T>(
+  props: HydratedDataProps<T>,
+  fetcher: (accessToken: string) => Promise<T>,
+): UseHydratedDataResult<T> {
+  const { getAccessToken, auth } = useImmutableAuth();
+  const {
+    ssr,
+    data: serverData,
+    fetchError,
+  } = props;
+
+  // Determine if we need to fetch client-side:
+  // 1. SSR was skipped (token expired) - need to refresh token and fetch
+  // 2. Server fetch failed - retry on client
+  // Note: We intentionally do NOT check serverData === null here.
+  // When ssr=true and no fetchError, null is a valid response (e.g., "no results found")
+  // and should not trigger a client-side refetch.
+  const needsClientFetch = !ssr || Boolean(fetchError);
+
+  // Initialize state with server data if available
+  const [data, setData] = useState<T | null>(serverData);
+  const [isLoading, setIsLoading] = useState(needsClientFetch);
+  const [error, setError] = useState<Error | null>(
+    fetchError ? new Error(fetchError) : null,
+  );
+
+  // Track if we've already started fetching to prevent duplicate calls
+  const hasFetchedRef = useRef(false);
+
+  // Fetch ID counter to detect stale fetches.
+  // When props change, we increment this counter. In-flight fetches compare their
+  // captured ID against the current counter and ignore results if they don't match.
+  // This prevents race conditions where a slow client-side fetch overwrites
+  // fresh server data that arrived via prop changes (e.g., during soft navigation).
+  const fetchIdRef = useRef(0);
+
+  // Track previous props to detect changes (for navigation between routes)
+  const prevPropsRef = useRef({ serverData, ssr, fetchError });
+
+  // Sync state when props change (e.g., navigating between routes with same component).
+  // useState only uses initial value on mount - subsequent prop changes are ignored
+  // unless we explicitly sync them.
+  useEffect(() => {
+    const prevProps = prevPropsRef.current;
+    const propsChanged = prevProps.serverData !== serverData
+      || prevProps.ssr !== ssr
+      || prevProps.fetchError !== fetchError;
+
+    if (propsChanged) {
+      prevPropsRef.current = { serverData, ssr, fetchError };
+      // Reset fetch guard to allow fetching with new props
+      hasFetchedRef.current = false;
+      // Increment fetch ID to invalidate any in-flight fetches
+      fetchIdRef.current += 1;
+
+      // Sync state from new props
+      if (ssr && !fetchError) {
+        // SSR succeeded: use server data directly (even if null - that's valid)
+        setData(serverData);
+        setIsLoading(false);
+        setError(null);
+      } else {
+        // Need client-side fetch: reset state to trigger fetch
+        setData(null);
+        setIsLoading(true);
+        setError(fetchError ? new Error(fetchError) : null);
+      }
+    }
+  }, [serverData, ssr, fetchError]);
+
+  const fetchData = useCallback(async () => {
+    // Capture current fetch ID to detect staleness after async operations
+    const currentFetchId = fetchIdRef.current;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Always get the current valid token via getAccessToken()
+      // This handles token refresh and uses the live session from useSession()
+      // rather than stale props.session which doesn't update after client-side refresh
+      const token = await getAccessToken();
+      const result = await fetcher(token);
+
+      // Only update state if this fetch is still current.
+      // If props changed while we were fetching, fetchIdRef will have been incremented
+      // and our captured ID will be stale - discard results to avoid overwriting
+      // fresh server data with stale client-fetched results.
+      if (fetchIdRef.current === currentFetchId) {
+        setData(result);
+      }
+    } catch (err) {
+      // Only update error state if this fetch is still current
+      if (fetchIdRef.current === currentFetchId) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      // Only update loading state if this fetch is still current
+      if (fetchIdRef.current === currentFetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [fetcher, getAccessToken]);
+
+  // Fetch client-side data when needed
+  // When ssr is false (token expired server-side), we must wait for the Auth instance
+  // to be initialized before fetching. Auth is created in a parent component's effect
+  // which runs AFTER this (child) effect due to React's bottom-up effect execution.
+  // Without waiting for auth, getAccessToken() would find auth === null, fall through
+  // to check the session (which has an error because token is expired), and throw
+  // "Session expired" instead of properly refreshing the token via Auth.
+  useEffect(() => {
+    // Already fetched, don't fetch again
+    if (hasFetchedRef.current) return;
+
+    // Don't need client fetch
+    if (!needsClientFetch) return;
+
+    // When ssr is false, we need Auth to refresh the expired token.
+    // Wait for it to initialize before attempting to fetch.
+    if (!ssr && !auth) return;
+
+    hasFetchedRef.current = true;
+    fetchData();
+  }, [needsClientFetch, ssr, auth, fetchData]);
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData,
+  };
+}

package/src/types.ts

@@ -0,0 +1,148 @@
+import type { DefaultSession, Session } from 'next-auth';
+
+// Re-export types from auth-next-server for convenience
+export type {
+  ImmutableAuthConfig,
+  ImmutableTokenData,
+  ZkEvmUser,
+  ImmutableUser,
+} from '@imtbl/auth-next-server';
+
+/**
+ * zkEVM wallet information
+ */
+export interface ZkEvmInfo {
+  ethAddress: string;
+  userAdminAddress: string;
+}
+
+/**
+ * Auth.js v5 module augmentation to add Immutable-specific fields
+ */
+declare module 'next-auth' {
+  // eslint-disable-next-line @typescript-eslint/no-shadow
+  interface Session extends DefaultSession {
+    user: {
+      sub: string;
+      email?: string;
+      nickname?: string;
+    } & DefaultSession['user'];
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpires: number;
+    zkEvm?: ZkEvmInfo;
+    error?: string;
+  }
+
+  interface User {
+    id: string;
+    sub: string;
+    email?: string | null;
+    nickname?: string;
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpires: number;
+    zkEvm?: ZkEvmInfo;
+  }
+}
+
+/**
+ * Props for ImmutableAuthProvider
+ */
+export interface ImmutableAuthProviderProps {
+  children: React.ReactNode;
+  /**
+   * Immutable auth configuration
+   */
+  config: {
+    clientId: string;
+    redirectUri: string;
+    popupRedirectUri?: string;
+    logoutRedirectUri?: string;
+    audience?: string;
+    scope?: string;
+    authenticationDomain?: string;
+    passportDomain?: string;
+  };
+  /**
+   * Initial session from server (for SSR hydration)
+   * Can be Session from auth() or any compatible session object
+   */
+  session?: Session | DefaultSession | null;
+  /**
+   * Custom base path for Auth.js API routes
+   * Use this when you have multiple auth endpoints (e.g., per environment)
+   * @default "/api/auth"
+   */
+  basePath?: string;
+}
+
+/**
+ * User profile from Immutable (local definition for client)
+ */
+export interface ImmutableUserClient {
+  sub: string;
+  email?: string;
+  nickname?: string;
+}
+
+/**
+ * Token data passed from client to Auth.js credentials provider
+ */
+export interface ImmutableTokenDataClient {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  accessTokenExpires: number;
+  profile: {
+    sub: string;
+    email?: string;
+    nickname?: string;
+  };
+  zkEvm?: ZkEvmInfo;
+}
+
+/**
+ * Return type of useImmutableAuth hook
+ */
+export interface UseImmutableAuthReturn {
+  /**
+   * Current user profile (null if not authenticated)
+   */
+  user: ImmutableUserClient | null;
+  /**
+   * Full Auth.js session with tokens
+   */
+  session: Session | null;
+  /**
+   * Whether authentication state is loading (initial session fetch)
+   */
+  isLoading: boolean;
+  /**
+   * Whether a login flow is in progress (popup open, waiting for OAuth callback)
+   */
+  isLoggingIn: boolean;
+  /**
+   * Whether user is authenticated
+   */
+  isAuthenticated: boolean;
+  /**
+   * Sign in with Immutable (opens popup)
+   * @param options - Optional login options (cached session, silent login, redirect flow, direct login)
+   */
+  signIn: (options?: import('@imtbl/auth').LoginOptions) => Promise<void>;
+  /**
+   * Sign out from both Auth.js and Immutable
+   */
+  signOut: () => Promise<void>;
+  /**
+   * Get a valid access token (refreshes if needed)
+   */
+  getAccessToken: () => Promise<string>;
+  /**
+   * The underlying Auth instance (for advanced use)
+   */
+  auth: import('@imtbl/auth').Auth | null;
+}