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

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

@@ -13,6 +13,7 @@ export type User = {
   orgId: string;
   userId: string;
   address: Address;
+  solanaAddress?: string;
   credentialId?: string;
   idToken?: string;
   claims?: Record<string, unknown>;
@@ -51,6 +52,7 @@ export type EmailAuthParams = {
   expirationSeconds?: number;
   targetPublicKey: string;
   redirectParams?: URLSearchParams;
+  multiFactors?: VerifyMfaParams[];
 };
 
 export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
@@ -63,6 +65,7 @@ export type OtpParams = {
   otpCode: string;
   targetPublicKey: string;
   expirationSeconds?: number;
+  multiFactors?: VerifyMfaParams[];
 };
 
 export type SignupResponse = {
@@ -121,10 +124,12 @@ export type SignerEndpoints = [
     Route: "/v1/auth";
     Body: Omit<EmailAuthParams, "redirectParams"> & {
       redirectParams?: string;
+      multiFactors?: VerifyMfaParams[];
     };
     Response: {
       orgId: string;
       otpId?: string;
+      multiFactors?: MfaFactor[];
     };
   },
   {
@@ -155,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[];
+    };
   }
 ];
 
@@ -199,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>;
+};

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,12 +6,17 @@ export {
   OauthFailedError,
 } from "./client/index.js";
 export type * from "./client/types.js";
+export {
+  NotAuthenticatedError,
+  OAuthProvidersError,
+  MfaRequiredError,
+} from "./errors.js";
 export {
   DEFAULT_SESSION_MS,
   SessionManagerParamsSchema,
 } from "./session/manager.js";
 export type * from "./signer.js";
 export { AlchemyWebSigner } from "./signer.js";
+export type * from "./solanaSigner.js";
 export type * from "./types.js";
 export { AlchemySignerStatus } from "./types.js";
-export { OAuthProvidersError, NotAuthenticatedError } from "./errors.js";

package/src/session/manager.ts

@@ -43,7 +43,11 @@ type Store = Mutate<
   [["zustand/subscribeWithSelector", never], ["zustand/persist", SessionState]]
 >;
 
-type TemporarySession = { orgId: string; isNewUser?: boolean };
+type TemporarySession = {
+  orgId: string;
+  isNewUser?: boolean;
+  isMfaRequired?: boolean;
+};
 
 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 =
@@ -13,6 +16,7 @@ export type AuthParams =
       email: string;
       emailMode?: "magicLink" | "otp";
       redirectParams?: URLSearchParams;
+      multiFactors?: VerifyMfaParams[];
     }
   | { type: "email"; bundle: string; orgId?: string; isNewUser?: boolean }
   | {
@@ -46,6 +50,7 @@ export type AuthParams =
   | {
       type: "otp";
       otpCode: string;
+      multiFactors?: VerifyMfaParams[];
     };
 
 export type OauthProviderConfig =

package/src/solanaSigner.ts

@@ -0,0 +1,83 @@
+import {
+  PublicKey,
+  Transaction,
+  type VersionedTransaction,
+} from "@solana/web3.js";
+import { size, slice, toBytes, toHex, type ByteArray, type Hex } from "viem";
+import type { BaseSignerClient } from "./client/base";
+import { NotAuthenticatedError } from "./errors.js";
+
+// TODO: I don't want this to be a class so that the flow is closer to how we do this for `toViemAccount`
+export class SolanaSigner {
+  private alchemyClient: BaseSignerClient;
+  public address: string;
+
+  constructor(client: BaseSignerClient) {
+    this.alchemyClient = client;
+    if (!client.getUser()) throw new Error("Must be authenticated!");
+
+    // TODO: also throw here
+    this.address = client.getUser()!.solanaAddress!;
+  }
+
+  async addSignature(
+    tx: Transaction | VersionedTransaction
+  ): Promise<Transaction | VersionedTransaction> {
+    const user = this.alchemyClient.getUser();
+    if (!user) {
+      throw new NotAuthenticatedError();
+    }
+
+    if (!user.solanaAddress) {
+      throw new Error("no solana address");
+    }
+
+    const fromKey = new PublicKey(user.solanaAddress);
+    const messageToSign = this.getMessageToSign(tx);
+    const signature = await this.alchemyClient.signRawMessage(
+      messageToSign,
+      "SOLANA"
+    );
+
+    tx.addSignature(
+      fromKey,
+      Buffer.from(toBytes(this.formatSignatureForSolana(signature)))
+    );
+    return tx;
+  }
+
+  async signMessage(message: Uint8Array): Promise<ByteArray> {
+    const user = this.alchemyClient.getUser();
+    if (!user) {
+      throw new NotAuthenticatedError();
+    }
+
+    if (!user.solanaAddress) {
+      throw new Error("no solana address");
+    }
+
+    const messageToSign = toHex(message);
+    const signature = await this.alchemyClient.signRawMessage(
+      messageToSign,
+      "SOLANA"
+    );
+
+    return toBytes(this.formatSignatureForSolana(signature));
+  }
+
+  private formatSignatureForSolana(signature: Hex): Hex {
+    if (size(signature) === 64) return signature;
+
+    return slice(signature, 0, 64);
+  }
+
+  private getMessageToSign(tx: Transaction | VersionedTransaction): Hex {
+    let messageToSign;
+    if (tx instanceof Transaction) {
+      messageToSign = tx.serializeMessage();
+    } else {
+      messageToSign = Buffer.from(tx.message.serialize());
+    }
+    return toHex(messageToSign);
+  }
+}

package/src/types.ts

@@ -6,6 +6,10 @@ export type AlchemySignerEvents = {
   disconnected(): void;
   statusChanged(status: AlchemySignerStatus): void;
   errorChanged(error: ErrorInfo | undefined): void;
+  mfaStatusChanged(mfaStatus: {
+    mfaRequired: boolean;
+    mfaFactorId?: string;
+  }): void;
 };
 
 export type AlchemySignerEvent = keyof AlchemySignerEvents;
@@ -21,6 +25,11 @@ export enum AlchemySignerStatus {
   AWAITING_OTP_AUTH = "AWAITING_OTP_AUTH",
 }
 
+export enum AlchemyMfaStatus {
+  NOT_REQUIRED = "not_required",
+  REQUIRED = "required",
+}
+
 export interface ErrorInfo {
   name: string;
   message: 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.15.3";
+export const VERSION = "4.16.1-alpha.3";