@account-kit/signer 4.21.0 → 4.23.0

package/dist/esm/base.d.ts

@@ -2,11 +2,11 @@ import { type SmartAccountAuthenticator } from "@aa-sdk/core";
 import { type GetTransactionType, type Hex, type IsNarrowable, type LocalAccount, type SerializeTransactionFn, type SignableMessage, type TransactionSerializable, type TransactionSerialized, type TypedData, type TypedDataDefinition } from "viem";
 import { type Authorization } from "viem/experimental";
 import type { BaseSignerClient } from "./client/base";
-import type { OauthConfig, User } from "./client/types";
+import type { MfaFactor, OauthConfig, User, VerifyMfaParams, EnableMfaParams, EnableMfaResult, RemoveMfaParams } from "./client/types";
 import { type SessionManagerParams } from "./session/manager.js";
 import type { AuthParams } from "./signer";
 import { SolanaSigner } from "./solanaSigner.js";
-import { type AlchemySignerEvents, type ErrorInfo } from "./types.js";
+import { type AlchemySignerEvents, type ErrorInfo, type ValidateMultiFactorsArgs } from "./types.js";
 export interface BaseAlchemySignerParams<TClient extends BaseSignerClient> {
     client: TClient;
     sessionConfig?: Omit<SessionManagerParams, "client">;
@@ -281,6 +281,36 @@ export declare abstract class BaseAlchemySigner<TClient extends BaseSignerClient
      * @returns {Promise<Authorization<number, true>> | undefined} a promise that resolves to the authorization with the signature
      */
     signAuthorization: (unsignedAuthorization: Authorization<number, false>) => Promise<Authorization<number, true>>;
+    /**
+     * 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;
+    };
     private unpackSignRawMessageBytes;
     /**
      * Unauthenticated call to look up a user's organizationId by email
@@ -421,9 +451,160 @@ export declare abstract class BaseAlchemySigner<TClient extends BaseSignerClient
     private authenticateWithOauth;
     private authenticateWithOtp;
     private handleOauthReturn;
+    private handleMfaRequired;
     private getExpirationSeconds;
     private registerListeners;
     private emitNewUserEvent;
+    private initOrCreateEmailUser;
+    private completeEmailAuth;
+    /**
+     * 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[];
+    }>;
+    /**
+     * 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>;
+    /**
+     * 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[];
+    }>;
+    /**
+     * 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[];
+    }>;
+    /**
+     * 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
+     */
+    validateMultiFactors(params: ValidateMultiFactorsArgs): Promise<User>;
     protected initConfig: () => Promise<SignerConfig>;
     /**
      * Returns the signer configuration while fetching it if it's not already initialized.

package/dist/esm/base.js

@@ -87,6 +87,8 @@ export class BaseAlchemySigner {
                             if (isNewUser)
                                 listener();
                         }, { fireImmediately: true });
+                    case "mfaStatusChanged":
+                        return this.store.subscribe(({ mfaStatus }) => mfaStatus, (mfaStatus) => listener(mfaStatus), { fireImmediately: true });
                     default:
                         assertNever(event, `Unknown event type ${event}`);
                 }
@@ -483,6 +485,40 @@ export class BaseAlchemySigner {
                 return { ...unsignedAuthorization, ...signature };
             })
         });
+        /**
+         * 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
+         */
+        Object.defineProperty(this, "getMfaStatus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                return this.store.getState().mfaStatus;
+            }
+        });
         Object.defineProperty(this, "unpackSignRawMessageBytes", {
             enumerable: true,
             configurable: true,
@@ -691,61 +727,27 @@ export class BaseAlchemySigner {
             configurable: true,
             writable: true,
             value: async (params) => {
-                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,
-                        });
-                    this.sessionManager.setTemporarySession({
-                        orgId,
-                        isNewUser: !existingUser,
-                    });
-                    this.store.setState({
-                        status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
-                        otpId,
-                        error: null,
-                    });
-                    // We wait for the session manager to emit a connected event if
-                    // cross tab sessions are permitted
-                    return new Promise((resolve) => {
-                        const removeListener = this.sessionManager.on("connected", (session) => {
-                            resolve(session.user);
-                            removeListener();
-                        });
-                    });
+                if ("bundle" in params) {
+                    return this.completeEmailAuth(params);
                 }
-                else {
-                    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",
+                const { orgId, otpId, isNewUser } = await this.initOrCreateEmailUser(params.email, params.emailMode, params.multiFactors, params.redirectParams);
+                this.sessionManager.setTemporarySession({
+                    orgId,
+                    isNewUser,
+                });
+                this.store.setState({
+                    status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+                    otpId,
+                    error: null,
+                });
+                // We wait for the session manager to emit a connected event if
+                // cross tab sessions are permitted
+                return new Promise((resolve) => {
+                    const removeListener = this.sessionManager.on("connected", (session) => {
+                        resolve(session.user);
+                        removeListener();
                     });
-                    // fire new user event
-                    this.emitNewUserEvent(params.isNewUser);
-                    return user;
-                }
+                });
             }
         });
         Object.defineProperty(this, "authenticateWithPasskey", {
@@ -814,14 +816,24 @@ export class BaseAlchemySigner {
                 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((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",
@@ -928,6 +940,144 @@ export class BaseAlchemySigner {
                     this.store.setState({ isNewUser });
             }
         });
+        /**
+         * 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
+         */
+        Object.defineProperty(this, "getMfaFactors", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 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
+         */
+        Object.defineProperty(this, "addMfa", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 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
+         */
+        Object.defineProperty(this, "verifyMfa", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 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
+         */
+        Object.defineProperty(this, "removeMfa", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: SignerLogger.profiled("BaseAlchemySigner.removeMfa", async (params) => {
+                return this.inner.removeMfa(params);
+            })
+        });
         Object.defineProperty(this, "initConfig", {
             enumerable: true,
             configurable: true,
@@ -966,6 +1116,10 @@ export class BaseAlchemySigner {
             user: null,
             status: AlchemySignerStatus.INITIALIZING,
             error: initialError ?? null,
+            mfaStatus: {
+                mfaRequired: false,
+                mfaFactorId: undefined,
+            },
         })));
         // NOTE: it's important that the session manager share a client
         // with the signer. The SessionManager leverages the Signer's client
@@ -980,6 +1134,149 @@ export class BaseAlchemySigner {
         this.sessionManager.initialize();
         this.config = this.fetchConfig();
     }
+    handleMfaRequired(encryptedPayload, multiFactors) {
+        // 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,
+            },
+        });
+    }
+    async initOrCreateEmailUser(email, emailMode, multiFactors, redirectParams) {
+        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,
+        };
+    }
+    async completeEmailAuth(params) {
+        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;
+    }
+    /**
+     * 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
+     */
+    async validateMultiFactors(params) {
+        // 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;
+    }
 }
 function toErrorInfo(error) {
     return error instanceof Error