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

package/src/client/base.ts

@@ -4,7 +4,7 @@ import EventEmitter from "eventemitter3";
 import { jwtDecode } from "jwt-decode";
 import { sha256, type Hex } from "viem";
 import { NotAuthenticatedError, OAuthProvidersError } from "../errors.js";
-import { addOpenIdIfAbsent, getDefaultScopeAndClaims } from "../oauth.js";
+import { getDefaultProviderCustomization } from "../oauth.js";
 import type { OauthMode } from "../signer.js";
 import { base64UrlEncode } from "../utils/base64UrlEncode.js";
 import { resolveRelativeUrl } from "../utils/resolveRelativeUrl.js";
@@ -14,13 +14,11 @@ import type {
   AlchemySignerClientEvents,
   AuthenticatingEventMetadata,
   CreateAccountParams,
-  RemoveMfaParams,
   EmailAuthParams,
-  EnableMfaParams,
-  EnableMfaResult,
   GetOauthProviderUrlArgs,
   GetWebAuthnAttestationResult,
-  MfaFactor,
+  JwtParams,
+  JwtResponse,
   OauthConfig,
   OauthParams,
   OauthState,
@@ -30,8 +28,8 @@ import type {
   SignerRoutes,
   SignupResponse,
   User,
-  VerifyMfaParams,
 } from "./types.js";
+import { VERSION } from "../version.js";
 
 export interface BaseSignerClientParams {
   stamper: TurnkeyClient["stamper"];
@@ -136,44 +134,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract initEmailAuth(
     params: Omit<EmailAuthParams, "targetPublicKey">
-  ): Promise<{ orgId: string; otpId?: string; multiFactors?: MfaFactor[] }>;
-
-  /**
-   * Retrieves the list of MFA factors configured for the current user.
-   *
-   * @returns {Promise<{ multiFactors: Array<MfaFactor> }>} A promise that resolves to an array of configured MFA factors
-   */
-  public abstract getMfaFactors(): Promise<{
-    multiFactors: MfaFactor[];
-  }>;
-
-  /**
-   * 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
-   */
-  public abstract addMfa(params: EnableMfaParams): Promise<EnableMfaResult>;
-
-  /**
-   * 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
-   */
-  public abstract verifyMfa(params: VerifyMfaParams): Promise<{
-    multiFactors: MfaFactor[];
-  }>;
-
-  /**
-   * Removes existing MFA factors by ID or factor type.
-   *
-   * @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
-   */
-  public abstract removeMfa(params: RemoveMfaParams): Promise<{
-    multiFactors: MfaFactor[];
-  }>;
+  ): Promise<{ orgId: string; otpId?: string }>;
 
   public abstract completeAuthWithBundle(params: {
     bundle: string;
@@ -195,6 +156,10 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     args: Omit<OtpParams, "targetPublicKey">
   ): Promise<{ bundle: string }>;
 
+  public abstract submitJwt(
+    args: Omit<JwtParams, "targetPublicKey">
+  ): Promise<JwtResponse>;
+
   public abstract disconnect(): Promise<void>;
 
   public abstract exportWallet(params: TExportWalletParams): Promise<boolean>;
@@ -424,6 +389,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     const basePath = "/signer";
 
     const headers = new Headers();
+    headers.append("Alchemy-AA-Sdk-Version", VERSION);
     headers.append("Content-Type", "application/json");
     if (this.connectionConfig.apiKey) {
       headers.append("Authorization", `Bearer ${this.connectionConfig.apiKey}`);
@@ -582,6 +548,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       auth0Connection,
       scope: providedScope,
       claims: providedClaims,
+      otherParameters: providedOtherParameters,
       mode,
       redirectUrl,
       expirationSeconds,
@@ -604,23 +571,20 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       throw new Error(`No auth provider found with id ${authProviderId}`);
     }
 
-    let scope: string;
-    let claims: string | undefined;
-
-    if (providedScope) {
-      scope = addOpenIdIfAbsent(providedScope);
-      claims = providedClaims;
-    } else {
-      if (isCustomProvider) {
-        throw new Error("scope must be provided for a custom provider");
-      }
-      const scopeAndClaims = getDefaultScopeAndClaims(authProviderId);
-      if (!scopeAndClaims) {
-        throw new Error(
-          `Default scope not known for provider ${authProviderId}`
-        );
-      }
-      ({ scope, claims } = scopeAndClaims);
+    let scope: string | undefined = providedScope;
+    let claims: string | undefined = providedClaims;
+    let otherParameters: Record<string, string> | undefined =
+      providedOtherParameters;
+
+    if (!isCustomProvider) {
+      const defaultCustomization =
+        getDefaultProviderCustomization(authProviderId);
+      scope ??= defaultCustomization?.scope;
+      claims ??= defaultCustomization?.claims;
+      otherParameters ??= defaultCustomization?.otherParameters;
+    }
+    if (!scope) {
+      throw new Error(`Default scope not known for provider ${authProviderId}`);
     }
     const { authEndpoint, clientId } = authProvider;
 
@@ -653,10 +617,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
       prompt: "select_account",
       client_id: clientId,
       nonce,
-      // Fixes Facebook mobile login so that `window.opener` doesn't get nullified.
-      ...(mode === "popup" && authProvider.id === "facebook"
-        ? { sdk: "joey" }
-        : {}),
+      ...otherParameters,
     };
     if (claims) {
       params.claims = claims;

package/src/client/index.ts

@@ -14,26 +14,14 @@ import type {
   CredentialCreationOptionOverrides,
   EmailAuthParams,
   ExportWalletParams,
+  JwtParams,
   OauthConfig,
   OtpParams,
+  JwtResponse,
   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,
@@ -212,25 +200,13 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     const { email, emailMode, expirationSeconds } = params;
     const publicKey = await this.initIframeStamper();
 
-    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;
-    }
+    return this.request("/v1/auth", {
+      email,
+      emailMode,
+      targetPublicKey: publicKey,
+      expirationSeconds,
+      redirectParams: params.redirectParams?.toString(),
+    });
   };
 
   /**
@@ -268,15 +244,46 @@ 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 };
   }
 
+  /**
+   * Authenticates using a custom issued JWT
+   *
+   * @example
+   * ```ts
+   * import { AlchemySignerWebClient } from "@account-kit/signer";
+   *
+   * const client = new AlchemySignerWebClient({
+   *  connection: {
+   *    apiKey: "your-api-key",
+   *  },
+   *  iframeConfig: {
+   *   iframeContainerId: "signer-iframe-container",
+   *  },
+   * });
+   *
+   * const account = await client.submitJwt({
+   *   jwt: "custom-issued-jwt",
+   *   authProvider: "auth-provider-name",
+   * });
+   * ```
+   *
+   * @param {Omit<JwtParams, "targetPublicKey">} args The parameters for the JWT request, excluding the target public key.
+   * @returns {Promise<{ bundle: string }>} A promise that resolves to an object containing the credential bundle.
+   */
+  public override async submitJwt(
+    args: Omit<JwtParams, "targetPublicKey">
+  ): Promise<JwtResponse> {
+    this.eventEmitter.emit("authenticating", { type: "custom-jwt" });
+    const targetPublicKey = await this.initIframeStamper();
+    return this.request("/v1/auth-jwt", {
+      jwt: args.jwt,
+      targetPublicKey,
+      authProvider: args.authProvider,
+    });
+  }
+
   /**
    * Completes auth for the user by injecting a credential bundle and retrieving
    * the user information based on the provided organization ID. Emits events
@@ -702,141 +709,6 @@ 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

@@ -29,6 +29,7 @@ export type CreateAccountParams =
   | {
       type: "email";
       email: string;
+      /** @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?: EmailType;
       expirationSeconds?: number;
       redirectParams?: URLSearchParams;
@@ -48,11 +49,11 @@ export type EmailType = "magicLink" | "otp";
 
 export type EmailAuthParams = {
   email: string;
+  /** @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?: EmailType;
   expirationSeconds?: number;
   targetPublicKey: string;
   redirectParams?: URLSearchParams;
-  multiFactors?: VerifyMfaParams[];
 };
 
 export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
@@ -65,7 +66,18 @@ export type OtpParams = {
   otpCode: string;
   targetPublicKey: string;
   expirationSeconds?: number;
-  multiFactors?: VerifyMfaParams[];
+};
+
+export type JwtParams = {
+  jwt: string;
+  targetPublicKey: string;
+  authProvider: string;
+};
+
+export type JwtResponse = {
+  isSignUp: boolean;
+  orgId: string;
+  credentialBundle: string;
 };
 
 export type SignupResponse = {
@@ -81,6 +93,14 @@ export type OauthConfig = {
   authProviders: AuthProviderConfig[];
 };
 
+export type EmailConfig = {
+  mode?: "MAGIC_LINK" | "OTP";
+};
+
+export type SignerConfig = {
+  email: EmailConfig;
+};
+
 export type AuthProviderConfig = {
   id: string;
   isCustomProvider?: boolean;
@@ -124,12 +144,10 @@ export type SignerEndpoints = [
     Route: "/v1/auth";
     Body: Omit<EmailAuthParams, "redirectParams"> & {
       redirectParams?: string;
-      multiFactors?: VerifyMfaParams[];
     };
     Response: {
       orgId: string;
       otpId?: string;
-      multiFactors?: MfaFactor[];
     };
   },
   {
@@ -160,50 +178,22 @@ export type SignerEndpoints = [
   {
     Route: "/v1/otp";
     Body: OtpParams;
-    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[];
-    };
+    Response: { credentialBundle: string };
   },
   {
-    Route: "/v1/auth-request-multi-factor";
-    Body: {
-      stampedRequest: TSignedRequest;
-      multiFactorType: MultiFactorType;
-    };
-    Response: EnableMfaResult;
+    Route: "/v1/auth-jwt";
+    Body: JwtParams;
+    Response: JwtResponse;
   },
   {
-    Route: "/v1/auth-verify-multi-factor";
-    Body: VerifyMfaParams & {
-      stampedRequest: TSignedRequest;
-    };
-    Response: {
-      multiFactors: MfaFactor[];
-    };
+    Route: "/v1/signer-config";
+    Body: {};
+    Response: SignerConfig;
   }
 ];
 
 export type AuthenticatingEventMetadata = {
-  type: "email" | "passkey" | "oauth" | "otp" | "otpVerify";
+  type: "email" | "passkey" | "oauth" | "otp" | "otpVerify" | "custom-jwt";
 };
 
 export type AlchemySignerClientEvents = {
@@ -214,6 +204,7 @@ export type AlchemySignerClientEvents = {
   connectedPasskey(user: User): void;
   connectedOauth(user: User, bundle: string): void;
   connectedOtp(user: User, bundle: string): void;
+  connectedJwt(user: User, bundle: string): void;
   disconnected(): void;
 };
 
@@ -242,38 +233,3 @@ 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,13 +23,3 @@ 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,11 +6,7 @@ export {
   OauthFailedError,
 } from "./client/index.js";
 export type * from "./client/types.js";
-export {
-  NotAuthenticatedError,
-  OAuthProvidersError,
-  MfaRequiredError,
-} from "./errors.js";
+export { NotAuthenticatedError, OAuthProvidersError } from "./errors.js";
 export {
   DEFAULT_SESSION_MS,
   SessionManagerParamsSchema,

package/src/metrics.ts

@@ -14,7 +14,8 @@ export type SignerEventsSchema = [
             | "oauthReturn";
           provider?: never;
         }
-      | { authType: "oauth"; provider: string };
+      | { authType: "oauth"; provider: string }
+      | { authType: "custom-jwt"; provider: string };
   },
   {
     EventName: "signer_sign_message";

package/src/oauth.ts

@@ -1,27 +1,41 @@
 import type { KnownAuthProvider } from "./signer";
 
-export type ScopeAndClaims = {
+export type AuthProviderCustomization = {
   scope: string;
   claims?: string;
+  otherParameters?: Record<string, string>;
 };
 
-const DEFAULT_SCOPE_AND_CLAIMS: Record<KnownAuthProvider, ScopeAndClaims> = {
+const DEFAULT_PROVIDER_CUSTOMIZATION: Record<
+  KnownAuthProvider,
+  AuthProviderCustomization
+> = {
   google: { scope: "openid email" },
   apple: { scope: "openid email" },
-  facebook: { scope: "openid email" },
+  facebook: {
+    scope: "openid email",
+    // Fixes Facebook mobile login so that `window.opener` doesn't get nullified.
+    otherParameters: { sdk: "joey" },
+  },
+  twitch: {
+    scope: "openid user:read:email",
+    claims: JSON.stringify({ id_token: { email: null } }),
+    // Forces Twitch to show the login page even if the user is already logged in.
+    otherParameters: { force_verify: "true" },
+  },
   auth0: { scope: "openid email" },
 };
 
 /**
- * Returns the default scope and claims when using a known auth provider
+ * Returns the default customization parameters when using a known auth provider
  *
  * @param {string} knownAuthProviderId id of a known auth provider, e.g. "google"
- * @returns {ScopeAndClaims | undefined} default scope and claims
+ * @returns {AuthProviderCustomization | undefined} default customization parameters
  */
-export function getDefaultScopeAndClaims(
+export function getDefaultProviderCustomization(
   knownAuthProviderId: KnownAuthProvider
-): ScopeAndClaims | undefined {
-  return DEFAULT_SCOPE_AND_CLAIMS[knownAuthProviderId];
+): AuthProviderCustomization | undefined {
+  return DEFAULT_PROVIDER_CUSTOMIZATION[knownAuthProviderId];
 }
 
 /**