@account-kit/signer 4.21.0 → 4.23.0

package/src/client/index.ts

@@ -17,9 +17,25 @@ import type {
   OauthConfig,
   OtpParams,
   User,
+  MfaFactor,
+  EnableMfaParams,
+  EnableMfaResult,
+  VerifyMfaParams,
+  RemoveMfaParams,
+  SubmitOtpCodeResponse,
+  ValidateMultiFactorsParams,
 } 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 +214,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;
+    }
   };
 
   /**
@@ -235,14 +263,38 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    */
   public override async submitOtpCode(
     args: Omit<OtpParams, "targetPublicKey">
-  ): Promise<{ bundle: string }> {
+  ): Promise<SubmitOtpCodeResponse> {
     this.eventEmitter.emit("authenticating", { type: "otpVerify" });
     const targetPublicKey = await this.initIframeStamper();
-    const { credentialBundle } = await this.request("/v1/otp", {
+    const response = await this.request("/v1/otp", {
       ...args,
       targetPublicKey,
     });
-    return { bundle: credentialBundle };
+
+    if ("credentialBundle" in response && response.credentialBundle) {
+      return {
+        mfaRequired: false,
+        bundle: response.credentialBundle,
+      };
+    }
+
+    // If the server says "MFA_REQUIRED", pass that data back to the caller:
+    if (
+      response.status === "MFA_REQUIRED" &&
+      response.encryptedPayload &&
+      response.multiFactors
+    ) {
+      return {
+        mfaRequired: true,
+        encryptedPayload: response.encryptedPayload,
+        multiFactors: response.multiFactors,
+      };
+    }
+
+    // Otherwise, it's truly an error:
+    throw new Error(
+      "Failed to submit OTP code. Server did not return required fields."
+    );
   }
 
   /**
@@ -670,6 +722,169 @@ 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,
+    });
+  };
+
+  /**
+   * 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
+   * @throws {Error} If no credential bundle is returned from the server
+   */
+  public override async validateMultiFactors(
+    params: ValidateMultiFactorsParams
+  ): Promise<{ bundle: string }> {
+    // Send the encryptedPayload plus TOTP codes, etc:
+    const response = await this.request("/v1/auth-validate-multi-factors", {
+      encryptedPayload: params.encryptedPayload,
+      multiFactors: params.multiFactors,
+    });
+
+    // The server is expected to return the *decrypted* payload in `response.payload.credentialBundle`
+    if (!response.payload || !response.payload.credentialBundle) {
+      throw new Error(
+        "Request to validateMultiFactors did not return a credential bundle"
+      );
+    }
+
+    return {
+      bundle: response.payload.credentialBundle,
+    };
+  }
 }
 
 /**

package/src/client/types.ts

@@ -54,6 +54,7 @@ export type EmailAuthParams = {
   expirationSeconds?: number;
   targetPublicKey: string;
   redirectParams?: URLSearchParams;
+  multiFactors?: VerifyMfaParams[];
 };
 
 export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
@@ -66,8 +67,20 @@ export type OtpParams = {
   otpCode: string;
   targetPublicKey: string;
   expirationSeconds?: number;
+  multiFactors?: VerifyMfaParams[];
 };
 
+export type OtpResponse =
+  | {
+      status: "SUCCESS";
+      credentialBundle: string;
+    }
+  | {
+      status: "MFA_REQUIRED";
+      encryptedPayload: string;
+      multiFactors: MfaFactor[];
+    };
+
 export type SignupResponse = {
   orgId: string;
   userId?: string;
@@ -132,10 +145,12 @@ export type SignerEndpoints = [
     Route: "/v1/auth";
     Body: Omit<EmailAuthParams, "redirectParams"> & {
       redirectParams?: string;
+      multiFactors?: VerifyMfaParams[];
     };
     Response: {
       orgId: string;
       otpId?: string;
+      multiFactors?: MfaFactor[];
     };
   },
   {
@@ -166,12 +181,61 @@ export type SignerEndpoints = [
   {
     Route: "/v1/otp";
     Body: OtpParams;
-    Response: { credentialBundle: string };
+    Response: OtpResponse;
+  },
+  {
+    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[];
+    };
   },
   {
     Route: "/v1/signer-config";
     Body: {};
     Response: SignerConfig;
+  },
+  {
+    Route: "/v1/auth-validate-multi-factors";
+    Body: {
+      encryptedPayload: string;
+      multiFactors: VerifyMfaParams[];
+    };
+    Response: {
+      payload: {
+        credentialBundle?: string;
+      };
+      multiFactors: MfaFactor[];
+    };
   }
 ];
 
@@ -216,6 +280,53 @@ export type GetOauthProviderUrlArgs = {
   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 ValidateMultiFactorsParams = {
+  encryptedPayload: string;
+  multiFactors: Array<{
+    multiFactorId: string;
+    multiFactorCode: string;
+  }>;
+};
+
+export type MfaChallenge = {
+  multiFactorId: string;
+  multiFactorChallenge:
+    | {
+        code: string;
+      }
+    | Record<string, any>;
+};
+
+export type SubmitOtpCodeResponse =
+  | { bundle: string; mfaRequired: false }
+  | { mfaRequired: true; encryptedPayload: string; multiFactors: MfaFactor[] };
+
 export type experimental_CreateApiKeyParams = {
   name: string;
   publicKey: string;

package/src/errors.ts

@@ -1,5 +1,5 @@
 import { BaseError } from "@aa-sdk/core";
-
+import type { MfaFactor } from "./client/types";
 export class NotAuthenticatedError extends BaseError {
   override name = "NotAuthenticatedError";
   constructor() {
@@ -23,3 +23,13 @@ export class OAuthProvidersError extends BaseError {
     });
   }
 }
+
+export class MfaRequiredError extends BaseError {
+  override name = "MfaRequiredError";
+  public multiFactors: MfaFactor[];
+
+  constructor(multiFactors: MfaFactor[]) {
+    super("MFA is required for this user");
+    this.multiFactors = multiFactors;
+  }
+}

package/src/index.ts

@@ -6,7 +6,11 @@ export {
   OauthFailedError,
 } from "./client/index.js";
 export type * from "./client/types.js";
-export { NotAuthenticatedError, OAuthProvidersError } from "./errors.js";
+export {
+  NotAuthenticatedError,
+  OAuthProvidersError,
+  MfaRequiredError,
+} from "./errors.js";
 export {
   DEFAULT_SESSION_MS,
   SessionManagerParamsSchema,

package/src/session/manager.ts

@@ -43,7 +43,12 @@ type Store = Mutate<
   [["zustand/subscribeWithSelector", never], ["zustand/persist", SessionState]]
 >;
 
-type TemporarySession = { orgId: string; isNewUser?: boolean };
+type TemporarySession = {
+  orgId: string;
+  isNewUser?: boolean;
+  encryptedPayload?: string;
+  mfaFactorId?: string;
+};
 
 export class SessionManager {
   private sessionKey: string;

package/src/signer.ts

@@ -4,7 +4,10 @@ import {
   AlchemySignerClientParamsSchema,
   AlchemySignerWebClient,
 } from "./client/index.js";
-import type { CredentialCreationOptionOverrides } from "./client/types.js";
+import type {
+  CredentialCreationOptionOverrides,
+  VerifyMfaParams,
+} from "./client/types.js";
 import { SessionManagerParamsSchema } from "./session/manager.js";
 
 export type AuthParams =
@@ -14,6 +17,7 @@ export type AuthParams =
       /** @deprecated This option will be overriden by dashboard settings. Please use the dashboard settings instead. This option will be removed in a future release. */
       emailMode?: "magicLink" | "otp";
       redirectParams?: URLSearchParams;
+      multiFactors?: VerifyMfaParams[];
     }
   | { type: "email"; bundle: string; orgId?: string; isNewUser?: boolean }
   | {
@@ -48,6 +52,7 @@ export type AuthParams =
   | {
       type: "otp";
       otpCode: string;
+      multiFactors?: VerifyMfaParams[];
     };
 
 export type OauthProviderConfig =

package/src/types.ts

@@ -6,6 +6,11 @@ export type AlchemySignerEvents = {
   disconnected(): void;
   statusChanged(status: AlchemySignerStatus): void;
   errorChanged(error: ErrorInfo | undefined): void;
+  mfaStatusChanged(mfaStatus: {
+    mfaRequired: boolean;
+    mfaFactorId?: string;
+    encryptedPayload?: string;
+  }): void;
 };
 
 export type AlchemySignerEvent = keyof AlchemySignerEvents;
@@ -19,9 +24,20 @@ export enum AlchemySignerStatus {
   AUTHENTICATING_OAUTH = "AUTHENTICATING_OAUTH",
   AWAITING_EMAIL_AUTH = "AWAITING_EMAIL_AUTH",
   AWAITING_OTP_AUTH = "AWAITING_OTP_AUTH",
+  AWAITING_MFA_AUTH = "AWAITING_MFA_AUTH",
+}
+
+export enum AlchemyMfaStatus {
+  NOT_REQUIRED = "not_required",
+  REQUIRED = "required",
 }
 
 export interface ErrorInfo {
   name: string;
   message: string;
 }
+
+export type ValidateMultiFactorsArgs = {
+  multiFactorId?: string;
+  multiFactorCode: string;
+};

package/src/utils/parseMfaError.ts

@@ -0,0 +1,15 @@
+import type { MfaFactor } from "../client/types.js";
+
+export function parseMfaError(error: unknown): MfaFactor[] | null {
+  if (error instanceof Error) {
+    try {
+      const parsed = JSON.parse(error.message);
+      if (parsed?.data?.multiFactors) {
+        return parsed.data.multiFactors;
+      }
+    } catch {
+      // ignore JSON parse failures
+    }
+  }
+  return null;
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is autogenerated by inject-version.ts. Any changes will be
 // overwritten on commit!
-export const VERSION = "4.21.0";
+export const VERSION = "4.23.0";