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

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@imtbl/auth-next-client",
+  "version": "2.12.5-alpha.13",
+  "description": "Immutable Auth.js v5 integration for Next.js - Client-side components",
+  "author": "Immutable",
+  "license": "Apache-2.0",
+  "repository": "immutable/ts-immutable-sdk.git",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/node/index.cjs",
+  "module": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "require": "./dist/node/index.cjs",
+        "default": "./dist/node/index.js"
+      },
+      "default": {
+        "types": "./dist/node/index.d.ts",
+        "require": "./dist/node/index.cjs",
+        "default": "./dist/node/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@imtbl/auth": "2.12.5-alpha.13",
+    "@imtbl/auth-next-server": "2.12.5-alpha.13"
+  },
+  "peerDependencies": {
+    "next": "^14.2.0 || ^15.0.0",
+    "next-auth": "^5.0.0-beta.25",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "next-auth": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@swc/core": "^1.4.2",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.7",
+    "@types/react": "^18.3.5",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "next": "^15.1.6",
+    "next-auth": "^5.0.0-beta.30",
+    "react": "^18.2.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "scripts": {
+    "build": "tsup && pnpm build:types",
+    "build:types": "tsc --project tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/**/*.{ts,tsx} --max-warnings=0",
+    "test": "jest --passWithNoTests"
+  }
+}

package/src/callback.tsx

@@ -0,0 +1,281 @@
+'use client';
+
+import React, { useEffect, useState, useRef } from 'react';
+import { useRouter } from 'next/navigation';
+import { signIn } from 'next-auth/react';
+import { Auth } from '@imtbl/auth';
+import type { ImmutableUserClient, ImmutableTokenDataClient } from './types';
+import { getTokenExpiry } from './utils/token';
+import {
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_AUDIENCE,
+  DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID,
+} from './constants';
+
+/**
+ * Get search params from the current URL.
+ * Uses window.location.search directly to avoid issues with useSearchParams()
+ * in Pages Router, where the hook may not be hydrated during initial render.
+ */
+function getSearchParams(): URLSearchParams {
+  if (typeof window === 'undefined') {
+    return new URLSearchParams();
+  }
+  return new URLSearchParams(window.location.search);
+}
+
+/**
+ * Config for CallbackPage
+ */
+interface CallbackConfig {
+  clientId: string;
+  redirectUri: string;
+  popupRedirectUri?: string;
+  logoutRedirectUri?: string;
+  audience?: string;
+  scope?: string;
+  authenticationDomain?: string;
+  passportDomain?: string;
+}
+
+export interface CallbackPageProps {
+  /**
+   * Immutable auth configuration
+   */
+  config: CallbackConfig;
+  /**
+   * URL to redirect to after successful authentication (when not in popup).
+   * Can be a string or a function that receives the authenticated user.
+   * If a function returns void/undefined, defaults to "/".
+   * @default "/"
+   */
+  redirectTo?: string | ((user: ImmutableUserClient) => string | void);
+  /**
+   * Custom loading component
+   */
+  loadingComponent?: React.ReactElement | null;
+  /**
+   * Custom error component
+   */
+  errorComponent?: (error: string) => React.ReactElement | null;
+  /**
+   * Callback fired after successful authentication.
+   * Receives the authenticated user as a parameter.
+   * Called before redirect (non-popup) or before window.close (popup).
+   * If this callback returns a Promise, it will be awaited before proceeding.
+   */
+  onSuccess?: (user: ImmutableUserClient) => void | Promise<void>;
+  /**
+   * Callback fired when authentication fails.
+   * Receives the error message as a parameter.
+   * Called before the error UI is displayed.
+   */
+  onError?: (error: string) => void;
+}
+
+/**
+ * Callback page component for handling OAuth redirects (App Router version).
+ *
+ * Use this in your callback page to process authentication responses.
+ */
+export function CallbackPage({
+  config,
+  redirectTo = '/',
+  loadingComponent = null,
+  errorComponent,
+  onSuccess,
+  onError,
+}: CallbackPageProps) {
+  const router = useRouter();
+  const [error, setError] = useState<string | null>(null);
+  // Track whether callback has been processed to prevent double invocation
+  // (React 18 StrictMode runs effects twice, and OAuth codes are single-use)
+  const callbackProcessedRef = useRef(false);
+
+  useEffect(() => {
+    // Get search params directly from window.location to ensure compatibility
+    // with both App Router and Pages Router. useSearchParams() from next/navigation
+    // has hydration issues in Pages Router where params may be empty initially.
+    const searchParams = getSearchParams();
+
+    const handleCallback = async () => {
+      try {
+        // Create Auth instance to handle the callback
+        const auth = 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,
+        });
+
+        // Process the callback - this extracts tokens from the URL and returns the user
+        const authUser = await auth.loginCallback();
+
+        // Check if we're in a popup window
+        if (window.opener) {
+          // Validate authUser before closing - if loginCallback failed silently,
+          // we need to show an error instead of closing the popup
+          if (!authUser) {
+            throw new Error('Authentication failed: no user data received from login callback');
+          }
+          // Create user object for callbacks
+          const user: ImmutableUserClient = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname,
+          };
+          // Call onSuccess callback before closing popup
+          if (onSuccess) {
+            await onSuccess(user);
+          }
+          // Close the popup - the parent window will receive the tokens via Auth events
+          window.close();
+        } else if (authUser) {
+          // Not in a popup - create NextAuth session before redirecting
+          // This ensures SSR/session-based auth is authenticated
+          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
+          // Note: signIn uses the basePath from SessionProvider context,
+          // so ensure CallbackPage is rendered within ImmutableAuthProvider
+          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');
+          }
+
+          // Create user object for callbacks and dynamic redirect
+          const user: ImmutableUserClient = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname,
+          };
+
+          // Call onSuccess callback before redirect
+          if (onSuccess) {
+            await onSuccess(user);
+          }
+
+          // Resolve redirect path (can be string or function)
+          const resolvedRedirectTo = typeof redirectTo === 'function'
+            ? redirectTo(user) || '/'
+            : redirectTo;
+
+          // Only redirect after successful session creation
+          router.replace(resolvedRedirectTo);
+        } else {
+          // authUser is undefined - loginCallback failed silently
+          // This can happen if the OIDC signinCallback returns null
+          throw new Error('Authentication failed: no user data received from login callback');
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Authentication failed';
+        if (onError) {
+          onError(errorMessage);
+        }
+        setError(errorMessage);
+      }
+    };
+
+    const handleOAuthError = () => {
+      // OAuth providers return error and error_description when authentication fails
+      // (e.g., user cancels, consent denied, invalid request)
+      const errorCode = searchParams.get('error');
+      const errorDescription = searchParams.get('error_description');
+
+      const errorMessage = errorDescription || errorCode || 'Authentication failed';
+      if (onError) {
+        onError(errorMessage);
+      }
+      setError(errorMessage);
+    };
+
+    // Guard against double invocation (React 18 StrictMode runs effects twice)
+    if (callbackProcessedRef.current) {
+      return;
+    }
+
+    const hasError = searchParams.get('error');
+    const hasCode = searchParams.get('code');
+
+    // Handle OAuth error responses (user cancelled, consent denied, etc.)
+    if (hasError) {
+      callbackProcessedRef.current = true;
+      handleOAuthError();
+      return;
+    }
+
+    // Handle successful OAuth callback with authorization code
+    if (hasCode) {
+      callbackProcessedRef.current = true;
+      handleCallback();
+      return;
+    }
+
+    // No OAuth parameters present - user navigated directly to callback page,
+    // bookmarked it, or OAuth redirect lost its parameters
+    callbackProcessedRef.current = true;
+    const errorMessage = 'Invalid callback: missing OAuth parameters. Please try logging in again.';
+    if (onError) {
+      onError(errorMessage);
+    }
+    setError(errorMessage);
+  }, [router, config, redirectTo, onSuccess, onError]);
+
+  if (error) {
+    if (errorComponent) {
+      return errorComponent(error);
+    }
+
+    return (
+      <div style={{ padding: '2rem', textAlign: 'center' }}>
+        <h2 style={{ color: '#dc3545' }}>Authentication Error</h2>
+        <p>{error}</p>
+        <button
+          onClick={() => router.push('/')}
+          type="button"
+          style={{
+            padding: '0.5rem 1rem',
+            marginTop: '1rem',
+            cursor: 'pointer',
+          }}
+        >
+          Return to Home
+        </button>
+      </div>
+    );
+  }
+
+  if (loadingComponent) {
+    return loadingComponent;
+  }
+
+  return (
+    <div style={{ padding: '2rem', textAlign: 'center' }}>
+      <p>Completing authentication...</p>
+    </div>
+  );
+}

package/src/constants.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared constants for @imtbl/auth-next-client
+ */
+
+/**
+ * Default Immutable authentication domain
+ */
+export const DEFAULT_AUTH_DOMAIN = 'https://auth.immutable.com';
+
+/**
+ * Default OAuth audience
+ */
+export const DEFAULT_AUDIENCE = 'platform_api';
+
+/**
+ * Default OAuth scopes
+ */
+export const DEFAULT_SCOPE = 'openid profile email offline_access transact';
+
+/**
+ * NextAuth credentials provider ID for Immutable
+ */
+export const IMMUTABLE_PROVIDER_ID = 'immutable';
+
+/**
+ * Default NextAuth API base path
+ */
+export const DEFAULT_NEXTAUTH_BASE_PATH = '/api/auth';
+
+/**
+ * Default token expiry in seconds (15 minutes)
+ * Used as fallback when exp claim cannot be extracted from JWT
+ */
+export const DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
+
+/**
+ * Default token expiry in milliseconds
+ */
+export const DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1000;

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @imtbl/auth-next-client
+ *
+ * Client-side components for Immutable Auth.js v5 integration with Next.js.
+ * This package provides React components and hooks for authentication.
+ *
+ * Note: This package depends on @imtbl/auth and should only be used in
+ * browser/client environments. For server-side utilities, use @imtbl/auth-next-server.
+ */
+
+// Client-side components and hooks
+export {
+  ImmutableAuthProvider,
+  useImmutableAuth,
+  useAccessToken,
+  useHydratedData,
+  type UseHydratedDataResult,
+  type HydratedDataProps,
+} from './provider';
+
+export { CallbackPage, type CallbackPageProps } from './callback';
+
+// Re-export types
+export type {
+  ImmutableAuthProviderProps,
+  UseImmutableAuthReturn,
+  ImmutableUserClient,
+  ImmutableTokenDataClient,
+  ZkEvmInfo,
+} from './types';
+
+// Re-export server types for convenience (commonly used together)
+export type {
+  ImmutableAuthConfig,
+  ImmutableTokenData,
+  ImmutableUser,
+  AuthProps,
+  AuthPropsWithData,
+  ProtectedAuthProps,
+  ProtectedAuthPropsWithData,
+} from '@imtbl/auth-next-server';
+
+// Re-export login-related types from @imtbl/auth for convenience
+export type { LoginOptions, DirectLoginOptions } from '@imtbl/auth';
+export { MarketingConsentStatus } from '@imtbl/auth';