@account-kit/signer 4.21.0 → 4.23.0

package/src/base.ts

@@ -21,7 +21,17 @@ import type { Mutate, StoreApi } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
 import { createStore } from "zustand/vanilla";
 import type { BaseSignerClient } from "./client/base";
-import type { OauthConfig, OauthParams, User } from "./client/types";
+import type {
+  EmailType,
+  MfaFactor,
+  OauthConfig,
+  OauthParams,
+  User,
+  VerifyMfaParams,
+  EnableMfaParams,
+  EnableMfaResult,
+  RemoveMfaParams,
+} from "./client/types";
 import { NotAuthenticatedError } from "./errors.js";
 import { SignerLogger } from "./metrics.js";
 import {
@@ -36,6 +46,7 @@ import {
   type AlchemySignerEvent,
   type AlchemySignerEvents,
   type ErrorInfo,
+  type ValidateMultiFactorsArgs,
 } from "./types.js";
 import { assertNever } from "./utils/typeAssertions.js";
 
@@ -51,6 +62,11 @@ type AlchemySignerStore = {
   error: ErrorInfo | null;
   otpId?: string;
   isNewUser?: boolean;
+  mfaStatus: {
+    mfaRequired: boolean;
+    mfaFactorId?: string;
+    encryptedPayload?: string;
+  };
 };
 
 type UnpackedSignature = {
@@ -108,6 +124,10 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
             user: null,
             status: AlchemySignerStatus.INITIALIZING,
             error: initialError ?? null,
+            mfaStatus: {
+              mfaRequired: false,
+              mfaFactorId: undefined,
+            },
           } satisfies AlchemySignerStore)
       )
     );
@@ -181,6 +201,13 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
           },
           { fireImmediately: true }
         );
+      case "mfaStatusChanged":
+        return this.store.subscribe(
+          ({ mfaStatus }) => mfaStatus,
+          (mfaStatus) =>
+            (listener as AlchemySignerEvents["mfaStatusChanged"])(mfaStatus),
+          { fireImmediately: true }
+        );
       default:
         assertNever(event, `Unknown event type ${event}`);
     }
@@ -590,6 +617,39 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     }
   );
 
+  /**
+   * Gets the current MFA status
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const mfaStatus = signer.getMfaStatus();
+   * if (mfaStatus === AlchemyMfaStatus.REQUIRED) {
+   *   // Handle MFA requirement
+   * }
+   * ```
+   *
+   * @returns {{ mfaRequired: boolean; mfaFactorId?: string }} The current MFA status
+   */
+  getMfaStatus = (): {
+    mfaRequired: boolean;
+    mfaFactorId?: string;
+  } => {
+    return this.store.getState().mfaStatus;
+  };
+
   private unpackSignRawMessageBytes = (
     hex: `0x${string}`
   ): UnpackedSignature => {
@@ -784,70 +844,36 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   private authenticateWithEmail = async (
     params: Extract<AuthParams, { type: "email" }>
   ): Promise<User> => {
-    if ("email" in params) {
-      const existingUser = await this.getUser(params.email);
-      const expirationSeconds = this.getExpirationSeconds();
-
-      const { orgId, otpId } = existingUser
-        ? await this.inner.initEmailAuth({
-            email: params.email,
-            emailMode: params.emailMode,
-            expirationSeconds,
-            redirectParams: params.redirectParams,
-          })
-        : await this.inner.createAccount({
-            type: "email",
-            email: params.email,
-            emailMode: params.emailMode,
-            expirationSeconds,
-            redirectParams: params.redirectParams,
-          });
+    if ("bundle" in params) {
+      return this.completeEmailAuth(params);
+    }
 
-      this.sessionManager.setTemporarySession({
-        orgId,
-        isNewUser: !existingUser,
-      });
-      this.store.setState({
-        status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
-        otpId,
-        error: null,
-      });
+    const { orgId, otpId, isNewUser } = await this.initOrCreateEmailUser(
+      params.email,
+      params.emailMode,
+      params.multiFactors,
+      params.redirectParams
+    );
 
-      // We wait for the session manager to emit a connected event if
-      // cross tab sessions are permitted
-      return new Promise<User>((resolve) => {
-        const removeListener = this.sessionManager.on(
-          "connected",
-          (session) => {
-            resolve(session.user);
-            removeListener();
-          }
-        );
-      });
-    } else {
-      const temporarySession = params.orgId
-        ? { orgId: params.orgId }
-        : this.sessionManager.getTemporarySession();
+    this.sessionManager.setTemporarySession({
+      orgId,
+      isNewUser,
+    });
 
-      if (!temporarySession) {
-        this.store.setState({
-          status: AlchemySignerStatus.DISCONNECTED,
-        });
-        throw new Error("Could not find email auth init session!");
-      }
+    this.store.setState({
+      status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+      otpId,
+      error: null,
+    });
 
-      const user = await this.inner.completeAuthWithBundle({
-        bundle: params.bundle,
-        orgId: temporarySession.orgId,
-        connectedEventName: "connectedEmail",
-        authenticatingType: "email",
+    // We wait for the session manager to emit a connected event if
+    // cross tab sessions are permitted
+    return new Promise<User>((resolve) => {
+      const removeListener = this.sessionManager.on("connected", (session) => {
+        resolve(session.user);
+        removeListener();
       });
-
-      // fire new user event
-      this.emitNewUserEvent(params.isNewUser);
-
-      return user;
-    }
+    });
   };
 
   private authenticateWithPasskey = async (
@@ -916,14 +942,31 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     if (!otpId) {
       throw new Error("otpId not found in session");
     }
-    const { bundle } = await this.inner.submitOtpCode({
+
+    const response = await this.inner.submitOtpCode({
       orgId,
       otpId,
       otpCode: args.otpCode,
       expirationSeconds: this.getExpirationSeconds(),
+      multiFactors: args.multiFactors,
     });
+
+    if (response.mfaRequired) {
+      this.handleMfaRequired(response.encryptedPayload, response.multiFactors);
+
+      return new Promise<User>((resolve) => {
+        const removeListener = this.sessionManager.on(
+          "connected",
+          (session) => {
+            resolve(session.user);
+            removeListener();
+          }
+        );
+      });
+    }
+
     const user = await this.inner.completeAuthWithBundle({
-      bundle,
+      bundle: response.bundle,
       orgId,
       connectedEventName: "connectedOtp",
       authenticatingType: "otp",
@@ -959,6 +1002,31 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return user;
   };
 
+  private handleMfaRequired(
+    encryptedPayload: string,
+    multiFactors: MfaFactor[]
+  ) {
+    // Store complete MFA context in the temporary session
+    const tempSession = this.sessionManager.getTemporarySession();
+    if (tempSession) {
+      this.sessionManager.setTemporarySession({
+        ...tempSession,
+        encryptedPayload,
+        mfaFactorId: multiFactors?.[0]?.multiFactorId,
+      });
+    }
+
+    // Keep minimal state in the store for UI updates
+    this.store.setState({
+      status: AlchemySignerStatus.AWAITING_MFA_AUTH,
+      error: null,
+      mfaStatus: {
+        mfaRequired: true,
+        mfaFactorId: multiFactors?.[0]?.multiFactorId,
+      },
+    });
+  }
+
   private getExpirationSeconds = () =>
     Math.floor(this.sessionManager.expirationTimeMs / 1000);
 
@@ -1027,6 +1095,297 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     if (isNewUser) this.store.setState({ isNewUser });
   };
 
+  private async initOrCreateEmailUser(
+    email: string,
+    emailMode?: EmailType,
+    multiFactors?: VerifyMfaParams[],
+    redirectParams?: URLSearchParams
+  ): Promise<{
+    orgId: string;
+    otpId?: string;
+    isNewUser: boolean;
+  }> {
+    const existingUser = await this.getUser(email);
+    const expirationSeconds = this.getExpirationSeconds();
+
+    if (existingUser) {
+      const { orgId, otpId } = await this.inner.initEmailAuth({
+        email: email,
+        emailMode: emailMode,
+        expirationSeconds,
+        redirectParams: redirectParams,
+        multiFactors,
+      });
+      return {
+        orgId,
+        otpId,
+        isNewUser: false,
+      };
+    }
+
+    const { orgId, otpId } = await this.inner.createAccount({
+      type: "email",
+      email,
+      emailMode,
+      expirationSeconds,
+      redirectParams,
+    });
+    return {
+      orgId,
+      otpId,
+      isNewUser: true,
+    };
+  }
+
+  private async completeEmailAuth(
+    params: Extract<AuthParams, { type: "email"; bundle: string }>
+  ): Promise<User> {
+    const temporarySession = params.orgId
+      ? { orgId: params.orgId }
+      : this.sessionManager.getTemporarySession();
+
+    if (!temporarySession) {
+      this.store.setState({ status: AlchemySignerStatus.DISCONNECTED });
+      throw new Error("Could not find email auth init session!");
+    }
+
+    const user = await this.inner.completeAuthWithBundle({
+      bundle: params.bundle,
+      orgId: temporarySession.orgId,
+      connectedEventName: "connectedEmail",
+      authenticatingType: "email",
+    });
+
+    // fire new user event
+    this.emitNewUserEvent(params.isNewUser);
+
+    return user;
+  }
+
+  /**
+   * Retrieves the list of MFA factors configured for the current user.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const { multiFactors } = await signer.getMfaFactors();
+   * ```
+   *
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   * @returns {Promise<{ multiFactors: Array<MfaFactor> }>} A promise that resolves to an array of configured MFA factors
+   */
+  getMfaFactors: () => Promise<{ multiFactors: MfaFactor[] }> =
+    SignerLogger.profiled("BaseAlchemySigner.getMfaFactors", async () => {
+      return this.inner.getMfaFactors();
+    });
+
+  /**
+   * Initiates the setup of a new MFA factor for the current user.
+   * The factor will need to be verified using verifyMfa before it becomes active.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.addMfa({ multiFactorType: "totp" });
+   * // Result contains multiFactorTotpUrl to display as QR code
+   * ```
+   *
+   * @param {EnableMfaParams} params The parameters required to enable a new MFA factor
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   * @returns {Promise<EnableMfaResult>} A promise that resolves to the factor setup information
+   */
+  addMfa: (params: EnableMfaParams) => Promise<EnableMfaResult> =
+    SignerLogger.profiled("BaseAlchemySigner.addMfa", async (params) => {
+      return this.inner.addMfa(params);
+    });
+
+  /**
+   * Verifies a newly created MFA factor to complete the setup process.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.verifyMfa({
+   *   multiFactorId: "factor-id",
+   *   multiFactorCode: "123456" // 6-digit code from authenticator app
+   * });
+   * ```
+   *
+   * @param {VerifyMfaParams} params The parameters required to verify the MFA factor
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   * @returns {Promise<{ multiFactors: MfaFactor[] }>} A promise that resolves to the updated list of MFA factors
+   */
+  verifyMfa: (
+    params: VerifyMfaParams
+  ) => Promise<{ multiFactors: MfaFactor[] }> = SignerLogger.profiled(
+    "BaseAlchemySigner.verifyMfa",
+    async (params) => {
+      return this.inner.verifyMfa(params);
+    }
+  );
+
+  /**
+   * Removes existing MFA factors by their IDs.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.removeMfa({
+   *   multiFactorIds: ["factor-id-1", "factor-id-2"]
+   * });
+   * ```
+   *
+   * @param {RemoveMfaParams} params The parameters specifying which factors to disable
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   * @returns {Promise<{ multiFactors: MfaFactor[] }>} A promise that resolves to the updated list of MFA factors
+   */
+  removeMfa: (
+    params: RemoveMfaParams
+  ) => Promise<{ multiFactors: MfaFactor[] }> = SignerLogger.profiled(
+    "BaseAlchemySigner.removeMfa",
+    async (params) => {
+      return this.inner.removeMfa(params);
+    }
+  );
+
+  /**
+   * Validates MFA factors that were required during authentication.
+   * This function should be called after MFA is required and the user has provided their MFA code.
+   * It completes the authentication process by validating the MFA factors and completing the auth bundle.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * // After MFA is required and user provides code
+   * const user = await signer.validateMultiFactors({
+   *   multiFactorCode: "123456", // 6-digit code from authenticator app
+   *   multiFactorId: "factor-id"
+   * });
+   * ```
+   *
+   * @param {ValidateMultiFactorsArgs} params - Parameters for validating MFA factors
+   * @throws {Error} If there is no pending MFA context or if orgId is not found
+   * @returns {Promise<User>} A promise that resolves to the authenticated user
+   */
+  public async validateMultiFactors(
+    params: ValidateMultiFactorsArgs
+  ): Promise<User> {
+    // Get MFA context from temporary session
+    const tempSession = this.sessionManager.getTemporarySession();
+    if (
+      !tempSession?.orgId ||
+      !tempSession.encryptedPayload ||
+      !tempSession.mfaFactorId
+    ) {
+      throw new Error(
+        "No pending MFA context found. Call submitOtpCode() first."
+      );
+    }
+
+    if (
+      params.multiFactorId &&
+      tempSession.mfaFactorId !== params.multiFactorId
+    ) {
+      throw new Error("MFA factor ID mismatch");
+    }
+
+    // Call the low-level client
+    const { bundle } = await this.inner.validateMultiFactors({
+      encryptedPayload: tempSession.encryptedPayload,
+      multiFactors: [
+        {
+          multiFactorId: tempSession.mfaFactorId,
+          multiFactorCode: params.multiFactorCode,
+        },
+      ],
+    });
+
+    // Complete the authentication
+    const user = await this.inner.completeAuthWithBundle({
+      bundle,
+      orgId: tempSession.orgId,
+      connectedEventName: "connectedOtp",
+      authenticatingType: "otp",
+    });
+
+    // Remove MFA data from temporary session
+    this.sessionManager.setTemporarySession({
+      ...tempSession,
+      encryptedPayload: undefined,
+      mfaFactorId: undefined,
+    });
+
+    // Update UI state
+    this.store.setState({
+      mfaStatus: {
+        mfaRequired: false,
+        mfaFactorId: undefined,
+      },
+    });
+
+    return user;
+  }
+
   protected initConfig = async (): Promise<SignerConfig> => {
     this.config = this.fetchConfig();
     return this.config;

package/src/client/base.ts

@@ -14,10 +14,14 @@ import type {
   AlchemySignerClientEvents,
   AuthenticatingEventMetadata,
   CreateAccountParams,
+  RemoveMfaParams,
   EmailAuthParams,
+  EnableMfaParams,
+  EnableMfaResult,
   experimental_CreateApiKeyParams,
   GetOauthProviderUrlArgs,
   GetWebAuthnAttestationResult,
+  MfaFactor,
   OauthConfig,
   OauthParams,
   OauthState,
@@ -27,6 +31,9 @@ import type {
   SignerRoutes,
   SignupResponse,
   User,
+  VerifyMfaParams,
+  SubmitOtpCodeResponse,
+  ValidateMultiFactorsParams,
 } from "./types.js";
 import { VERSION } from "../version.js";
 
@@ -133,7 +140,54 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract initEmailAuth(
     params: Omit<EmailAuthParams, "targetPublicKey">
-  ): Promise<{ orgId: string; otpId?: string }>;
+  ): Promise<{ orgId: string; otpId?: string; multiFactors?: MfaFactor[] }>;
+
+  /**
+   * Retrieves the list of MFA factors configured for the current user.
+   *
+   * @returns {Promise<{ multiFactors: Array<MfaFactor> }>} A promise that resolves to an array of configured MFA factors
+   */
+  public abstract getMfaFactors(): Promise<{
+    multiFactors: MfaFactor[];
+  }>;
+
+  /**
+   * Initiates the setup of a new MFA factor for the current user. Mfa will need to be verified before it is active.
+   *
+   * @param {EnableMfaParams} params The parameters required to enable a new MFA factor
+   * @returns {Promise<EnableMfaResult>} A promise that resolves to the factor setup information
+   */
+  public abstract addMfa(params: EnableMfaParams): Promise<EnableMfaResult>;
+
+  /**
+   * Verifies a newly created MFA factor to complete the setup process.
+   *
+   * @param {VerifyMfaParams} params The parameters required to verify the MFA factor
+   * @returns {Promise<{ multiFactors: MfaFactor[] }>} A promise that resolves to the updated list of MFA factors
+   */
+  public abstract verifyMfa(params: VerifyMfaParams): Promise<{
+    multiFactors: MfaFactor[];
+  }>;
+
+  /**
+   * Removes existing MFA factors by ID or factor type.
+   *
+   * @param {RemoveMfaParams} params The parameters specifying which factors to disable
+   * @returns {Promise<{ multiFactors: MfaFactor[] }>} A promise that resolves to the updated list of MFA factors
+   */
+  public abstract removeMfa(params: RemoveMfaParams): Promise<{
+    multiFactors: MfaFactor[];
+  }>;
+
+  /**
+   * Validates multiple MFA factors using the provided encrypted payload and MFA codes.
+   *
+   * @param {ValidateMultiFactorsParams} params The validation parameters
+   * @returns {Promise<{ bundle: string }>} A promise that resolves to an object containing the credential bundle
+   */
+  public abstract validateMultiFactors(
+    params: ValidateMultiFactorsParams
+  ): Promise<{ bundle: string }>;
 
   public abstract completeAuthWithBundle(params: {
     bundle: string;
@@ -153,7 +207,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract submitOtpCode(
     args: Omit<OtpParams, "targetPublicKey">
-  ): Promise<{ bundle: string }>;
+  ): Promise<SubmitOtpCodeResponse>;
 
   public abstract disconnect(): Promise<void>;