@account-kit/signer 4.0.0-beta.1 → 4.0.0-beta.10

package/src/base.ts

@@ -4,10 +4,14 @@ import {
   hashTypedData,
   keccak256,
   serializeTransaction,
-  type CustomSource,
+  type GetTransactionType,
   type Hex,
+  type IsNarrowable,
   type LocalAccount,
+  type SerializeTransactionFn,
   type SignableMessage,
+  type TransactionSerializable,
+  type TransactionSerialized,
   type TypedData,
   type TypedDataDefinition,
 } from "viem";
@@ -16,8 +20,9 @@ import type { Mutate, StoreApi } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
 import { createStore } from "zustand/vanilla";
 import type { BaseSignerClient } from "./client/base";
-import type { User } from "./client/types";
+import type { OauthConfig, OauthParams, User } from "./client/types";
 import { NotAuthenticatedError } from "./errors.js";
+import { SignerLogger } from "./metrics.js";
 import {
   SessionManager,
   type SessionManagerParams,
@@ -27,16 +32,20 @@ import {
   AlchemySignerStatus,
   type AlchemySignerEvent,
   type AlchemySignerEvents,
+  type ErrorInfo,
 } from "./types.js";
+import { assertNever } from "./utils/typeAssertions.js";
 
 export interface BaseAlchemySignerParams<TClient extends BaseSignerClient> {
   client: TClient;
   sessionConfig?: Omit<SessionManagerParams, "client">;
+  initialError?: ErrorInfo;
 }
 
 type AlchemySignerStore = {
   user: User | null;
   status: AlchemySignerStatus;
+  error: ErrorInfo | null;
 };
 
 type InternalStore = Mutate<
@@ -64,8 +73,13 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @param {BaseAlchemySignerParams<TClient>} param0 Object containing the client and session configuration
    * @param {TClient} param0.client The client instance to be used internally
    * @param {SessionConfig} param0.sessionConfig Configuration for managing sessions
+   * @param {ErrorInfo | undefined} param0.initialError Error already present on the signer when initialized, if any
    */
-  constructor({ client, sessionConfig }: BaseAlchemySignerParams<TClient>) {
+  constructor({
+    client,
+    sessionConfig,
+    initialError,
+  }: BaseAlchemySignerParams<TClient>) {
     this.inner = client;
     this.store = createStore(
       subscribeWithSelector(
@@ -73,6 +87,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
           ({
             user: null,
             status: AlchemySignerStatus.INITIALIZING,
+            error: initialError ?? null,
           } satisfies AlchemySignerStore)
       )
     );
@@ -83,15 +98,6 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
       ...sessionConfig,
       client: this.inner,
     });
-    this.store = createStore(
-      subscribeWithSelector(
-        () =>
-          ({
-            user: null,
-            status: AlchemySignerStatus.INITIALIZING,
-          } satisfies AlchemySignerStore)
-      )
-    );
     // register listeners first
     this.registerListeners();
     // then initialize so that we can catch those events
@@ -137,11 +143,51 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
           listener as AlchemySignerEvents["statusChanged"],
           { fireImmediately: true }
         );
+      case "errorChanged":
+        return this.store.subscribe(
+          ({ error }) => error,
+          (error) =>
+            (listener as AlchemySignerEvents["errorChanged"])(
+              error ?? undefined
+            ),
+          { fireImmediately: true }
+        );
       default:
-        throw new Error(`Uknown event type ${event}`);
+        assertNever(event, `Unknown event type ${event}`);
     }
   };
 
+  /**
+   * Prepares the config needed to use popup-based OAuth login. This must be
+   * called before calling `.authenticate` with params `{ type: "oauth", mode:
+   * "popup" }`, and is recommended to be called on page load.
+   *
+   * This method exists because browsers may prevent popups from opening unless
+   * triggered by user interaction, and so the OAuth config must already have
+   * been fetched at the time a user clicks a social login button.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * await signer.preparePopupOauth();
+   * ```
+   * @returns {Promise<OauthConfig>} the config which must be loaded before
+   * using popup-based OAuth
+   */
+  preparePopupOauth = (): Promise<OauthConfig> => this.inner.initOauth();
+
   /**
    * Authenticate a user with either an email or a passkey and create a session for that user
    *
@@ -169,12 +215,70 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @param {AuthParams} params - undefined if passkey login, otherwise an object with email and bundle to resolve
    * @returns {Promise<User>} the user that was authenticated
    */
-  authenticate: (params: AuthParams) => Promise<User> = async (params) => {
-    if (params.type === "email") {
-      return this.authenticateWithEmail(params);
+  authenticate: (params: AuthParams) => Promise<User> = SignerLogger.profiled(
+    "BaseAlchemySigner.authenticate",
+    async (params) => {
+      const { type } = params;
+      const result = (() => {
+        switch (type) {
+          case "email":
+            return this.authenticateWithEmail(params);
+          case "passkey":
+            return this.authenticateWithPasskey(params);
+          case "oauth":
+            return this.authenticateWithOauth(params);
+          case "oauthReturn":
+            return this.handleOauthReturn(params);
+          default:
+            assertNever(type, `Unknown auth type: ${type}`);
+        }
+      })();
+
+      this.trackAuthenticateType(params);
+
+      return result.catch((error) => {
+        this.store.setState({ error: toErrorInfo(error) });
+        throw error;
+      });
+    }
+  );
+
+  private trackAuthenticateType = (params: AuthParams) => {
+    const { type } = params;
+    switch (type) {
+      case "email": {
+        // we just want to track the start of email auth
+        if ("bundle" in params) return;
+        SignerLogger.trackEvent({
+          name: "signer_authnticate",
+          data: { authType: "email" },
+        });
+        return;
+      }
+      case "passkey": {
+        const isAnon = !("email" in params) && params.createNew == null;
+        SignerLogger.trackEvent({
+          name: "signer_authnticate",
+          data: {
+            authType: isAnon ? "passkey_anon" : "passkey_email",
+          },
+        });
+        return;
+      }
+      case "oauth":
+        SignerLogger.trackEvent({
+          name: "signer_authnticate",
+          data: {
+            authType: "oauth",
+            provider: params.authProviderId,
+          },
+        });
+        break;
+      case "oauthReturn":
+        break;
+      default:
+        assertNever(type, `Unknown auth type: ${type}`);
     }
-
-    return this.authenticateWithPasskey(params);
   };
 
   /**
@@ -245,11 +349,14 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    *
    * @returns {Promise<string>} A promise that resolves to the address of the current user.
    */
-  getAddress: () => Promise<`0x${string}`> = async () => {
-    const { address } = await this.inner.whoami();
+  getAddress: () => Promise<`0x${string}`> = SignerLogger.profiled(
+    "BaseAlchemySigner.getAddress",
+    async () => {
+      const { address } = await this.inner.whoami();
 
-    return address;
-  };
+      return address;
+    }
+  );
 
   /**
    * Signs a raw message after hashing it.
@@ -275,13 +382,18 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @param {string} msg the message to be hashed and then signed
    * @returns {Promise<string>} a promise that resolves to the signed message
    */
-  signMessage: (msg: SignableMessage) => Promise<`0x${string}`> = async (
-    msg
-  ) => {
-    const messageHash = hashMessage(msg);
+  signMessage: (msg: SignableMessage) => Promise<`0x${string}`> =
+    SignerLogger.profiled("BaseAlchemySigner.signMessage", async (msg) => {
+      const messageHash = hashMessage(msg);
 
-    return this.inner.signRawMessage(messageHash);
-  };
+      const result = await this.inner.signRawMessage(messageHash);
+
+      SignerLogger.trackEvent({
+        name: "signer_sign_message",
+      });
+
+      return result;
+    });
 
   /**
    * Signs a typed message by first hashing it and then signing the hashed message using the `signRawMessage` method.
@@ -317,11 +429,14 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     TPrimaryType extends keyof TTypedData | "EIP712Domain" = keyof TTypedData
   >(
     params: TypedDataDefinition<TTypedData, TPrimaryType>
-  ) => Promise<Hex> = async (params) => {
-    const messageHash = hashTypedData(params);
+  ) => Promise<Hex> = SignerLogger.profiled(
+    "BaseAlchemySigner.signTypedData",
+    async (params) => {
+      const messageHash = hashTypedData(params);
 
-    return this.inner.signRawMessage(messageHash);
-  };
+      return this.inner.signRawMessage(messageHash);
+    }
+  );
 
   /**
    * Serializes a transaction, signs it with a raw message, and then returns the serialized transaction with the signature.
@@ -353,21 +468,41 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @param {() => Hex} [args.serializer] an optional serializer function. If not provided, the default `serializeTransaction` function will be used
    * @returns {Promise<string>} a promise that resolves to the serialized transaction with the signature
    */
-  signTransaction: CustomSource["signTransaction"] = async (tx, args) => {
-    const serializeFn = args?.serializer ?? serializeTransaction;
-    const serializedTx = serializeFn(tx);
-    const signatureHex = await this.inner.signRawMessage(
-      keccak256(serializedTx)
-    );
+  signTransaction: <
+    serializer extends SerializeTransactionFn<TransactionSerializable> = SerializeTransactionFn<TransactionSerializable>,
+    transaction extends Parameters<serializer>[0] = Parameters<serializer>[0]
+  >(
+    transaction: transaction,
+    options?:
+      | {
+          serializer?: serializer | undefined;
+        }
+      | undefined
+  ) => Promise<
+    IsNarrowable<
+      TransactionSerialized<GetTransactionType<transaction>>,
+      Hex
+    > extends true
+      ? TransactionSerialized<GetTransactionType<transaction>>
+      : Hex
+  > = SignerLogger.profiled(
+    "BaseAlchemySigner.signTransaction",
+    async (tx, args) => {
+      const serializeFn = args?.serializer ?? serializeTransaction;
+      const serializedTx = serializeFn(tx);
+      const signatureHex = await this.inner.signRawMessage(
+        keccak256(serializedTx)
+      );
 
-    const signature = {
-      r: takeBytes(signatureHex, { count: 32 }),
-      s: takeBytes(signatureHex, { count: 32, offset: 32 }),
-      v: BigInt(takeBytes(signatureHex, { count: 1, offset: 64 })),
-    };
+      const signature = {
+        r: takeBytes(signatureHex, { count: 32 }),
+        s: takeBytes(signatureHex, { count: 32, offset: 32 }),
+        v: BigInt(takeBytes(signatureHex, { count: 1, offset: 64 })),
+      };
 
-    return serializeFn(tx, signature);
-  };
+      return serializeFn(tx, signature);
+    }
+  );
 
   /**
    * Unauthenticated call to look up a user's organizationId by email
@@ -393,19 +528,18 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @param {string} email the email to lookup
    * @returns {Promise<{orgId: string}>} the organization id for the user if they exist
    */
-  getUser: (email: string) => Promise<{ orgId: string } | null> = async (
-    email
-  ) => {
-    const result = await this.inner.lookupUserByEmail(email);
+  getUser: (email: string) => Promise<{ orgId: string } | null> =
+    SignerLogger.profiled("BaseAlchemySigner.getUser", async (email) => {
+      const result = await this.inner.lookupUserByEmail(email);
 
-    if (result.orgId == null) {
-      return null;
-    }
+      if (result.orgId == null) {
+        return null;
+      }
 
-    return {
-      orgId: result.orgId,
-    };
-  };
+      return {
+        orgId: result.orgId,
+      };
+    });
 
   /**
    * Adds a passkey to the user's account
@@ -432,9 +566,9 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * @returns {Promise<string[]>} an array of the authenticator ids added to the user
    */
   addPasskey: (params?: CredentialCreationOptions) => Promise<string[]> =
-    async (params) => {
+    SignerLogger.profiled("BaseAlchemySigner.addPasskey", async (params) => {
       return this.inner.addPasskey(params ?? {});
-    };
+    });
 
   /**
    * Used to export the wallet for a given user
@@ -519,22 +653,28 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   ): Promise<User> => {
     if ("email" in params) {
       const existingUser = await this.getUser(params.email);
+      const expirationSeconds = Math.floor(
+        this.sessionManager.expirationTimeMs / 1000
+      );
 
       const { orgId } = existingUser
         ? await this.inner.initEmailAuth({
             email: params.email,
-            expirationSeconds: this.sessionManager.expirationTimeMs,
+            expirationSeconds,
             redirectParams: params.redirectParams,
           })
         : await this.inner.createAccount({
             type: "email",
             email: params.email,
-            expirationSeconds: this.sessionManager.expirationTimeMs,
+            expirationSeconds,
             redirectParams: params.redirectParams,
           });
 
       this.sessionManager.setTemporarySession({ orgId });
-      this.store.setState({ status: AlchemySignerStatus.AWAITING_EMAIL_AUTH });
+      this.store.setState({
+        status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+        error: null,
+      });
 
       // We wait for the session manager to emit a connected event if
       // cross tab sessions are permitted
@@ -557,9 +697,11 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
         throw new Error("Could not find email auth init session!");
       }
 
-      const user = await this.inner.completeEmailAuth({
+      const user = await this.inner.completeAuthWithBundle({
         bundle: params.bundle,
         orgId: temporarySession.orgId,
+        connectedEventName: "connectedEmail",
+        authenticatingType: "email",
       });
 
       return user;
@@ -568,7 +710,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
 
   private authenticateWithPasskey = async (
     args: Extract<AuthParams, { type: "passkey" }>
-  ) => {
+  ): Promise<User> => {
     let user: User;
     const shouldCreateNew = async () => {
       if ("email" in args) {
@@ -604,11 +746,41 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return user;
   };
 
+  private authenticateWithOauth = async (
+    args: Extract<AuthParams, { type: "oauth" }>
+  ): Promise<User> => {
+    const params: OauthParams = {
+      ...args,
+      expirationSeconds: Math.floor(
+        this.sessionManager.expirationTimeMs / 1000
+      ),
+    };
+    if (params.mode === "redirect") {
+      return this.inner.oauthWithRedirect(params);
+    } else {
+      return this.inner.oauthWithPopup(params);
+    }
+  };
+
+  private handleOauthReturn = ({
+    bundle,
+    orgId,
+    idToken,
+  }: Extract<AuthParams, { type: "oauthReturn" }>): Promise<User> =>
+    this.inner.completeAuthWithBundle({
+      bundle,
+      orgId,
+      connectedEventName: "connectedOauth",
+      authenticatingType: "oauth",
+      idToken,
+    });
+
   private registerListeners = () => {
     this.sessionManager.on("connected", (session) => {
       this.store.setState({
         user: session.user,
         status: AlchemySignerStatus.CONNECTED,
+        error: null,
       });
     });
 
@@ -624,11 +796,34 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
         status: state.user
           ? AlchemySignerStatus.CONNECTED
           : AlchemySignerStatus.DISCONNECTED,
+        ...(state.user ? { error: null } : undefined),
       }));
     });
 
-    this.inner.on("authenticating", () => {
-      this.store.setState({ status: AlchemySignerStatus.AUTHENTICATING });
+    this.inner.on("authenticating", ({ type }) => {
+      const status = (() => {
+        switch (type) {
+          case "email":
+            return AlchemySignerStatus.AUTHENTICATING_EMAIL;
+          case "passkey":
+            return AlchemySignerStatus.AUTHENTICATING_PASSKEY;
+          case "oauth":
+            return AlchemySignerStatus.AUTHENTICATING_OAUTH;
+          default:
+            assertNever(type, "unhandled authenticating type");
+        }
+      })();
+
+      this.store.setState({
+        status,
+        error: null,
+      });
     });
   };
 }
+
+function toErrorInfo(error: unknown): ErrorInfo {
+  return error instanceof Error
+    ? { name: error.name, message: error.message }
+    : { name: "Error", message: "Unknown error" };
+}

package/src/client/base.ts

@@ -1,15 +1,20 @@
 import { ConnectionConfigSchema, type ConnectionConfig } from "@aa-sdk/core";
 import { TurnkeyClient, type TSignedRequest } from "@turnkey/http";
 import EventEmitter from "eventemitter3";
+import { jwtDecode } from "jwt-decode";
 import type { Hex } from "viem";
 import { NotAuthenticatedError } from "../errors.js";
 import { base64UrlEncode } from "../utils/base64UrlEncode.js";
+import { assertNever } from "../utils/typeAssertions.js";
 import type {
   AlchemySignerClientEvent,
   AlchemySignerClientEvents,
+  AuthenticatingEventMetadata,
   CreateAccountParams,
   EmailAuthParams,
   GetWebAuthnAttestationResult,
+  OauthConfig,
+  OauthParams,
   SignerBody,
   SignerResponse,
   SignerRoutes,
@@ -39,6 +44,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   protected turnkeyClient: TurnkeyClient;
   protected rootOrg: string;
   protected eventEmitter: EventEmitter<AlchemySignerClientEvents>;
+  protected oauthConfig: OauthConfig | undefined;
 
   /**
    * Create a new instance of the Alchemy Signer client
@@ -47,7 +53,6 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
    */
   constructor(params: BaseSignerClientParams) {
     const { stamper, connection, rootOrgId } = params;
-
     this.rootOrg = rootOrgId ?? "24c1acf5-810f-41e0-a503-d5d13fa8e830";
     this.eventEmitter = new EventEmitter<AlchemySignerClientEvents>();
     this.connectionConfig = ConnectionConfigSchema.parse(connection);
@@ -57,6 +62,16 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     );
   }
 
+  /**
+   * Asynchronously fetches and sets the OAuth configuration.
+   *
+   * @returns {Promise<OauthConfig>} A promise that resolves to the OAuth configuration
+   */
+  public initOauth = async (): Promise<OauthConfig> => {
+    this.oauthConfig = await this.getOauthConfig();
+    return this.oauthConfig;
+  };
+
   protected get user() {
     return this._user;
   }
@@ -92,11 +107,14 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     exportStamper: ExportWalletStamper;
     exportAs: "SEED_PHRASE" | "PRIVATE_KEY";
   }): Promise<boolean> {
-    switch (params.exportAs) {
+    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}`);
     }
   }
 
@@ -110,17 +128,30 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     params: Omit<EmailAuthParams, "targetPublicKey">
   ): Promise<{ orgId: string }>;
 
-  public abstract completeEmailAuth(params: {
+  public abstract completeAuthWithBundle(params: {
     bundle: string;
     orgId: string;
+    connectedEventName: keyof AlchemySignerClientEvents;
+    authenticatingType: AuthenticatingEventMetadata["type"];
+    idToken?: string;
   }): Promise<User>;
 
+  public abstract oauthWithRedirect(
+    args: Extract<OauthParams, { mode: "redirect" }>
+  ): Promise<never>;
+
+  public abstract oauthWithPopup(
+    args: Extract<OauthParams, { mode: "popup" }>
+  ): Promise<User>;
+
   public abstract disconnect(): Promise<void>;
 
   public abstract exportWallet(params: TExportWalletParams): Promise<boolean>;
 
   public abstract lookupUserWithPasskey(user?: User): Promise<User>;
 
+  protected abstract getOauthConfig(): Promise<OauthConfig>;
+
   protected abstract getWebAuthnAttestation(
     options: CredentialCreationOptions,
     userDetails?: { username: string }
@@ -190,10 +221,14 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
    * Retrieves the current user or fetches the user information if not already available.
    *
    * @param {string} [orgId] optional organization ID, defaults to the user's organization ID
+   * @param {string} idToken an OIDC ID token containing additional user information
    * @returns {Promise<User>} A promise that resolves to the user object
    * @throws {Error} if no organization ID is provided when there is no current user
    */
-  public whoami = async (orgId = this.user?.orgId): Promise<User> => {
+  public whoami = async (
+    orgId = this.user?.orgId,
+    idToken?: string
+  ): Promise<User> => {
     if (this.user) {
       return this.user;
     }
@@ -210,6 +245,15 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       stampedRequest,
     });
 
+    if (idToken) {
+      const claims: Record<string, unknown> = jwtDecode(idToken);
+      user.idToken = idToken;
+      user.claims = claims;
+      if (typeof claims.email === "string") {
+        user.email = claims.email;
+      }
+    }
+
     const credentialId = (() => {
       try {
         return JSON.parse(stampedRequest?.stamp.stampHeaderValue)
@@ -310,6 +354,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     body: SignerBody<R>
   ): Promise<SignerResponse<R>> => {
     const url = this.connectionConfig.rpcUrl ?? "https://api.g.alchemy.com";
+
     const basePath = "/signer";
 
     const headers = new Headers();