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

package/src/client/index.ts

@@ -1,19 +1,27 @@
-import { ConnectionConfigSchema } from "@aa-sdk/core";
+import { BaseError, ConnectionConfigSchema } from "@aa-sdk/core";
 import { getWebAuthnAttestation } from "@turnkey/http";
 import { IframeStamper } from "@turnkey/iframe-stamper";
 import { WebauthnStamper } from "@turnkey/webauthn-stamper";
 import { z } from "zod";
+import { getDefaultScopeAndClaims, getOauthNonce } from "../oauth.js";
+import type { AuthParams, OauthMode } from "../signer.js";
 import { base64UrlEncode } from "../utils/base64UrlEncode.js";
 import { generateRandomBuffer } from "../utils/generateRandomBuffer.js";
 import { BaseSignerClient } from "./base.js";
 import type {
+  AlchemySignerClientEvents,
+  AuthenticatingEventMetadata,
   CreateAccountParams,
   CredentialCreationOptionOverrides,
   EmailAuthParams,
   ExportWalletParams,
+  OauthConfig,
+  OauthParams,
   User,
 } from "./types.js";
 
+const CHECK_CLOSE_INTERVAL = 500;
+
 export const AlchemySignerClientParamsSchema = z.object({
   connection: ConnectionConfigSchema,
   iframeConfig: z.object({
@@ -25,12 +33,27 @@ export const AlchemySignerClientParamsSchema = z.object({
     .string()
     .optional()
     .default("24c1acf5-810f-41e0-a503-d5d13fa8e830"),
+  oauthCallbackUrl: z
+    .string()
+    .optional()
+    .default("https://signer.alchemy.com/callback"),
+  enablePopupOauth: z.boolean().optional().default(false),
 });
 
 export type AlchemySignerClientParams = z.input<
   typeof AlchemySignerClientParamsSchema
 >;
 
+type OauthState = {
+  authProviderId: string;
+  isCustomProvider?: boolean;
+  requestKey: string;
+  turnkeyPublicKey: string;
+  expirationSeconds?: number;
+  redirectUrl?: string;
+  openerOrigin?: string;
+};
+
 /**
  * A lower level client used by the AlchemySigner used to communicate with
  * Alchemy's signer service.
@@ -38,6 +61,7 @@ export type AlchemySignerClientParams = z.input<
 export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams> {
   private iframeStamper: IframeStamper;
   private webauthnStamper: WebauthnStamper;
+  oauthCallbackUrl: string;
   iframeContainerId: string;
 
   /**
@@ -64,7 +88,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * @param {string} params.rootOrgId The root organization ID
    */
   constructor(params: AlchemySignerClientParams) {
-    const { connection, iframeConfig, rpId, rootOrgId } =
+    const { connection, iframeConfig, rpId, rootOrgId, oauthCallbackUrl } =
       AlchemySignerClientParamsSchema.parse(params);
 
     const iframeStamper = new IframeStamper({
@@ -85,6 +109,8 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     this.webauthnStamper = new WebauthnStamper({
       rpId: rpId ?? window.location.hostname,
     });
+
+    this.oauthCallbackUrl = oauthCallbackUrl;
   }
 
   /**
@@ -109,9 +135,9 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * @param {CreateAccountParams} params The parameters for creating an account, including the type (email or passkey) and additional details.
    * @returns {Promise<SignupResponse>} A promise that resolves with the response object containing the account creation result.
    */
-  createAccount = async (params: CreateAccountParams) => {
-    this.eventEmitter.emit("authenticating");
+  public override createAccount = async (params: CreateAccountParams) => {
     if (params.type === "email") {
+      this.eventEmitter.emit("authenticating", { type: "email" });
       const { email, expirationSeconds } = params;
       const publicKey = await this.initIframeStamper();
 
@@ -125,6 +151,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
       return response;
     }
 
+    this.eventEmitter.emit("authenticating", { type: "passkey" });
     // Passkey account creation flow
     const { attestation, challenge } = await this.getWebAuthnAttestation(
       params.creationOpts,
@@ -174,10 +201,10 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * @param {Omit<EmailAuthParams, "targetPublicKey">} params The parameters for email authentication, excluding the target public key
    * @returns {Promise<any>} The response from the authentication request
    */
-  public initEmailAuth = async (
+  public override initEmailAuth = async (
     params: Omit<EmailAuthParams, "targetPublicKey">
   ) => {
-    this.eventEmitter.emit("authenticating");
+    this.eventEmitter.emit("authenticating", { type: "email" });
     const { email, expirationSeconds } = params;
     const publicKey = await this.initIframeStamper();
 
@@ -190,7 +217,9 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
   };
 
   /**
-   * Completes email auth for the user by injecting a credential bundle and retrieving the user information based on the provided organization ID. Emits events during the process.
+   * Completes auth for the user by injecting a credential bundle and retrieving
+   * the user information based on the provided organization ID. Emits events
+   * during the process.
    *
    * @example
    * ```ts
@@ -205,20 +234,31 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    *  },
    * });
    *
-   * const account = await client.completeEmailAuth({ orgId: "user-org-id", bundle: "bundle-from-email" });
+   * const account = await client.completeAuthWithBundle({ orgId: "user-org-id", bundle: "bundle-from-email", connectedEventName: "connectedEmail" });
    * ```
    *
-   * @param {{ bundle: string; orgId: string }} config The configuration object for the authentication function containing the credential bundle to inject and the organization id associated with the user
-   * @returns {Promise<User>} A promise that resolves to the authenticated user information
+   * @param {{ bundle: string; orgId: string, connectedEventName: keyof AlchemySignerClientEvents, idToken?: string }} config
+   * The configuration object for the authentication function containing the
+   * credential bundle to inject and the organization id associated with the
+   * user, as well as the event to be emitted on success and optionally an OIDC
+   * ID token with extra user information
+   * @returns {Promise<User>} A promise that resolves to the authenticated user
+   * information
    */
-  public completeEmailAuth = async ({
+  public override completeAuthWithBundle = async ({
     bundle,
     orgId,
+    connectedEventName,
+    idToken,
+    authenticatingType,
   }: {
     bundle: string;
     orgId: string;
-  }) => {
-    this.eventEmitter.emit("authenticating");
+    connectedEventName: keyof AlchemySignerClientEvents;
+    authenticatingType: AuthenticatingEventMetadata["type"];
+    idToken?: string;
+  }): Promise<User> => {
+    this.eventEmitter.emit("authenticating", { type: authenticatingType });
     await this.initIframeStamper();
 
     const result = await this.iframeStamper.injectCredentialBundle(bundle);
@@ -227,8 +267,9 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
       throw new Error("Failed to inject credential bundle");
     }
 
-    const user = await this.whoami(orgId);
-    this.eventEmitter.emit("connectedEmail", user, bundle);
+    const user = await this.whoami(orgId, idToken);
+
+    this.eventEmitter.emit(connectedEventName, user, bundle);
 
     return user;
   };
@@ -255,8 +296,10 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * @param {User} [user] An optional user object to authenticate
    * @returns {Promise<User>} A promise that resolves to the authenticated user object
    */
-  public lookupUserWithPasskey = async (user: User | undefined = undefined) => {
-    this.eventEmitter.emit("authenticating");
+  public override lookupUserWithPasskey = async (
+    user: User | undefined = undefined
+  ) => {
+    this.eventEmitter.emit("authenticating", { type: "passkey" });
     await this.initWebauthnStamper(user);
     if (user) {
       this.user = user;
@@ -297,7 +340,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * @param {string} [config.iframeElementId] Optional ID for the iframe element
    * @returns {Promise<void>} A promise that resolves when the export process is complete
    */
-  public exportWallet = async ({
+  public override exportWallet = async ({
     iframeContainerId,
     iframeElementId = "turnkey-export-iframe",
   }: ExportWalletParams) => {
@@ -340,9 +383,202 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    * const account = await client.disconnect();
    * ```
    */
-  public disconnect = async () => {
+  public override disconnect = async () => {
     this.user = undefined;
     this.iframeStamper.clear();
+    await this.iframeStamper.init();
+  };
+
+  /**
+   * Redirects the user to the OAuth provider URL based on the provided arguments. This function will always reject after 1 second if the redirection does not occur.
+   *
+   * @example
+   * ```ts
+   * import { AlchemySignerWebClient } from "@account-kit/signer";
+   *
+   * const client = new AlchemySignerWebClient({
+   *  connection: {
+   *    apiKey: "your-api-key",
+   *  },
+   *  iframeConfig: {
+   *   iframeContainerId: "signer-iframe-container",
+   *  },
+   * });
+   *
+   * await client.oauthWithRedirect({
+   *   type: "oauth",
+   *   authProviderId: "google",
+   *   mode: "redirect",
+   *   redirectUrl: "/",
+   * });
+   * ```
+   *
+   * @param {Extract<AuthParams, { type: "oauth"; mode: "redirect" }>} args The arguments required to obtain the OAuth provider URL
+   * @returns {Promise<never>} A promise that will never resolve, only reject if the redirection fails
+   */
+  public override oauthWithRedirect = async (
+    args: Extract<AuthParams, { type: "oauth"; mode: "redirect" }>
+  ): Promise<never> => {
+    const providerUrl = await this.getOauthProviderUrl(args);
+    window.location.href = providerUrl;
+    return new Promise((_, reject) =>
+      setTimeout(() => reject("Failed to redirect to OAuth provider"), 1000)
+    );
+  };
+
+  /**
+   * Initiates an OAuth authentication flow in a popup window and returns the authenticated user.
+   *
+   * @example
+   * ```ts
+   * import { AlchemySignerWebClient } from "@account-kit/signer";
+   *
+   * const client = new AlchemySignerWebClient({
+   *  connection: {
+   *    apiKey: "your-api-key",
+   *  },
+   *  iframeConfig: {
+   *   iframeContainerId: "signer-iframe-container",
+   *  },
+   * });
+   *
+   * const user = await client.oauthWithPopup({
+   *  type: "oauth",
+   *  authProviderId: "google",
+   *  mode: "popup"
+   * });
+   * ```
+   *
+   * @param {Extract<AuthParams, { type: "oauth"; mode: "popup" }>} args The authentication parameters specifying OAuth type and popup mode
+   * @returns {Promise<User>} A promise that resolves to a `User` object containing the authenticated user information
+   */
+  public override oauthWithPopup = async (
+    args: Extract<AuthParams, { type: "oauth"; mode: "popup" }>
+  ): Promise<User> => {
+    const providerUrl = await this.getOauthProviderUrl(args);
+    const popup = window.open(
+      providerUrl,
+      "_blank",
+      "popup,width=500,height=600"
+    );
+    return new Promise((resolve, reject) => {
+      const handleMessage = (event: MessageEvent) => {
+        if (!event.data) {
+          return;
+        }
+        const {
+          alchemyBundle: bundle,
+          alchemyOrgId: orgId,
+          alchemyIdToken: idToken,
+          alchemyError,
+        } = event.data;
+        if (bundle && orgId && idToken) {
+          cleanup();
+          popup?.close();
+          this.completeAuthWithBundle({
+            bundle,
+            orgId,
+            connectedEventName: "connectedOauth",
+            idToken,
+            authenticatingType: "oauth",
+          }).then(resolve, reject);
+        } else if (alchemyError) {
+          cleanup();
+          popup?.close();
+          reject(new OauthFailedError(alchemyError));
+        }
+      };
+
+      window.addEventListener("message", handleMessage);
+
+      const checkCloseIntervalId = setInterval(() => {
+        if (popup?.closed) {
+          cleanup();
+          reject(new OauthCancelledError());
+        }
+      }, CHECK_CLOSE_INTERVAL);
+
+      const cleanup = () => {
+        window.removeEventListener("message", handleMessage);
+        clearInterval(checkCloseIntervalId);
+      };
+    });
+  };
+
+  private getOauthProviderUrl = async (args: OauthParams): Promise<string> => {
+    const {
+      authProviderId,
+      isCustomProvider,
+      auth0Connection,
+      scope: providedScope,
+      claims: providedClaims,
+      mode,
+      redirectUrl,
+      expirationSeconds,
+    } = args;
+    const { codeChallenge, requestKey, authProviders } =
+      await this.getOauthConfigForMode(mode);
+    const authProvider = authProviders.find(
+      (provider) =>
+        provider.id === authProviderId &&
+        !!provider.isCustomProvider === !!isCustomProvider
+    );
+    if (!authProvider) {
+      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);
+    }
+    const { authEndpoint, clientId } = authProvider;
+    const turnkeyPublicKey = await this.initIframeStamper();
+    const nonce = getOauthNonce(turnkeyPublicKey);
+    const stateObject: OauthState = {
+      authProviderId,
+      isCustomProvider,
+      requestKey,
+      turnkeyPublicKey,
+      expirationSeconds,
+      redirectUrl:
+        mode === "redirect" ? resolveRelativeUrl(redirectUrl) : undefined,
+      openerOrigin: mode === "popup" ? window.location.origin : undefined,
+    };
+    const state = base64UrlEncode(
+      new TextEncoder().encode(JSON.stringify(stateObject))
+    );
+    const authUrl = new URL(authEndpoint);
+    const params: Record<string, string> = {
+      redirect_uri: this.oauthCallbackUrl,
+      response_type: "code",
+      scope,
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      prompt: "select_account",
+      client_id: clientId,
+      nonce,
+    };
+    if (claims) {
+      params.claims = claims;
+    }
+    if (auth0Connection) {
+      params.connection = auth0Connection;
+    }
+    authUrl.search = new URLSearchParams(params).toString();
+    return authUrl.toString();
   };
 
   private initIframeStamper = async () => {
@@ -369,7 +605,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     }
   };
 
-  protected getWebAuthnAttestation = async (
+  protected override getWebAuthnAttestation = async (
     options?: CredentialCreationOptionOverrides,
     userDetails: { username: string } = {
       username: this.user?.email ?? "anonymous",
@@ -423,4 +659,65 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
 
     return { challenge, authenticatorUserId, attestation };
   };
+
+  protected override getOauthConfig = async (): Promise<OauthConfig> => {
+    const publicKey = await this.initIframeStamper();
+    const nonce = getOauthNonce(publicKey);
+    return this.request("/v1/prepare-oauth", { nonce });
+  };
+
+  private getOauthConfigForMode = async (
+    mode: OauthMode
+  ): Promise<OauthConfig> => {
+    if (this.oauthConfig) {
+      return this.oauthConfig;
+    } else if (mode === "redirect") {
+      return this.initOauth();
+    } else {
+      throw new Error(
+        "enablePopupOauth must be set in configuration or signer.preparePopupOauth must be called before using popup-based OAuth login"
+      );
+    }
+  };
+}
+
+function resolveRelativeUrl(url: string): string {
+  // Funny trick.
+  const a = document.createElement("a");
+  a.href = url;
+  return a.href;
+}
+
+/**
+ * "openid" is a required scope in the OIDC protocol. Insert it if the user
+ * forgot.
+ *
+ * @param {string} scope scope param which may be missing "openid"
+ * @returns {string} scope which most definitely contains "openid"
+ */
+function addOpenIdIfAbsent(scope: string): string {
+  return scope.match(/\bopenid\b/) ? scope : `openid ${scope}`;
+}
+
+/**
+ * This error is thrown when the OAuth flow is cancelled because the auth popup
+ * window was closed.
+ */
+export class OauthCancelledError extends BaseError {
+  override name = "OauthCancelledError";
+
+  /**
+   * Constructor for initializing an error indicating that the OAuth flow was
+   * cancelled.
+   */
+  constructor() {
+    super("OAuth cancelled");
+  }
+}
+
+/**
+ * This error is thrown when an error occurs during the OAuth login flow.
+ */
+export class OauthFailedError extends BaseError {
+  override name = "OauthFailedError";
 }

package/src/client/types.ts

@@ -1,6 +1,7 @@
 import type { Address } from "@aa-sdk/core";
 import type { TSignedRequest, getWebAuthnAttestation } from "@turnkey/http";
 import type { Hex } from "viem";
+import type { AuthParams } from "../signer";
 
 export type CredentialCreationOptionOverrides = {
   publicKey?: Partial<CredentialCreationOptions["publicKey"]>;
@@ -13,6 +14,8 @@ export type User = {
   userId: string;
   address: Address;
   credentialId?: string;
+  idToken?: string;
+  claims?: Record<string, unknown>;
 };
 // [!endregion User]
 
@@ -46,12 +49,29 @@ export type EmailAuthParams = {
   redirectParams?: URLSearchParams;
 };
 
+export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
+  expirationSeconds?: number;
+};
+
 export type SignupResponse = {
   orgId: string;
   userId?: string;
   address?: Address;
 };
 
+export type OauthConfig = {
+  codeChallenge: string;
+  requestKey: string;
+  authProviders: AuthProviderConfig[];
+};
+
+export type AuthProviderConfig = {
+  id: string;
+  isCustomProvider?: boolean;
+  clientId: string;
+  authEndpoint: string;
+};
+
 export type SignerRoutes = SignerEndpoints[number]["Route"];
 export type SignerBody<T extends SignerRoutes> = Extract<
   SignerEndpoints[number],
@@ -106,14 +126,26 @@ export type SignerEndpoints = [
     Response: {
       signature: Hex;
     };
+  },
+  {
+    Route: "/v1/prepare-oauth";
+    Body: {
+      nonce: string;
+    };
+    Response: OauthConfig;
   }
 ];
 
+export type AuthenticatingEventMetadata = {
+  type: "email" | "passkey" | "oauth";
+};
+
 export type AlchemySignerClientEvents = {
   connected(user: User): void;
-  authenticating(): void;
+  authenticating(data: AuthenticatingEventMetadata): void;
   connectedEmail(user: User, bundle: string): void;
   connectedPasskey(user: User): void;
+  connectedOauth(user: User, bundle: string): void;
   disconnected(): void;
 };
 

package/src/index.ts

@@ -1,6 +1,10 @@
 export { BaseAlchemySigner } from "./base.js";
 export { BaseSignerClient } from "./client/base.js";
-export { AlchemySignerWebClient } from "./client/index.js";
+export {
+  AlchemySignerWebClient,
+  OauthCancelledError,
+  OauthFailedError,
+} from "./client/index.js";
 export type * from "./client/types.js";
 export { DEFAULT_SESSION_MS } from "./session/manager.js";
 export type * from "./signer.js";

package/src/metrics.ts

@@ -0,0 +1,23 @@
+import { createLogger } from "@account-kit/logging";
+import { VERSION } from "./version.js";
+
+export type SignerEventsSchema = [
+  {
+    EventName: "signer_authnticate";
+    EventData:
+      | {
+          authType: "email" | "passkey_anon" | "passkey_email" | "oauthReturn";
+          provider?: never;
+        }
+      | { authType: "oauth"; provider: string };
+  },
+  {
+    EventName: "signer_sign_message";
+    EventData: undefined;
+  }
+];
+
+export const SignerLogger = createLogger<SignerEventsSchema>({
+  package: "@account-kit/signer",
+  version: VERSION,
+});

package/src/oauth.ts

@@ -0,0 +1,36 @@
+import { sha256 } from "viem";
+import type { KnownAuthProvider } from "./signer";
+
+/**
+ * Turnkey requires the nonce in the id token to be in this format.
+ *
+ * @param {string} turnkeyPublicKey key from a Turnkey iframe
+ * @returns {string} nonce to be used in OIDC
+ */
+export function getOauthNonce(turnkeyPublicKey: string): string {
+  return sha256(new TextEncoder().encode(turnkeyPublicKey)).slice(2);
+}
+
+export type ScopeAndClaims = {
+  scope: string;
+  claims?: string;
+};
+
+const DEFAULT_SCOPE_AND_CLAIMS: Record<KnownAuthProvider, ScopeAndClaims> = {
+  google: { scope: "openid email" },
+  apple: { scope: "openid email" },
+  facebook: { scope: "openid email" },
+  auth0: { scope: "openid email" },
+};
+
+/**
+ * Returns the default scope and claims 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
+ */
+export function getDefaultScopeAndClaims(
+  knownAuthProviderId: KnownAuthProvider
+): ScopeAndClaims | undefined {
+  return DEFAULT_SCOPE_AND_CLAIMS[knownAuthProviderId];
+}