@account-kit/signer 4.16.0 → 4.16.1-alpha.3

package/src/base.ts

@@ -21,7 +21,14 @@ 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,
+} from "./client/types";
 import { NotAuthenticatedError } from "./errors.js";
 import { SignerLogger } from "./metrics.js";
 import {
@@ -51,6 +58,10 @@ type AlchemySignerStore = {
   error: ErrorInfo | null;
   otpId?: string;
   isNewUser?: boolean;
+  mfaStatus: {
+    mfaRequired: boolean;
+    mfaFactorId?: string;
+  };
 };
 
 type UnpackedSignature = {
@@ -99,6 +110,10 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
             user: null,
             status: AlchemySignerStatus.INITIALIZING,
             error: initialError ?? null,
+            mfaStatus: {
+              mfaRequired: false,
+              mfaFactorId: undefined,
+            },
           } satisfies AlchemySignerStore)
       )
     );
@@ -171,6 +186,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}`);
     }
@@ -580,6 +602,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 => {
@@ -769,70 +824,48 @@ 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,
-      });
+    if (!("email" in params)) {
+      throw new Error("Email is required");
+    }
 
-      // 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();
+    const { orgId, otpId, multiFactors, isNewUser } =
+      await this.initOrCreateEmailUser(
+        params.email,
+        params.emailMode ?? "otp",
+        params.multiFactors,
+        params.redirectParams
+      );
 
-      if (!temporarySession) {
-        this.store.setState({
-          status: AlchemySignerStatus.DISCONNECTED,
-        });
-        throw new Error("Could not find email auth init session!");
-      }
+    const isMfaRequired = multiFactors ? multiFactors?.length > 0 : false;
 
-      const user = await this.inner.completeAuthWithBundle({
-        bundle: params.bundle,
-        orgId: temporarySession.orgId,
-        connectedEventName: "connectedEmail",
-        authenticatingType: "email",
-      });
+    this.sessionManager.setTemporarySession({
+      orgId,
+      isNewUser,
+      isMfaRequired,
+    });
 
-      // fire new user event
-      this.emitNewUserEvent(params.isNewUser);
+    this.store.setState({
+      status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+      otpId,
+      error: null,
+      mfaStatus: {
+        mfaRequired: isMfaRequired,
+        mfaFactorId: multiFactors?.[0]?.multiFactorId,
+      },
+    });
 
-      return user;
-    }
+    // 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();
+      });
+    });
   };
 
   private authenticateWithPasskey = async (
@@ -893,7 +926,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     args: Extract<AuthParams, { type: "otp" }>
   ): Promise<User> => {
     const tempSession = this.sessionManager.getTemporarySession();
-    const { orgId, isNewUser } = tempSession ?? {};
+    const { orgId, isNewUser, isMfaRequired } = tempSession ?? {};
     const { otpId } = this.store.getState();
     if (!orgId) {
       throw new Error("orgId not found in session");
@@ -901,11 +934,16 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     if (!otpId) {
       throw new Error("otpId not found in session");
     }
+    if (isMfaRequired && !args.multiFactors) {
+      throw new Error(`MFA is required.`);
+    }
+
     const { bundle } = await this.inner.submitOtpCode({
       orgId,
       otpId,
       otpCode: args.otpCode,
       expirationSeconds: this.getExpirationSeconds(),
+      multiFactors: args.multiFactors,
     });
     const user = await this.inner.completeAuthWithBundle({
       bundle,
@@ -1011,6 +1049,79 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     // assumes that if isNewUser is undefined it is a returning user
     if (isNewUser) this.store.setState({ isNewUser });
   };
+
+  private async initOrCreateEmailUser(
+    email: string,
+    emailMode: EmailType,
+    multiFactors?: VerifyMfaParams[],
+    redirectParams?: URLSearchParams
+  ): Promise<{
+    orgId: string;
+    otpId?: string;
+    multiFactors?: MfaFactor[];
+    isNewUser: boolean;
+  }> {
+    const existingUser = await this.getUser(email);
+    const expirationSeconds = this.getExpirationSeconds();
+
+    if (existingUser) {
+      const {
+        orgId,
+        otpId,
+        multiFactors: mfaFactors,
+      } = await this.inner.initEmailAuth({
+        email: email,
+        emailMode: emailMode,
+        expirationSeconds,
+        redirectParams: redirectParams,
+        multiFactors,
+      });
+      return {
+        orgId,
+        otpId,
+        multiFactors: mfaFactors,
+        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;
+  }
 }
 
 function toErrorInfo(error: unknown): ErrorInfo {

package/src/client/base.ts

@@ -14,9 +14,13 @@ import type {
   AlchemySignerClientEvents,
   AuthenticatingEventMetadata,
   CreateAccountParams,
+  RemoveMfaParams,
   EmailAuthParams,
+  EnableMfaParams,
+  EnableMfaResult,
   GetOauthProviderUrlArgs,
   GetWebAuthnAttestationResult,
+  MfaFactor,
   OauthConfig,
   OauthParams,
   OauthState,
@@ -26,6 +30,7 @@ import type {
   SignerRoutes,
   SignupResponse,
   User,
+  VerifyMfaParams,
 } from "./types.js";
 
 export interface BaseSignerClientParams {
@@ -131,7 +136,44 @@ 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[];
+  }>;
 
   public abstract completeAuthWithBundle(params: {
     bundle: string;

package/src/client/index.ts

@@ -17,9 +17,23 @@ import type {
   OauthConfig,
   OtpParams,
   User,
+  MfaFactor,
+  EnableMfaParams,
+  EnableMfaResult,
+  VerifyMfaParams,
+  RemoveMfaParams,
 } from "./types.js";
+import { MfaRequiredError, NotAuthenticatedError } from "../errors.js";
+import { parseMfaError } from "../utils/parseMfaError.js";
 
 const CHECK_CLOSE_INTERVAL = 500;
+const MFA_PAYLOAD = {
+  GET: "get_mfa",
+  ADD: "add_mfa",
+  DELETE: "delete_mfas",
+  VERIFY: "verify_mfa",
+  LIST: "list_mfas",
+};
 
 export const AlchemySignerClientParamsSchema = z.object({
   connection: ConnectionConfigSchema,
@@ -198,13 +212,25 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     const { email, emailMode, expirationSeconds } = params;
     const publicKey = await this.initIframeStamper();
 
-    return this.request("/v1/auth", {
-      email,
-      emailMode,
-      targetPublicKey: publicKey,
-      expirationSeconds,
-      redirectParams: params.redirectParams?.toString(),
-    });
+    try {
+      return await this.request("/v1/auth", {
+        email,
+        emailMode,
+        targetPublicKey: publicKey,
+        expirationSeconds,
+        redirectParams: params.redirectParams?.toString(),
+        multiFactors: params.multiFactors,
+      });
+    } catch (error) {
+      const multiFactors = parseMfaError(error);
+
+      // If MFA is required, and emailMode is Magic Link, the user must submit mfa with the request or
+      // the the server will return an error with the required mfa factors.
+      if (multiFactors) {
+        throw new MfaRequiredError(multiFactors);
+      }
+      throw error;
+    }
   };
 
   /**
@@ -242,6 +268,12 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
       ...args,
       targetPublicKey,
     });
+
+    if (!credentialBundle) {
+      throw new Error(
+        "Failed to submit OTP code. Check if multiFactor is required."
+      );
+    }
     return { bundle: credentialBundle };
   }
 
@@ -670,6 +702,141 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     const nonce = this.getOauthNonce(publicKey);
     return this.request("/v1/prepare-oauth", { nonce });
   };
+
+  /**
+   * Retrieves the list of MFA factors configured for the current user.
+   *
+   * @returns {Promise<{ multiFactors: MfaFactor[] }>} A promise that resolves to an array of configured MFA factors
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   */
+  public override getMfaFactors = async (): Promise<{
+    multiFactors: MfaFactor[];
+  }> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const stampedRequest = await this.turnkeyClient.stampSignRawPayload({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
+        hashFunction: "HASH_FUNCTION_NO_OP",
+        payload: MFA_PAYLOAD.LIST,
+        signWith: this.user.address,
+      },
+    });
+
+    return this.request("/v1/auth-list-multi-factors", {
+      stampedRequest,
+    });
+  };
+
+  /**
+   * 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
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   * @throws {Error} If an unsupported factor type is provided
+   */
+  public override addMfa = async (
+    params: EnableMfaParams
+  ): Promise<EnableMfaResult> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const stampedRequest = await this.turnkeyClient.stampSignRawPayload({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
+        hashFunction: "HASH_FUNCTION_NO_OP",
+        payload: MFA_PAYLOAD.ADD,
+        signWith: this.user.address,
+      },
+    });
+
+    switch (params.multiFactorType) {
+      case "totp":
+        return this.request("/v1/auth-request-multi-factor", {
+          stampedRequest,
+          multiFactorType: params.multiFactorType,
+        });
+      default:
+        throw new Error(
+          `Unsupported MFA factor type: ${params.multiFactorType}`
+        );
+    }
+  };
+
+  /**
+   * 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
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   */
+  public override verifyMfa = async (
+    params: VerifyMfaParams
+  ): Promise<{ multiFactors: MfaFactor[] }> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const stampedRequest = await this.turnkeyClient.stampSignRawPayload({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
+        hashFunction: "HASH_FUNCTION_NO_OP",
+        payload: MFA_PAYLOAD.VERIFY,
+        signWith: this.user.address,
+      },
+    });
+
+    return this.request("/v1/auth-verify-multi-factor", {
+      stampedRequest,
+      multiFactorId: params.multiFactorId,
+      multiFactorCode: params.multiFactorCode,
+    });
+  };
+
+  /**
+   * Removes existing MFA factors by ID.
+   *
+   * @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
+   * @throws {NotAuthenticatedError} If no user is authenticated
+   */
+  public override removeMfa = async (
+    params: RemoveMfaParams
+  ): Promise<{ multiFactors: MfaFactor[] }> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const stampedRequest = await this.turnkeyClient.stampSignRawPayload({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
+        hashFunction: "HASH_FUNCTION_NO_OP",
+        payload: MFA_PAYLOAD.DELETE,
+        signWith: this.user.address,
+      },
+    });
+
+    return this.request("/v1/auth-delete-multi-factors", {
+      stampedRequest,
+      multiFactorIds: params.multiFactorIds,
+    });
+  };
 }
 
 /**

package/src/client/types.ts

@@ -52,6 +52,7 @@ export type EmailAuthParams = {
   expirationSeconds?: number;
   targetPublicKey: string;
   redirectParams?: URLSearchParams;
+  multiFactors?: VerifyMfaParams[];
 };
 
 export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
@@ -64,6 +65,7 @@ export type OtpParams = {
   otpCode: string;
   targetPublicKey: string;
   expirationSeconds?: number;
+  multiFactors?: VerifyMfaParams[];
 };
 
 export type SignupResponse = {
@@ -122,10 +124,12 @@ export type SignerEndpoints = [
     Route: "/v1/auth";
     Body: Omit<EmailAuthParams, "redirectParams"> & {
       redirectParams?: string;
+      multiFactors?: VerifyMfaParams[];
     };
     Response: {
       orgId: string;
       otpId?: string;
+      multiFactors?: MfaFactor[];
     };
   },
   {
@@ -156,7 +160,45 @@ export type SignerEndpoints = [
   {
     Route: "/v1/otp";
     Body: OtpParams;
-    Response: { credentialBundle: string };
+    Response: {
+      credentialBundle: string | null;
+    };
+  },
+  {
+    Route: "/v1/auth-list-multi-factors";
+    Body: {
+      stampedRequest: TSignedRequest;
+    };
+    Response: {
+      multiFactors: MfaFactor[];
+    };
+  },
+  {
+    Route: "/v1/auth-delete-multi-factors";
+    Body: {
+      stampedRequest: TSignedRequest;
+      multiFactorIds: string[];
+    };
+    Response: {
+      multiFactors: MfaFactor[];
+    };
+  },
+  {
+    Route: "/v1/auth-request-multi-factor";
+    Body: {
+      stampedRequest: TSignedRequest;
+      multiFactorType: MultiFactorType;
+    };
+    Response: EnableMfaResult;
+  },
+  {
+    Route: "/v1/auth-verify-multi-factor";
+    Body: VerifyMfaParams & {
+      stampedRequest: TSignedRequest;
+    };
+    Response: {
+      multiFactors: MfaFactor[];
+    };
   }
 ];
 
@@ -200,3 +242,38 @@ export type GetOauthProviderUrlArgs = {
   oauthConfig?: OauthConfig;
   usesRelativeUrl?: boolean;
 };
+
+export type MfaFactor = {
+  multiFactorId: string;
+  multiFactorType: string;
+};
+
+type MultiFactorType = "totp";
+
+export type EnableMfaParams = {
+  multiFactorType: MultiFactorType;
+};
+
+export type EnableMfaResult = {
+  multiFactorType: MultiFactorType;
+  multiFactorId: string;
+  multiFactorTotpUrl: string;
+};
+
+export type VerifyMfaParams = {
+  multiFactorId: string;
+  multiFactorCode: string;
+};
+
+export type RemoveMfaParams = {
+  multiFactorIds: string[];
+};
+
+export type MfaChallenge = {
+  multiFactorId: string;
+  multiFactorChallenge:
+    | {
+        code: string;
+      }
+    | Record<string, any>;
+};