@imtbl/auth 2.10.7-alpha.3 → 2.10.7-alpha.5

package/dist/types/Auth.d.ts

@@ -0,0 +1,129 @@
+import AuthManager from './authManager';
+import { IAuthConfiguration } from './config';
+import { AuthModuleConfiguration, User, DirectLoginOptions, DeviceTokenResponse, LoginOptions, AuthEventMap } from './types';
+import TypedEventEmitter from './utils/typedEventEmitter';
+/**
+ * Public-facing Auth class for authentication
+ * Wraps AuthManager with a simpler API
+ */
+export declare class Auth {
+    private authManager;
+    private config;
+    /**
+     * Event emitter for authentication events (LOGGED_IN, LOGGED_OUT)
+     * Exposed for wallet and passport packages to subscribe to auth state changes
+     */
+    readonly eventEmitter: TypedEventEmitter<AuthEventMap>;
+    /**
+     * Create a new Auth instance
+     *
+     * @param config - Auth configuration
+     *
+     * @example
+     * ```typescript
+     * import { Auth } from '@imtbl/auth';
+     *
+     * const auth = new Auth({
+     *   authenticationDomain: 'https://auth.immutable.com',
+     *   passportDomain: 'https://passport.immutable.com',
+     *   clientId: 'your-client-id',
+     *   redirectUri: 'https://your-app.com/callback',
+     *   scope: 'openid profile email transact',
+     * });
+     * ```
+     */
+    constructor(config: AuthModuleConfiguration);
+    /**
+     * Login the user with extended options
+     * Supports cached sessions, silent login, redirect flow, and direct login
+     * @param options - Extended login options
+     * @returns Promise that resolves with the user or null
+     */
+    login(options?: LoginOptions): Promise<User | null>;
+    /**
+     * Login with redirect
+     * Redirects the page for authentication
+     * @param directLoginOptions - Optional direct login options
+     * @returns Promise that resolves when redirect is initiated
+     */
+    loginWithRedirect(directLoginOptions?: DirectLoginOptions): Promise<void>;
+    /**
+     * Login callback handler
+     * Call this in your redirect URI page
+     * @returns Promise that resolves with the authenticated user
+     */
+    loginCallback(): Promise<User>;
+    /**
+     * Logout the current user
+     * @returns Promise that resolves when logout is complete
+     */
+    logout(): Promise<void>;
+    /**
+     * Get the current authenticated user
+     * @returns Promise that resolves with the user or null if not authenticated
+     */
+    getUser(): Promise<User | null>;
+    /**
+     * Get the ID token for the current user
+     * @returns Promise that resolves with the ID token or undefined
+     */
+    getIdToken(): Promise<string | undefined>;
+    /**
+     * Get the access token for the current user
+     * @returns Promise that resolves with the access token or undefined
+     */
+    getAccessToken(): Promise<string | undefined>;
+    /**
+     * Check if user is logged in
+     * @returns Promise that resolves with true if user is logged in
+     */
+    isLoggedIn(): Promise<boolean>;
+    /**
+     * Force a silent user refresh (for silent login)
+     * @returns Promise that resolves with the user or null if refresh fails
+     */
+    forceUserRefresh(): Promise<User | null>;
+    /**
+     * Get the PKCE authorization URL for login flow
+     * @param directLoginOptions - Optional direct login options
+     * @param imPassportTraceId - Optional trace ID for tracking
+     * @returns Promise that resolves with the authorization URL
+     */
+    loginWithPKCEFlow(directLoginOptions?: DirectLoginOptions, imPassportTraceId?: string): Promise<string>;
+    /**
+     * Handle the PKCE login callback
+     * @param authorizationCode - The authorization code from the OAuth provider
+     * @param state - The state parameter for CSRF protection
+     * @returns Promise that resolves with the authenticated user
+     */
+    loginWithPKCEFlowCallback(authorizationCode: string, state: string): Promise<User>;
+    /**
+     * Store tokens from device flow and retrieve user
+     * @param tokenResponse - The token response from device flow
+     * @returns Promise that resolves with the authenticated user
+     */
+    storeTokens(tokenResponse: DeviceTokenResponse): Promise<User>;
+    /**
+     * Get the logout URL
+     * @returns Promise that resolves with the logout URL or undefined if not available
+     */
+    getLogoutUrl(): Promise<string | undefined>;
+    /**
+     * Handle the silent logout callback
+     * @param url - The URL containing logout information
+     * @returns Promise that resolves when callback is handled
+     */
+    logoutSilentCallback(url: string): Promise<void>;
+    /**
+     * Get internal AuthManager instance
+     * @internal
+     * @returns AuthManager instance for advanced use cases
+     */
+    getAuthManager(): AuthManager;
+    /**
+     * Get auth configuration
+     * @internal
+     * @returns IAuthConfiguration instance
+     */
+    getConfig(): IAuthConfiguration;
+}

package/dist/types/authManager.d.ts

@@ -1,6 +1,6 @@
-import { DirectLoginOptions, User, DeviceTokenResponse, UserZkEvm, UserImx } from './types';
+import { DirectLoginOptions, User, DeviceTokenResponse, UserZkEvm } from './types';
 import { IAuthConfiguration } from './config';
-import { EmbeddedLoginPrompt } from './confirmation';
+import EmbeddedLoginPrompt from './login/embeddedLoginPrompt';
 export default class AuthManager {
     private userManager;
     private deviceCredentialsManager;
@@ -15,16 +15,16 @@ export default class AuthManager {
     private static mapOidcUserToDomainModel;
     private static mapDeviceTokenResponseToOidcUser;
     private buildExtraQueryParams;
-    loginWithRedirect(anonymousId?: string, directLoginOptions?: DirectLoginOptions): Promise<void>;
+    getClientId(): Promise<string>;
+    loginWithRedirect(directLoginOptions?: DirectLoginOptions): Promise<void>;
     /**
      * login
-     * @param anonymousId Caller can pass an anonymousId if they want to associate their user's identity with immutable's internal instrumentation.
      * @param directLoginOptions If provided, contains login method and marketing consent options
      * @param directLoginOptions.directLoginMethod The login method to use (e.g., 'google', 'apple', 'email')
      * @param directLoginOptions.marketingConsentStatus Marketing consent status ('opted_in' or 'unsubscribed')
      * @param directLoginOptions.email Required when directLoginMethod is 'email'
      */
-    login(anonymousId?: string, directLoginOptions?: DirectLoginOptions): Promise<User>;
+    login(directLoginOptions?: DirectLoginOptions): Promise<User>;
     getUserOrLogin(): Promise<User>;
     private static shouldUseSigninPopupCallback;
     loginCallback(): Promise<undefined | User>;
@@ -58,5 +58,4 @@ export default class AuthManager {
      */
     getUser<T extends User>(typeAssertion?: (user: User) => user is T): Promise<T | null>;
     getUserZkEvm(): Promise<UserZkEvm>;
-    getUserImx(): Promise<UserImx>;
 }

package/dist/types/index.d.ts

@@ -1,8 +1,7 @@
+export { Auth } from './Auth';
 export { default as AuthManager } from './authManager';
 export { AuthConfiguration, type IAuthConfiguration } from './config';
-export type { User, UserProfile, UserImx, UserZkEvm, DirectLoginMethod, DirectLoginOptions, DeviceTokenResponse, OidcConfiguration, AuthModuleConfiguration, PopupOverlayOptions, PassportMetadata, IdTokenPayload, PKCEData, } from './types';
-export { isUserZkEvm, isUserImx, RollupType, MarketingConsentStatus, } from './types';
+export type { User, UserProfile, UserZkEvm, DirectLoginMethod, DirectLoginOptions, LoginOptions, DeviceTokenResponse, OidcConfiguration, AuthModuleConfiguration, PopupOverlayOptions, PassportMetadata, IdTokenPayload, PKCEData, AuthEventMap, } from './types';
+export { isUserZkEvm, RollupType, MarketingConsentStatus, AuthEvents, } from './types';
+export { default as TypedEventEmitter } from './utils/typedEventEmitter';
 export { PassportError, PassportErrorType, withPassportError } from './errors';
-export { default as ConfirmationScreen } from './confirmation/confirmation';
-export { default as EmbeddedLoginPrompt } from './confirmation/embeddedLoginPrompt';
-export { default as ConfirmationOverlay } from './overlay/confirmationOverlay';

package/dist/types/{confirmation → login}/embeddedLoginPrompt.d.ts

@@ -6,5 +6,5 @@ export default class EmbeddedLoginPrompt {
     private getHref;
     private static appendIFrameStylesIfNeeded;
     private getEmbeddedLoginIFrame;
-    displayEmbeddedLoginPrompt(anonymousId?: string): Promise<EmbeddedLoginPromptResult>;
+    displayEmbeddedLoginPrompt(): Promise<EmbeddedLoginPromptResult>;
 }

package/dist/types/overlay/{confirmationOverlay.d.ts → loginPopupOverlay.d.ts}

@@ -1,5 +1,5 @@
 import { PopupOverlayOptions } from '../types';
-export default class ConfirmationOverlay {
+export default class LoginPopupOverlay {
     private disableGenericPopupOverlay;
     private disableBlockedPopupOverlay;
     private overlay;

package/dist/types/types.d.ts

@@ -10,7 +10,6 @@ export type UserProfile = {
     sub: string;
 };
 export declare enum RollupType {
-    IMX = "imx",
     ZKEVM = "zkEvm"
 }
 export type User = {
@@ -19,22 +18,14 @@ export type User = {
     refreshToken?: string;
     profile: UserProfile;
     expired?: boolean;
-    [RollupType.IMX]?: {
-        ethAddress: string;
-        starkAddress: string;
-        userAdminAddress: string;
-    };
     [RollupType.ZKEVM]?: {
         ethAddress: string;
         userAdminAddress: string;
     };
 };
 export type PassportMetadata = {
-    imx_eth_address: string;
-    imx_stark_address: string;
-    imx_user_admin_address: string;
-    zkevm_eth_address: string;
-    zkevm_user_admin_address: string;
+    zkevm_eth_address?: string;
+    zkevm_user_admin_address?: string;
 };
 export interface OidcConfiguration {
     clientId: string;
@@ -72,10 +63,8 @@ export interface AuthModuleConfiguration extends OidcConfiguration {
 type WithRequired<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
 };
-export type UserImx = WithRequired<User, RollupType.IMX>;
 export type UserZkEvm = WithRequired<User, RollupType.ZKEVM>;
 export declare const isUserZkEvm: (user: User) => user is UserZkEvm;
-export declare const isUserImx: (user: User) => user is UserImx;
 export type DeviceTokenResponse = {
     access_token: string;
     refresh_token?: string;
@@ -105,8 +94,39 @@ export declare enum MarketingConsentStatus {
     Unsubscribed = "unsubscribed"
 }
 export type DirectLoginOptions = {
-    directLoginMethod: DirectLoginMethod;
-    marketingConsentStatus?: MarketingConsentStatus;
-    email?: string;
+    marketingConsentStatus: MarketingConsentStatus;
+} & ({
+    directLoginMethod: 'email';
+    email: string;
+} | {
+    directLoginMethod: Exclude<DirectLoginMethod, 'email'>;
+    email?: never;
+});
+/**
+ * Extended login options with caching and silent login support
+ */
+export type LoginOptions = {
+    /** If true, attempts to use cached session without user interaction */
+    useCachedSession?: boolean;
+    /** If true, attempts silent authentication (force token refresh) */
+    useSilentLogin?: boolean;
+    /** If true, uses redirect flow instead of popup flow */
+    useRedirectFlow?: boolean;
+    /** Direct login options (social provider, email, etc.) */
+    directLoginOptions?: DirectLoginOptions;
 };
+/**
+ * Authentication events emitted by the Auth class
+ */
+export declare enum AuthEvents {
+    LOGGED_OUT = "loggedOut",
+    LOGGED_IN = "loggedIn"
+}
+/**
+ * Event map for typed event emitter
+ */
+export interface AuthEventMap extends Record<string, any> {
+    [AuthEvents.LOGGED_OUT]: [];
+    [AuthEvents.LOGGED_IN]: [User];
+}
 export {};

package/dist/types/utils/metrics.d.ts

@@ -0,0 +1,2 @@
+import { Flow } from '@imtbl/metrics';
+export declare const withMetricsAsync: <T>(fn: (flow: Flow) => Promise<T>, flowName: string, trackStartEvent?: boolean, trackEndEvent?: boolean) => Promise<T>;

package/dist/types/utils/typedEventEmitter.d.ts

@@ -0,0 +1,6 @@
+export default class TypedEventEmitter<TEvents extends Record<string, any>> {
+    private emitter;
+    emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArg: TEvents[TEventName]): void;
+    on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
+    removeListener<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth",
-  "version": "2.10.7-alpha.3",
+  "version": "2.10.7-alpha.5",
   "description": "Authentication SDK for Immutable",
   "author": "Immutable",
   "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
@@ -25,8 +25,8 @@
     }
   },
   "dependencies": {
-    "@imtbl/config": "2.10.7-alpha.3",
-    "@imtbl/metrics": "2.10.7-alpha.3",
+    "@imtbl/config": "2.10.7-alpha.5",
+    "@imtbl/metrics": "2.10.7-alpha.5",
     "axios": "^1.6.5",
     "jwt-decode": "^3.1.2",
     "localforage": "^1.10.0",
@@ -34,7 +34,7 @@
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@imtbl/toolkit": "2.10.7-alpha.3",
+    "@imtbl/toolkit": "2.10.7-alpha.5",
     "@types/node": "^18.14.2",
     "tsup": "^8.3.0",
     "typescript": "^5.6.2"

package/src/Auth.ts

@@ -0,0 +1,264 @@
+import AuthManager from './authManager';
+import { AuthConfiguration, IAuthConfiguration } from './config';
+import {
+  AuthModuleConfiguration, User, DirectLoginOptions, DeviceTokenResponse, LoginOptions, AuthEventMap, AuthEvents,
+} from './types';
+import EmbeddedLoginPrompt from './login/embeddedLoginPrompt';
+import TypedEventEmitter from './utils/typedEventEmitter';
+import { withMetricsAsync } from './utils/metrics';
+import { identify, track, trackError } from '@imtbl/metrics';
+import logger from './utils/logger';
+
+/**
+ * Public-facing Auth class for authentication
+ * Wraps AuthManager with a simpler API
+ */
+export class Auth {
+  private authManager: AuthManager;
+
+  private config: IAuthConfiguration;
+
+  /**
+   * Event emitter for authentication events (LOGGED_IN, LOGGED_OUT)
+   * Exposed for wallet and passport packages to subscribe to auth state changes
+   */
+  public readonly eventEmitter: TypedEventEmitter<AuthEventMap>;
+
+  /**
+   * Create a new Auth instance
+   *
+   * @param config - Auth configuration
+   *
+   * @example
+   * ```typescript
+   * import { Auth } from '@imtbl/auth';
+   *
+   * const auth = new Auth({
+   *   authenticationDomain: 'https://auth.immutable.com',
+   *   passportDomain: 'https://passport.immutable.com',
+   *   clientId: 'your-client-id',
+   *   redirectUri: 'https://your-app.com/callback',
+   *   scope: 'openid profile email transact',
+   * });
+   * ```
+   */
+  constructor(config: AuthModuleConfiguration) {
+    this.config = new AuthConfiguration(config);
+    const embeddedLoginPrompt = new EmbeddedLoginPrompt(this.config);
+    this.authManager = new AuthManager(this.config, embeddedLoginPrompt);
+    this.eventEmitter = new TypedEventEmitter<AuthEventMap>();
+    track('passport', 'initialise');
+  }
+
+  /**
+   * Login the user with extended options
+   * Supports cached sessions, silent login, redirect flow, and direct login
+   * @param options - Extended login options
+   * @returns Promise that resolves with the user or null
+   */
+  async login(options?: LoginOptions): Promise<User | null> {
+    return withMetricsAsync(async () => {
+      const { useCachedSession = false, useSilentLogin } = options || {};
+      let user: User | null = null;
+
+      // Try to get cached user
+      try {
+        user = await this.authManager.getUser();
+      } catch (error: any) {
+        if (error instanceof Error && !error.message.includes('Unknown or invalid refresh token')) {
+          trackError('passport', 'login', error);
+        }
+        if (useCachedSession) {
+          throw error;
+        }
+        logger.warn('Failed to retrieve a cached user session', error);
+      }
+
+      // If no cached user, try silent login or regular login
+      if (!user && useSilentLogin) {
+        user = await this.authManager.forceUserRefresh();
+      } else if (!user && !useCachedSession) {
+        if (options?.useRedirectFlow) {
+          await this.authManager.loginWithRedirect(options?.directLoginOptions);
+          return null; // Redirect doesn't return user immediately
+        }
+        user = await this.authManager.login(options?.directLoginOptions);
+      }
+
+      // Emit LOGGED_IN event and identify user if logged in
+      if (user) {
+        this.eventEmitter.emit(AuthEvents.LOGGED_IN, user);
+        identify({ passportId: user.profile.sub });
+      }
+
+      return user;
+    }, 'login');
+  }
+
+  /**
+   * Login with redirect
+   * Redirects the page for authentication
+   * @param directLoginOptions - Optional direct login options
+   * @returns Promise that resolves when redirect is initiated
+   */
+  async loginWithRedirect(directLoginOptions?: DirectLoginOptions): Promise<void> {
+    await this.authManager.loginWithRedirect(directLoginOptions);
+  }
+
+  /**
+   * Login callback handler
+   * Call this in your redirect URI page
+   * @returns Promise that resolves with the authenticated user
+   */
+  async loginCallback(): Promise<User> {
+    return withMetricsAsync(async () => {
+      const user = await this.authManager.loginCallback();
+      if (!user) {
+        throw new Error('Login callback failed - no user returned');
+      }
+      this.eventEmitter.emit(AuthEvents.LOGGED_IN, user);
+      identify({ passportId: user.profile.sub });
+      return user;
+    }, 'loginCallback');
+  }
+
+  /**
+   * Logout the current user
+   * @returns Promise that resolves when logout is complete
+   */
+  async logout(): Promise<void> {
+    await withMetricsAsync(async () => {
+      await this.authManager.logout();
+      this.eventEmitter.emit(AuthEvents.LOGGED_OUT);
+    }, 'logout');
+  }
+
+  /**
+   * Get the current authenticated user
+   * @returns Promise that resolves with the user or null if not authenticated
+   */
+  async getUser(): Promise<User | null> {
+    return withMetricsAsync(async () => this.authManager.getUser(), 'getUserInfo', false);
+  }
+
+  /**
+   * Get the ID token for the current user
+   * @returns Promise that resolves with the ID token or undefined
+   */
+  async getIdToken(): Promise<string | undefined> {
+    return withMetricsAsync(async () => {
+      const user = await this.authManager.getUser();
+      return user?.idToken;
+    }, 'getIdToken', false);
+  }
+
+  /**
+   * Get the access token for the current user
+   * @returns Promise that resolves with the access token or undefined
+   */
+  async getAccessToken(): Promise<string | undefined> {
+    return withMetricsAsync(async () => {
+      const user = await this.authManager.getUser();
+      return user?.accessToken;
+    }, 'getAccessToken', false, false);
+  }
+
+  /**
+   * Check if user is logged in
+   * @returns Promise that resolves with true if user is logged in
+   */
+  async isLoggedIn(): Promise<boolean> {
+    const user = await this.getUser();
+    return user !== null;
+  }
+
+  /**
+   * Force a silent user refresh (for silent login)
+   * @returns Promise that resolves with the user or null if refresh fails
+   */
+  async forceUserRefresh(): Promise<User | null> {
+    return this.authManager.forceUserRefresh();
+  }
+
+  /**
+   * Get the PKCE authorization URL for login flow
+   * @param directLoginOptions - Optional direct login options
+   * @param imPassportTraceId - Optional trace ID for tracking
+   * @returns Promise that resolves with the authorization URL
+   */
+  async loginWithPKCEFlow(directLoginOptions?: DirectLoginOptions, imPassportTraceId?: string): Promise<string> {
+    return withMetricsAsync(
+      async () => this.authManager.getPKCEAuthorizationUrl(directLoginOptions, imPassportTraceId),
+      'loginWithPKCEFlow',
+    );
+  }
+
+  /**
+   * Handle the PKCE login callback
+   * @param authorizationCode - The authorization code from the OAuth provider
+   * @param state - The state parameter for CSRF protection
+   * @returns Promise that resolves with the authenticated user
+   */
+  async loginWithPKCEFlowCallback(authorizationCode: string, state: string): Promise<User> {
+    return withMetricsAsync(async () => {
+      const user = await this.authManager.loginWithPKCEFlowCallback(authorizationCode, state);
+      this.eventEmitter.emit(AuthEvents.LOGGED_IN, user);
+      identify({ passportId: user.profile.sub });
+      return user;
+    }, 'loginWithPKCEFlowCallback');
+  }
+
+  /**
+   * Store tokens from device flow and retrieve user
+   * @param tokenResponse - The token response from device flow
+   * @returns Promise that resolves with the authenticated user
+   */
+  async storeTokens(tokenResponse: DeviceTokenResponse): Promise<User> {
+    return withMetricsAsync(async () => {
+      const user = await this.authManager.storeTokens(tokenResponse);
+      this.eventEmitter.emit(AuthEvents.LOGGED_IN, user);
+      identify({ passportId: user.profile.sub });
+      return user;
+    }, 'storeTokens');
+  }
+
+  /**
+   * Get the logout URL
+   * @returns Promise that resolves with the logout URL or undefined if not available
+   */
+  async getLogoutUrl(): Promise<string | undefined> {
+    return withMetricsAsync(async () => {
+      await this.authManager.removeUser();
+      this.eventEmitter.emit(AuthEvents.LOGGED_OUT);
+      const url = await this.authManager.getLogoutUrl();
+      return url || undefined;
+    }, 'getLogoutUrl');
+  }
+
+  /**
+   * Handle the silent logout callback
+   * @param url - The URL containing logout information
+   * @returns Promise that resolves when callback is handled
+   */
+  async logoutSilentCallback(url: string): Promise<void> {
+    return withMetricsAsync(() => this.authManager.logoutSilentCallback(url), 'logoutSilentCallback');
+  }
+
+  /**
+   * Get internal AuthManager instance
+   * @internal
+   * @returns AuthManager instance for advanced use cases
+   */
+  getAuthManager(): AuthManager {
+    return this.authManager;
+  }
+
+  /**
+   * Get auth configuration
+   * @internal
+   * @returns IAuthConfiguration instance
+   */
+  getConfig(): IAuthConfiguration {
+    return this.config;
+  }
+}