@account-kit/signer 4.60.1 → 4.62.0

package/src/client/base.ts

@@ -15,7 +15,6 @@ import { getDefaultProviderCustomization } from "../oauth.js";
 import type { OauthMode } from "../signer.js";
 import { base64UrlEncode } from "../utils/base64UrlEncode.js";
 import { resolveRelativeUrl } from "../utils/resolveRelativeUrl.js";
-import { assertNever } from "../utils/typeAssertions.js";
 import type {
   AlchemySignerClientEvent,
   AlchemySignerClientEvents,
@@ -50,6 +49,7 @@ import type {
   IdTokenOnly,
   AuthMethods,
   SmsAuthParams,
+  VerificationOtp,
 } from "./types.js";
 import { VERSION } from "../version.js";
 import { secp256k1 } from "@noble/curves/secp256k1";
@@ -81,7 +81,10 @@ const withHexPrefix = (hex: string) => `0x${hex}` as const;
 /**
  * Base class for all Alchemy Signer clients
  */
-export abstract class BaseSignerClient<TExportWalletParams = unknown> {
+export abstract class BaseSignerClient<
+  TExportWalletParams = unknown,
+  TExportWalletOutput = unknown,
+> {
   private _user: User | undefined;
   private connectionConfig: ConnectionConfig;
   protected turnkeyClient: TurnkeyClient;
@@ -137,29 +140,6 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     this.turnkeyClient.stamper = stamper;
   }
 
-  /**
-   * Exports wallet credentials based on the specified type, either as a SEED_PHRASE or PRIVATE_KEY.
-   *
-   * @param {object} params The parameters for exporting the wallet
-   * @param {ExportWalletStamper} params.exportStamper The stamper used for exporting the wallet
-   * @param {"SEED_PHRASE" | "PRIVATE_KEY"} params.exportAs Specifies the format for exporting the wallet, either as a SEED_PHRASE or PRIVATE_KEY
-   * @returns {Promise<boolean>} A promise that resolves to true if the export is successful
-   */
-  protected exportWalletInner(params: {
-    exportStamper: ExportWalletStamper;
-    exportAs: "SEED_PHRASE" | "PRIVATE_KEY";
-  }): Promise<boolean> {
-    const { exportAs } = params;
-    switch (exportAs) {
-      case "PRIVATE_KEY":
-        return this.exportAsPrivateKey(params.exportStamper);
-      case "SEED_PHRASE":
-        return this.exportAsSeedPhrase(params.exportStamper);
-      default:
-        assertNever(exportAs, `Unknown export mode: ${exportAs}`);
-    }
-  }
-
   /**
    * Authenticates the user by either email or passkey account creation flow. Emits events during the process.
    *
@@ -265,7 +245,9 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract disconnect(): Promise<void>;
 
-  public abstract exportWallet(params: TExportWalletParams): Promise<boolean>;
+  public abstract exportWallet(
+    params: TExportWalletParams,
+  ): Promise<TExportWalletOutput>;
 
   public abstract targetPublicKey(): Promise<string>;
 
@@ -310,53 +292,178 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
    * Sets the email for the authenticated user, allowing them to login with that
    * email.
    *
-   * You must contact Alchemy to enable this feature for your team, as there are
-   * important security considerations. In particular, you must not call this
-   * without first validating that the user owns this email account.
+   * @deprecated You must contact Alchemy to enable this feature for your team,
+   * as there are important security considerations. In particular, you must not
+   * call this without first validating that the user owns this email account.
+   * Recommended to use the email verification flow instead.
    *
    * @param {string} email The email to set for the user
-   * @returns {Promise<void>} A promise that resolves when the email is set
+   * @returns {Promise<void>} A promise that resolves to the updated email
    * @throws {NotAuthenticatedError} If the user is not authenticated
    */
-  public setEmail = async (email: string): Promise<void> => {
-    if (!email) {
-      throw new Error(
-        "Email must not be empty. Use removeEmail() to remove email auth.",
-      );
+  public setEmail(email: string): Promise<string>;
+
+  /**
+   * Sets the email for the authenticated user, allowing them to login with that
+   * email.  Must be called after calling `initOtp` with the email.
+   *
+   * @param {VerificationOtp} otp The OTP verification object including the OTP ID and OTP code
+   * @returns {Promise<void>} A promise that resolves to the updated email
+   * @throws {NotAuthenticatedError} If the user is not authenticated
+   */
+  public setEmail(otp: VerificationOtp): Promise<string>;
+
+  /**
+   * Implementation for setEmail method with optional OTP verification.
+   *
+   * @param {string | VerificationOtp} params An OTP object containing the OTP ID & OTP code (or an email address for legacy usage)
+   * @returns {Promise<void>} A promise that resolves to the updated email address
+   */
+  public async setEmail(params: string | VerificationOtp): Promise<string> {
+    if (typeof params === "string") {
+      // Legacy use, requires team flag.
+      const contact = params;
+      if (!contact) {
+        throw new Error(
+          "Email must not be empty. Use removeEmail() to remove email auth.",
+        );
+      }
+      await this.updateEmail(contact);
+      return contact;
     }
-    await this.updateEmail(email);
-  };
+
+    const { verificationToken } = await this.request("/v1/verify-otp", {
+      otpId: params.id,
+      otpCode: params.code,
+    });
+    const { contact } = jwtDecode<{ contact: string }>(verificationToken);
+    await this.updateEmail(contact, verificationToken);
+    return contact;
+  }
 
   /**
    * Removes the email for the authenticated user, disallowing them from login with that email.
    *
-   * @returns {Promise<void>} A promise that resolves when the email is removed
+   * @returns {Promise<string>} A promise that resolves when the email is removed
    * @throws {NotAuthenticatedError} If the user is not authenticated
    */
   public removeEmail = async (): Promise<void> => {
-    // This is a hack to remove the email for the user. Turnkey does not
-    // support clearing the email once set, so we set it to a known
-    // inaccessible address instead.
-    await this.updateEmail("not.enabled@example.invalid");
+    await this.updateEmail("");
+  };
+
+  private updateEmail = async (
+    email: string,
+    verificationToken?: string,
+  ): Promise<void> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    // Unverified use is legacy & requires team flag.
+    const isUnverified = email && !verificationToken;
+
+    const stampedRequest = isUnverified
+      ? await this.turnkeyClient.stampUpdateUser({
+          type: "ACTIVITY_TYPE_UPDATE_USER",
+          timestampMs: Date.now().toString(),
+          organizationId: this.user.orgId,
+          parameters: {
+            userId: this.user.userId,
+            userEmail: email,
+          },
+        })
+      : await this.turnkeyClient.stampUpdateUserEmail({
+          type: "ACTIVITY_TYPE_UPDATE_USER_EMAIL",
+          timestampMs: Date.now().toString(),
+          organizationId: this.user.orgId,
+          parameters: {
+            userId: this.user.userId,
+            userEmail: email,
+            verificationToken,
+          },
+        });
+
+    await this.request("/v1/update-email-auth", {
+      stampedRequest,
+    });
+    this.user = {
+      ...this.user,
+      email: email || undefined,
+    };
+  };
+
+  /**
+   * Updates the phone number for the authenticated user, allowing them to login with that
+   * phone number. Must be called after calling `initOtp` with the phone number.
+   *
+   * @param {VerificationOtp} otp The OTP object including the OTP ID and OTP code
+   * @returns {Promise<void>} A promise that resolves when the phone number is set
+   * @throws {NotAuthenticatedError} If the user is not authenticated
+   */
+  public setPhoneNumber = async (otp: VerificationOtp): Promise<void> => {
+    const { verificationToken } = await this.request("/v1/verify-otp", {
+      otpId: otp.id,
+      otpCode: otp.code,
+    });
+    const { contact } = jwtDecode<{ contact: string }>(verificationToken);
+    await this.updatePhoneNumber(contact, verificationToken);
   };
 
-  private updateEmail = async (email: string): Promise<void> => {
+  /**
+   * Removes the phone number for the authenticated user, disallowing them from login with that phone number.
+   *
+   * @returns {Promise<void>} A promise that resolves when the phone number is removed
+   * @throws {NotAuthenticatedError} If the user is not authenticated
+   */
+  public removePhoneNumber = async (): Promise<void> => {
+    await this.updatePhoneNumber("");
+  };
+
+  private updatePhoneNumber = async (
+    phone: string,
+    verificationToken?: string,
+  ): Promise<void> => {
     if (!this.user) {
       throw new NotAuthenticatedError();
     }
-    const stampedRequest = await this.turnkeyClient.stampUpdateUser({
-      type: "ACTIVITY_TYPE_UPDATE_USER",
+    if (phone.trim() && !verificationToken) {
+      throw new Error("Verification token is required to change phone number.");
+    }
+    const stampedRequest = await this.turnkeyClient.stampUpdateUserPhoneNumber({
+      type: "ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER",
       timestampMs: Date.now().toString(),
       organizationId: this.user.orgId,
       parameters: {
         userId: this.user.userId,
-        userEmail: email,
-        userTagIds: [],
+        userPhoneNumber: phone,
+        verificationToken,
       },
     });
-    await this.request("/v1/update-email-auth", {
+    await this.request("/v1/update-phone-auth", {
       stampedRequest,
     });
+    this.user = {
+      ...this.user,
+      phone: phone || undefined,
+    };
+  };
+
+  /**
+   * Initiates an OTP (One-Time Password) verification process for a user contact.
+   *
+   * @param {("email" | "sms")} type - The type of OTP to send, either "email" or "sms"
+   * @param {string} contact - The email address or phone number to send the OTP to
+   * @returns {Promise<{ otpId: string }>} A promise that resolves to an object containing the OTP ID
+   * @throws {NotAuthenticatedError} When no user is currently authenticated
+   */
+  public initOtp = async (
+    type: "email" | "sms",
+    contact: string,
+  ): Promise<{ otpId: string }> => {
+    return await this.request("/v1/init-otp", {
+      otpType: type === "email" ? "OTP_TYPE_EMAIL" : "OTP_TYPE_SMS",
+      contact,
+    });
   };
 
   /**
@@ -780,7 +887,9 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
       return {
         stampHeaderName: "X-Stamp",
-        stampHeaderValue: base64UrlEncode(Buffer.from(JSON.stringify(stamp))),
+        stampHeaderValue: base64UrlEncode(
+          Buffer.from(JSON.stringify(stamp)).buffer,
+        ),
       };
     },
   });
@@ -1141,94 +1250,6 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   // #endregion
 
   // #region PRIVATE METHODS
-  private exportAsSeedPhrase = async (stamper: ExportWalletStamper) => {
-    if (!this.user) {
-      throw new NotAuthenticatedError();
-    }
-
-    const { wallets } = await this.turnkeyClient.getWallets({
-      organizationId: this.user.orgId,
-    });
-
-    const walletAccounts = await Promise.all(
-      wallets.map(({ walletId }) =>
-        this.turnkeyClient.getWalletAccounts({
-          organizationId: this.user!.orgId,
-          walletId,
-        }),
-      ),
-    ).then((x) => x.flatMap((x) => x.accounts));
-
-    const walletAccount = walletAccounts.find(
-      (x) => x.address === this.user!.address,
-    );
-
-    if (!walletAccount) {
-      throw new Error(
-        `Could not find wallet associated with ${this.user.address}`,
-      );
-    }
-
-    const { activity } = await this.turnkeyClient.exportWallet({
-      organizationId: this.user.orgId,
-      type: "ACTIVITY_TYPE_EXPORT_WALLET",
-      timestampMs: Date.now().toString(),
-      parameters: {
-        walletId: walletAccount!.walletId,
-        targetPublicKey: stamper.publicKey()!,
-      },
-    });
-
-    const { exportBundle } = await this.pollActivityCompletion(
-      activity,
-      this.user.orgId,
-      "exportWalletResult",
-    );
-
-    const result = await stamper.injectWalletExportBundle(
-      exportBundle,
-      this.user.orgId,
-    );
-
-    if (!result) {
-      throw new Error("Failed to inject wallet export bundle");
-    }
-
-    return result;
-  };
-
-  private exportAsPrivateKey = async (stamper: ExportWalletStamper) => {
-    if (!this.user) {
-      throw new NotAuthenticatedError();
-    }
-
-    const { activity } = await this.turnkeyClient.exportWalletAccount({
-      organizationId: this.user.orgId,
-      type: "ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT",
-      timestampMs: Date.now().toString(),
-      parameters: {
-        address: this.user.address,
-        targetPublicKey: stamper.publicKey()!,
-      },
-    });
-
-    const { exportBundle } = await this.pollActivityCompletion(
-      activity,
-      this.user.orgId,
-      "exportWalletAccountResult",
-    );
-
-    const result = await stamper.injectKeyExportBundle(
-      exportBundle,
-      this.user.orgId,
-    );
-
-    if (!result) {
-      throw new Error("Failed to inject wallet export bundle");
-    }
-
-    return result;
-  };
 
   /**
    * Returns the authentication url for the selected OAuth Proivder
@@ -1337,7 +1358,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       fetchIdTokenOnly: oauthParams.fetchIdTokenOnly,
     };
     const state = base64UrlEncode(
-      new TextEncoder().encode(JSON.stringify(stateObject)),
+      new TextEncoder().encode(JSON.stringify(stateObject)).buffer,
     );
     const authUrl = new URL(authEndpoint);
     const params: Record<string, string> = {

package/src/client/index.ts

@@ -5,7 +5,9 @@ import { WebauthnStamper } from "@turnkey/webauthn-stamper";
 import { z } from "zod";
 import type { AuthParams } from "../signer.js";
 import { generateRandomBuffer } from "../utils/generateRandomBuffer.js";
-import { BaseSignerClient } from "./base.js";
+import { assertNever } from "../utils/typeAssertions.js";
+import { BaseSignerClient, type ExportWalletStamper } from "./base.js";
+import { NotAuthenticatedError } from "../errors.js";
 import type {
   AlchemySignerClientEvents,
   AuthenticatingEventMetadata,
@@ -22,6 +24,7 @@ import type {
   GetWebAuthnAttestationResult,
   IdTokenOnly,
   SmsAuthParams,
+  ExportWalletOutput,
 } from "./types.js";
 import { MfaRequiredError } from "../errors.js";
 import { parseMfaError } from "../utils/parseMfaError.js";
@@ -54,7 +57,10 @@ export type AlchemySignerClientParams = z.input<
  * A lower level client used by the AlchemySigner used to communicate with
  * Alchemy's signer service.
  */
-export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams> {
+export class AlchemySignerWebClient extends BaseSignerClient<
+  ExportWalletParams,
+  ExportWalletOutput
+> {
   private iframeStamper: IframeStamper;
   private webauthnStamper: WebauthnStamper;
   oauthCallbackUrl: string;
@@ -389,7 +395,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
   public override exportWallet = async ({
     iframeContainerId,
     iframeElementId = "turnkey-export-iframe",
-  }: ExportWalletParams) => {
+  }: ExportWalletParams): Promise<ExportWalletOutput> => {
     const exportWalletIframeStamper = new IframeStamper({
       iframeContainer: document.getElementById(iframeContainerId),
       iframeElementId: iframeElementId,
@@ -410,6 +416,29 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     });
   };
 
+  /**
+   * Exports wallet credentials based on the specified type, either as a SEED_PHRASE or PRIVATE_KEY.
+   *
+   * @param {object} params The parameters for exporting the wallet
+   * @param {ExportWalletStamper} params.exportStamper The stamper used for exporting the wallet
+   * @param {"SEED_PHRASE" | "PRIVATE_KEY"} params.exportAs Specifies the format for exporting the wallet, either as a SEED_PHRASE or PRIVATE_KEY
+   * @returns {Promise<boolean>} A promise that resolves to true if the export is successful
+   */
+  protected exportWalletInner(params: {
+    exportStamper: ExportWalletStamper;
+    exportAs: "SEED_PHRASE" | "PRIVATE_KEY";
+  }): Promise<ExportWalletOutput> {
+    const { exportAs } = params;
+    switch (exportAs) {
+      case "PRIVATE_KEY":
+        return this.exportAsPrivateKey(params.exportStamper);
+      case "SEED_PHRASE":
+        return this.exportAsSeedPhrase(params.exportStamper);
+      default:
+        assertNever(exportAs, `Unknown export mode: ${exportAs}`);
+    }
+  }
+
   /**
    * Asynchronous function that clears the user and resets the iframe stamper.
    *
@@ -748,6 +777,96 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
       ];
     }
   }
+
+  private exportAsSeedPhrase = async (stamper: ExportWalletStamper) => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const { wallets } = await this.turnkeyClient.getWallets({
+      organizationId: this.user.orgId,
+    });
+
+    const walletAccountResponses = await Promise.all(
+      wallets.map(({ walletId }) =>
+        this.turnkeyClient.getWalletAccounts({
+          organizationId: this.user!.orgId,
+          walletId,
+        }),
+      ),
+    );
+    const walletAccounts = walletAccountResponses.flatMap((x) => x.accounts);
+
+    const walletAccount = walletAccounts.find(
+      (x) => x.address.toLowerCase() === this.user!.address.toLowerCase(),
+    );
+
+    if (!walletAccount) {
+      throw new Error(
+        `Could not find wallet associated with ${this.user.address}`,
+      );
+    }
+
+    const { activity } = await this.turnkeyClient.exportWallet({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_EXPORT_WALLET",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        walletId: walletAccount!.walletId,
+        targetPublicKey: stamper.publicKey()!,
+      },
+    });
+
+    const { exportBundle } = await this.pollActivityCompletion(
+      activity,
+      this.user.orgId,
+      "exportWalletResult",
+    );
+
+    const result = await stamper.injectWalletExportBundle(
+      exportBundle,
+      this.user.orgId,
+    );
+
+    if (!result) {
+      throw new Error("Failed to inject wallet export bundle");
+    }
+
+    return result;
+  };
+
+  private exportAsPrivateKey = async (stamper: ExportWalletStamper) => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+
+    const { activity } = await this.turnkeyClient.exportWalletAccount({
+      organizationId: this.user.orgId,
+      type: "ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT",
+      timestampMs: Date.now().toString(),
+      parameters: {
+        address: this.user.address,
+        targetPublicKey: stamper.publicKey()!,
+      },
+    });
+
+    const { exportBundle } = await this.pollActivityCompletion(
+      activity,
+      this.user.orgId,
+      "exportWalletAccountResult",
+    );
+
+    const result = await stamper.injectKeyExportBundle(
+      exportBundle,
+      this.user.orgId,
+    );
+
+    if (!result) {
+      throw new Error("Failed to inject wallet export bundle");
+    }
+
+    return result;
+  };
 }
 
 /**

package/src/client/types.ts

@@ -7,6 +7,15 @@ import type {
 import type { Hex } from "viem";
 import type { AuthParams } from "../signer";
 
+// [!region VerificationOtp]
+export type VerificationOtp = {
+  /** The OTP ID returned from initOtp */
+  id: string;
+  /** The OTP code received by the user */
+  code: string;
+};
+// [!endregion VerificationOtp]
+
 export type CredentialCreationOptionOverrides = {
   publicKey?: Partial<CredentialCreationOptions["publicKey"]>;
 } & Pick<CredentialCreationOptions, "signal">;
@@ -14,6 +23,7 @@ export type CredentialCreationOptionOverrides = {
 // [!region User]
 export type User = {
   email?: string;
+  phone?: string;
   orgId: string;
   userId: string;
   address: Address;
@@ -30,6 +40,8 @@ export type ExportWalletParams = {
   iframeElementId?: string;
 };
 
+export type ExportWalletOutput = boolean;
+
 export type CreateAccountParams =
   | {
       type: "email";
@@ -195,6 +207,26 @@ export type SignerEndpoints = [
       orgId: string | null;
     };
   },
+  {
+    Route: "/v1/init-otp";
+    Body: {
+      contact: string;
+      otpType: "OTP_TYPE_SMS" | "OTP_TYPE_EMAIL";
+    };
+    Response: {
+      otpId: string;
+    };
+  },
+  {
+    Route: "/v1/verify-otp";
+    Body: {
+      otpId: string;
+      otpCode: string;
+    };
+    Response: {
+      verificationToken: string;
+    };
+  },
   {
     Route: "/v1/sign-payload";
     Body: {
@@ -211,6 +243,13 @@ export type SignerEndpoints = [
     };
     Response: void;
   },
+  {
+    Route: "/v1/update-phone-auth";
+    Body: {
+      stampedRequest: TSignedRequest;
+    };
+    Response: void;
+  },
   {
     Route: "/v1/add-oauth-provider";
     Body: {
@@ -510,6 +549,7 @@ export type AddOauthProviderParams = {
 
 export type AuthMethods = {
   email?: string;
+  phone?: string;
   oauthProviders: OauthProviderInfo[];
   passkeys: PasskeyInfo[];
 };

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.60.1";
+export const VERSION = "4.62.0";