@account-kit/signer 4.31.2 → 4.32.0

package/src/base.ts

@@ -21,17 +21,18 @@ import type { Mutate, StoreApi } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
 import { createStore } from "zustand/vanilla";
 import type { BaseSignerClient } from "./client/base";
-import type {
-  EmailType,
-  MfaFactor,
-  OauthConfig,
-  OauthParams,
-  User,
-  VerifyMfaParams,
-  AddMfaParams,
-  AddMfaResult,
-  RemoveMfaParams,
-} from "./client/types";
+import {
+  type EmailType,
+  type MfaFactor,
+  type OauthConfig,
+  type OauthParams,
+  type User,
+  type VerifyMfaParams,
+  type AddMfaParams,
+  type AddMfaResult,
+  type RemoveMfaParams,
+  type AuthLinkingPrompt,
+} from "./client/types.js";
 import { NotAuthenticatedError } from "./errors.js";
 import { SignerLogger } from "./metrics.js";
 import {
@@ -54,6 +55,7 @@ export interface BaseAlchemySignerParams<TClient extends BaseSignerClient> {
   client: TClient;
   sessionConfig?: Omit<SessionManagerParams, "client">;
   initialError?: ErrorInfo;
+  initialAuthLinkingPrompt?: AuthLinkingPrompt;
 }
 
 type AlchemySignerStore = {
@@ -67,6 +69,11 @@ type AlchemySignerStore = {
     mfaFactorId?: string;
     encryptedPayload?: string;
   };
+  authLinkingStatus?: {
+    email: string;
+    providerName: string;
+    idToken: string;
+  };
 };
 
 type UnpackedSignature = {
@@ -115,6 +122,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     client,
     sessionConfig,
     initialError,
+    initialAuthLinkingPrompt,
   }: BaseAlchemySignerParams<TClient>) {
     this.inner = client;
     this.store = createStore(
@@ -143,6 +151,9 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     // then initialize so that we can catch those events
     this.sessionManager.initialize();
     this.config = this.fetchConfig();
+    if (initialAuthLinkingPrompt) {
+      this.setAuthLinkingPrompt(initialAuthLinkingPrompt);
+    }
   }
 
   /**
@@ -161,52 +172,64 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     // is fired. In the Client and SessionManager we use EventEmitter because it's easier to handle internally
     switch (event) {
       case "connected":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ status }) => status,
           (status) =>
             status === AlchemySignerStatus.CONNECTED &&
             (listener as AlchemySignerEvents["connected"])(
               this.store.getState().user!
-            ),
-          { fireImmediately: true }
+            )
         );
       case "disconnected":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ status }) => status,
           (status) =>
             status === AlchemySignerStatus.DISCONNECTED &&
-            (listener as AlchemySignerEvents["disconnected"])(),
-          { fireImmediately: true }
+            (listener as AlchemySignerEvents["disconnected"])()
         );
       case "statusChanged":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ status }) => status,
-          listener as AlchemySignerEvents["statusChanged"],
-          { fireImmediately: true }
+          listener as AlchemySignerEvents["statusChanged"]
         );
       case "errorChanged":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ error }) => error,
           (error) =>
             (listener as AlchemySignerEvents["errorChanged"])(
               error ?? undefined
-            ),
-          { fireImmediately: true }
+            )
         );
       case "newUserSignup":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ isNewUser }) => isNewUser,
           (isNewUser) => {
             if (isNewUser) (listener as AlchemySignerEvents["newUserSignup"])();
-          },
-          { fireImmediately: true }
+          }
         );
       case "mfaStatusChanged":
-        return this.store.subscribe(
+        return subscribeWithDelayedFireImmediately(
+          this.store,
           ({ mfaStatus }) => mfaStatus,
           (mfaStatus) =>
-            (listener as AlchemySignerEvents["mfaStatusChanged"])(mfaStatus),
-          { fireImmediately: true }
+            (listener as AlchemySignerEvents["mfaStatusChanged"])(mfaStatus)
+        );
+      case "emailAuthLinkingRequired":
+        return subscribeWithDelayedFireImmediately(
+          this.store,
+          ({ authLinkingStatus }) => authLinkingStatus,
+          (authLinkingStatus) => {
+            if (authLinkingStatus) {
+              (listener as AlchemySignerEvents["emailAuthLinkingRequired"])(
+                authLinkingStatus.email
+              );
+            }
+          }
         );
       default:
         assertNever(event, `Unknown event type ${event}`);
@@ -855,25 +878,19 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
       params.redirectParams
     );
 
-    this.sessionManager.setTemporarySession({
-      orgId,
-      isNewUser,
-    });
+    this.setAwaitingEmailAuth({ orgId, otpId, isNewUser });
 
-    this.store.setState({
-      status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
-      otpId,
-      error: null,
-    });
+    // Clear the auth linking status if the email has changed. This would mean
+    // that the previously initiated social login is not associated with the
+    // email which is now being used to login.
+    const { authLinkingStatus } = this.store.getState();
+    if (authLinkingStatus && authLinkingStatus.email !== params.email) {
+      this.store.setState({ authLinkingStatus: undefined });
+    }
 
     // We wait for the session manager to emit a connected event if
     // cross tab sessions are permitted
-    return new Promise<User>((resolve) => {
-      const removeListener = this.sessionManager.on("connected", (session) => {
-        resolve(session.user);
-        removeListener();
-      });
-    });
+    return this.waitForConnected();
   };
 
   private authenticateWithPasskey = async (
@@ -919,15 +936,20 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   private authenticateWithOauth = async (
     args: Extract<AuthParams, { type: "oauth" }>
   ): Promise<User> => {
+    this.store.setState({ authLinkingStatus: undefined });
     const params: OauthParams = {
       ...args,
       expirationSeconds: this.getExpirationSeconds(),
     };
     if (params.mode === "redirect") {
       return this.inner.oauthWithRedirect(params);
-    } else {
-      return this.inner.oauthWithPopup(params);
     }
+    const result = await this.inner.oauthWithPopup(params);
+    if (!isAuthLinkingPrompt(result)) {
+      return result;
+    }
+    this.setAuthLinkingPrompt(result);
+    return this.waitForConnected();
   };
 
   private authenticateWithOtp = async (
@@ -953,16 +975,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
 
     if (response.mfaRequired) {
       this.handleMfaRequired(response.encryptedPayload, response.multiFactors);
-
-      return new Promise<User>((resolve) => {
-        const removeListener = this.sessionManager.on(
-          "connected",
-          (session) => {
-            resolve(session.user);
-            removeListener();
-          }
-        );
-      });
+      return this.waitForConnected();
     }
 
     const user = await this.inner.completeAuthWithBundle({
@@ -980,9 +993,39 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
       });
     }
 
+    const { authLinkingStatus } = this.store.getState();
+    if (authLinkingStatus) {
+      (async () => {
+        this.inner.addOauthProvider({
+          providerName: authLinkingStatus.providerName,
+          oidcToken: authLinkingStatus.idToken,
+        });
+      })();
+    }
+
     return user;
   };
 
+  private setAwaitingEmailAuth = ({
+    orgId,
+    otpId,
+    isNewUser,
+  }: {
+    orgId: string;
+    otpId?: string;
+    isNewUser?: boolean;
+  }): void => {
+    this.sessionManager.setTemporarySession({
+      orgId,
+      isNewUser,
+    });
+    this.store.setState({
+      status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+      otpId,
+      error: null,
+    });
+  };
+
   private handleOauthReturn = ({
     bundle,
     orgId,
@@ -1407,6 +1450,30 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   protected fetchConfig = async (): Promise<SignerConfig> => {
     return this.inner.request("/v1/signer-config", {});
   };
+
+  private setAuthLinkingPrompt = (prompt: AuthLinkingPrompt) => {
+    this.setAwaitingEmailAuth({
+      orgId: prompt.orgId,
+      otpId: prompt.otpId,
+      isNewUser: false,
+    });
+    this.store.setState({
+      authLinkingStatus: {
+        email: prompt.email,
+        providerName: prompt.providerName,
+        idToken: prompt.idToken,
+      },
+    });
+  };
+
+  private waitForConnected = (): Promise<User> => {
+    return new Promise<User>((resolve) => {
+      const removeListener = this.sessionManager.on("connected", (session) => {
+        resolve(session.user);
+        removeListener();
+      });
+    });
+  };
 }
 
 function toErrorInfo(error: unknown): ErrorInfo {
@@ -1414,3 +1481,52 @@ function toErrorInfo(error: unknown): ErrorInfo {
     ? { name: error.name, message: error.message }
     : { name: "Error", message: "Unknown error" };
 }
+
+// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns
+/**
+ * Zustand's `fireImmediately` option calls the listener before
+ * `store.subscribe` has returned, which breaks listeners which call
+ * unsubscribe, e.g.
+ *
+ * ```ts
+ * const unsubscribe = store.subscribe(
+ *   selector,
+ *   (update) => {
+ *     handleUpdate(update);
+ *     unsubscribe();
+ *   },
+ *   { fireImmediately: true },
+ * )
+ * ```
+ *
+ * since `unsubscribe` is still undefined at the time the listener is called. To
+ * prevent this, if the listener triggers before `subscribe` has returned, delay
+ * the callback to a later run of the event loop.
+ */
+function subscribeWithDelayedFireImmediately<T>(
+  store: InternalStore,
+  selector: (state: AlchemySignerStore) => T,
+  listener: (selectedState: T, previousSelectedState: T) => void
+): () => void {
+  let subscribeHasReturned = false;
+  const unsubscribe = store.subscribe(
+    selector,
+    (...args) => {
+      if (subscribeHasReturned) {
+        listener(...args);
+      } else {
+        setTimeout(() => listener(...args), 0);
+      }
+    },
+    { fireImmediately: true }
+  );
+  subscribeHasReturned = true;
+  return unsubscribe;
+}
+
+function isAuthLinkingPrompt(result: unknown): result is AuthLinkingPrompt {
+  return (
+    (result as AuthLinkingPrompt)?.status ===
+    "ACCOUNT_LINKING_CONFIRMATION_REQUIRED"
+  );
+}

package/src/client/base.ts

@@ -34,6 +34,8 @@ import type {
   VerifyMfaParams,
   SubmitOtpCodeResponse,
   ValidateMultiFactorsParams,
+  AuthLinkingPrompt,
+  AddOauthProviderParams,
 } from "./types.js";
 import { VERSION } from "../version.js";
 
@@ -99,13 +101,13 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   }
 
   protected set user(user: User | undefined) {
-    if (user && !this._user) {
+    const previousUser = this._user;
+    this._user = user;
+    if (user && !previousUser) {
       this.eventEmitter.emit("connected", user);
-    } else if (!user && this._user) {
+    } else if (!user && previousUser) {
       this.eventEmitter.emit("disconnected");
     }
-
-    this._user = user;
   }
 
   /**
@@ -160,11 +162,11 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract oauthWithRedirect(
     args: Extract<OauthParams, { mode: "redirect" }>
-  ): Promise<User | never>;
+  ): Promise<User>;
 
   public abstract oauthWithPopup(
     args: Extract<OauthParams, { mode: "popup" }>
-  ): Promise<User>;
+  ): Promise<User | AuthLinkingPrompt>;
 
   public abstract submitOtpCode(
     args: Omit<OtpParams, "targetPublicKey">
@@ -266,6 +268,32 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     };
   };
 
+  /**
+   * Adds an OAuth provider for the authenticated user using the provided parameters. Throws an error if the user is not authenticated.
+   *
+   * @param {AddOauthProviderParams} params The parameters for adding an OAuth provider, including `providerName` and `oidcToken`.
+   * @throws {NotAuthenticatedError} Throws if the user is not authenticated.
+   * @returns {Promise<void>} A Promise that resolves when the OAuth provider is added.
+   */
+  public addOauthProvider = async (
+    params: AddOauthProviderParams
+  ): Promise<void> => {
+    if (!this.user) {
+      throw new NotAuthenticatedError();
+    }
+    const { providerName, oidcToken } = params;
+    const stampedRequest = await this.turnkeyClient.stampCreateOauthProviders({
+      type: "ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS",
+      timestampMs: Date.now().toString(),
+      organizationId: this.user.orgId,
+      parameters: {
+        userId: this.user.userId,
+        oauthProviders: [{ providerName, oidcToken }],
+      },
+    });
+    await this.request("/v1/add-oauth-provider", { stampedRequest });
+  };
+
   /**
    * Retrieves the current user or fetches the user information if not already available.
    *
@@ -374,7 +402,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       throw new Error("User must be authenticated to create api key");
     }
     const resp = await this.turnkeyClient.createApiKeys({
-      type: "ACTIVITY_TYPE_CREATE_API_KEYS",
+      type: "ACTIVITY_TYPE_CREATE_API_KEYS_V2",
       timestampMs: new Date().getTime().toString(),
       organizationId: this.user.orgId,
       parameters: {
@@ -382,6 +410,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
           {
             apiKeyName: params.name,
             publicKey: params.publicKey,
+            curveType: "API_KEY_CURVE_P256",
             expirationSeconds: params.expirationSec.toString(),
           },
         ],

package/src/client/index.ts

@@ -18,6 +18,7 @@ import type {
   OtpParams,
   User,
   SubmitOtpCodeResponse,
+  AuthLinkingPrompt,
 } from "./types.js";
 import { MfaRequiredError } from "../errors.js";
 import { parseMfaError } from "../utils/parseMfaError.js";
@@ -531,7 +532,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    */
   public override oauthWithPopup = async (
     args: Extract<AuthParams, { type: "oauth"; mode: "popup" }>
-  ): Promise<User> => {
+  ): Promise<User | AuthLinkingPrompt> => {
     const turnkeyPublicKey = await this.initIframeStamper();
     const oauthParams = args;
     const providerUrl = await this.getOauthProviderUrl({
@@ -551,33 +552,55 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
           return;
         }
         const {
+          alchemyStatus: status,
           alchemyBundle: bundle,
           alchemyOrgId: orgId,
           alchemyIdToken: idToken,
           alchemyIsSignup: isSignup,
           alchemyError,
+          alchemyOtpId: otpId,
+          alchemyEmail: email,
+          alchemyAuthProvider: providerName,
         } = event.data;
-        if (bundle && orgId && idToken) {
-          cleanup();
-          popup?.close();
-          this.completeAuthWithBundle({
-            bundle,
-            orgId,
-            connectedEventName: "connectedOauth",
-            idToken,
-            authenticatingType: "oauth",
-          }).then((user) => {
-            if (isSignup) {
-              eventEmitter.emit("newUserSignup");
-            }
-
-            resolve(user);
-          }, reject);
-        } else if (alchemyError) {
+        if (alchemyError) {
           cleanup();
           popup?.close();
           reject(new OauthFailedError(alchemyError));
         }
+        if (!status) {
+          // This message isn't meant for us.
+          return;
+        }
+        cleanup();
+        popup?.close();
+        switch (status) {
+          case "SUCCESS":
+            this.completeAuthWithBundle({
+              bundle,
+              orgId,
+              connectedEventName: "connectedOauth",
+              idToken,
+              authenticatingType: "oauth",
+            }).then((user) => {
+              if (isSignup) {
+                eventEmitter.emit("newUserSignup");
+              }
+              resolve(user);
+            }, reject);
+            break;
+          case "ACCOUNT_LINKING_CONFIRMATION_REQUIRED":
+            resolve({
+              status,
+              idToken,
+              email,
+              providerName,
+              otpId,
+              orgId,
+            } satisfies AuthLinkingPrompt);
+            break;
+          default:
+            reject(new Error(`Unknown status: ${status}`));
+        }
       };
 
       window.addEventListener("message", handleMessage);

package/src/client/types.ts

@@ -171,6 +171,13 @@ export type SignerEndpoints = [
       signature: Hex;
     };
   },
+  {
+    Route: "/v1/add-oauth-provider";
+    Body: {
+      stampedRequest: TSignedRequest;
+    };
+    Response: void;
+  },
   {
     Route: "/v1/prepare-oauth";
     Body: {
@@ -262,6 +269,15 @@ export type GetWebAuthnAttestationResult = {
   authenticatorUserId: ArrayBuffer;
 };
 
+export type AuthLinkingPrompt = {
+  status: "ACCOUNT_LINKING_CONFIRMATION_REQUIRED";
+  idToken: string;
+  email: string;
+  providerName: string;
+  otpId: string;
+  orgId: string;
+};
+
 export type OauthState = {
   authProviderId: string;
   isCustomProvider?: boolean;
@@ -324,6 +340,11 @@ export type SubmitOtpCodeResponse =
   | { bundle: string; mfaRequired: false }
   | { mfaRequired: true; encryptedPayload: string; multiFactors: MfaFactor[] };
 
+export type AddOauthProviderParams = {
+  providerName: string;
+  oidcToken: string;
+};
+
 export type experimental_CreateApiKeyParams = {
   name: string;
   publicKey: string;

package/src/signer.ts

@@ -5,6 +5,7 @@ import {
   AlchemySignerWebClient,
 } from "./client/index.js";
 import type {
+  AuthLinkingPrompt,
   CredentialCreationOptionOverrides,
   VerifyMfaParams,
 } from "./client/types.js";
@@ -141,20 +142,28 @@ export class AlchemyWebSigner extends BaseAlchemySigner<AlchemySignerWebClient>
       emailBundle: "bundle",
       // We don't need this, but we still want to remove it from the URL.
       emailOrgId: "orgId",
+      status: "alchemy-status",
       oauthBundle: "alchemy-bundle",
       oauthOrgId: "alchemy-org-id",
-      oauthError: "alchemy-error",
       idToken: "alchemy-id-token",
       isSignup: "aa-is-signup",
+      otpId: "alchemy-otp-id",
+      email: "alchemy-email",
+      authProvider: "alchemy-auth-provider",
+      oauthError: "alchemy-error",
     };
 
     const {
       emailBundle,
+      status,
       oauthBundle,
       oauthOrgId,
-      oauthError,
       idToken,
       isSignup,
+      otpId,
+      email,
+      authProvider,
+      oauthError,
     } = getAndRemoveQueryParams(qpStructure);
 
     if (!AlchemyWebSigner.replaceStateFilterInstalled) {
@@ -167,7 +176,31 @@ export class AlchemyWebSigner extends BaseAlchemySigner<AlchemySignerWebClient>
         ? { name: "OauthError", message: oauthError }
         : undefined;
 
-    super({ client, sessionConfig, initialError });
+    const initialAuthLinkingPrompt: AuthLinkingPrompt | undefined = (() => {
+      if (status !== "ACCOUNT_LINKING_CONFIRMATION_REQUIRED") {
+        return undefined;
+      }
+      if (
+        idToken == null ||
+        email == null ||
+        authProvider == null ||
+        otpId == null ||
+        oauthOrgId == null
+      ) {
+        console.error("Missing required query params for auth linking prompt");
+        return undefined;
+      }
+      return {
+        status,
+        idToken,
+        email,
+        providerName: authProvider,
+        otpId,
+        orgId: oauthOrgId,
+      };
+    })();
+
+    super({ client, sessionConfig, initialError, initialAuthLinkingPrompt });
 
     const isNewUser = isSignup === "true";
 

package/src/solanaSigner.ts

@@ -88,17 +88,17 @@ export class SolanaSigner {
     return toBytes(this.formatSignatureForSolana(signature));
   }
 
-  async createTransfer(
+  async createTransaction(
     instructions: TransactionInstruction[],
     connection: Connection,
     version?: "versioned"
   ): Promise<VersionedTransaction>;
-  async createTransfer(
+  async createTransaction(
     instructions: TransactionInstruction[],
     connection: Connection,
     version?: "legacy"
   ): Promise<Transaction>;
-  async createTransfer(
+  async createTransaction(
     instructions: TransactionInstruction[],
     connection: Connection
   ): Promise<VersionedTransaction>;
@@ -111,7 +111,7 @@ export class SolanaSigner {
    * @param {"versioned" | "legacy"} [version] - The version of the transaction
    * @returns {Promise<Transaction | VersionedTransaction>} The transfer transaction
    */
-  async createTransfer(
+  async createTransaction(
     instructions: TransactionInstruction[],
     connection: Connection,
     version?: string

package/src/types.ts

@@ -11,6 +11,7 @@ export type AlchemySignerEvents = {
     mfaFactorId?: string;
     encryptedPayload?: string;
   }): void;
+  emailAuthLinkingRequired(email: string): void;
 };
 
 export type AlchemySignerEvent = keyof AlchemySignerEvents;

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