@aztec/wallet-sdk 0.0.1-commit.0208eb9

package/src/manager/types.ts

@@ -0,0 +1,177 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+
+/**
+ * A pending connection that requires user verification before finalizing.
+ *
+ * After key exchange, both dApp and wallet compute a verification hash independently.
+ * The dApp should display this hash (typically as emojis) and let the user confirm
+ * it matches what's shown in their wallet before calling `confirm()`.
+ *
+ * This protects the dApp from connecting to a malicious wallet that might be
+ * intercepting the connection (MITM attack).
+ */
+export interface PendingConnection {
+  /**
+   * The verification hash computed from the shared secret.
+   * Use `hashToEmoji()` to convert to a visual representation for user verification.
+   * The user should confirm this matches what their wallet displays.
+   */
+  verificationHash: string;
+
+  /**
+   * Confirms the connection after user verifies the emojis match.
+   * @returns The connected wallet instance
+   */
+  confirm(): Promise<Wallet>;
+
+  /**
+   * Cancels the pending connection.
+   * Call this if the user indicates the emojis don't match.
+   */
+  cancel(): void;
+}
+
+/**
+ * Configuration for extension wallets
+ */
+export interface ExtensionWalletConfig {
+  /** Whether extension wallets are enabled */
+  enabled: boolean;
+  /** Optional list of allowed extension IDs (whitelist) */
+  allowList?: string[];
+  /** Optional list of blocked extension IDs (blacklist) */
+  blockList?: string[];
+}
+
+/**
+ * Configuration for web wallets
+ */
+export interface WebWalletConfig {
+  /** URLs of web wallet services */
+  urls: string[];
+}
+
+/**
+ * Configuration for the WalletManager
+ */
+export interface WalletManagerConfig {
+  /** Extension wallet configuration */
+  extensions?: ExtensionWalletConfig;
+  /** Web wallet configuration */
+  webWallets?: WebWalletConfig;
+}
+
+/**
+ * Type of wallet provider
+ */
+export type WalletProviderType = 'extension' | 'web';
+
+/**
+ * Callback type for wallet disconnect events at the provider level.
+ */
+export type ProviderDisconnectionCallback = () => void;
+
+/**
+ * A wallet provider that can connect to create a wallet instance.
+ * Chain information is already baked in from the discovery process.
+ */
+export interface WalletProvider {
+  /** Unique identifier for the provider */
+  id: string;
+  /** Type of wallet provider */
+  type: WalletProviderType;
+  /** Display name */
+  name: string;
+  /** Icon URL */
+  icon?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+  /**
+   * Establishes a secure channel with this wallet provider.
+   *
+   * This performs the ECDH key exchange and returns a pending connection with the
+   * verification hash. The channel is encrypted but NOT yet verified - the dApp
+   * should display the hash (as emojis) to the user and let them confirm it
+   * matches their wallet before calling `confirm()`.
+   *
+   * @param appId - Application identifier for the requesting dapp
+   * @returns A pending connection with verification hash and confirm/cancel methods
+   *
+   * @example
+   * ```typescript
+   * const pending = await provider.establishSecureChannel('my-app');
+   *
+   * // Show emojis to user for verification
+   * const emojis = hashToEmoji(pending.verificationHash);
+   * showDialog(`Verify these match your wallet: ${emojis}`);
+   *
+   * // User confirms emojis match
+   * const wallet = await pending.confirm();
+   * ```
+   */
+  establishSecureChannel(appId: string): Promise<PendingConnection>;
+  /**
+   * Disconnects the current wallet and cleans up resources.
+   * After calling this, the wallet returned from confirm() should no longer be used.
+   * @returns A promise that resolves when disconnection is complete
+   */
+  disconnect?(): Promise<void>;
+  /**
+   * Registers a callback to be invoked when the wallet disconnects unexpectedly.
+   * @param callback - Function to call when wallet disconnects
+   * @returns A function to unregister the callback
+   */
+  onDisconnect?(callback: ProviderDisconnectionCallback): () => void;
+  /**
+   * Returns whether the provider's wallet connection has been disconnected.
+   * @returns true if the wallet is no longer connected
+   */
+  isDisconnected?(): boolean;
+}
+
+/**
+ * Options for discovering wallets
+ */
+export interface DiscoverWalletsOptions {
+  /** Chain information to filter by */
+  chainInfo: ChainInfo;
+  /** Application ID making the request */
+  appId: string;
+  /** Discovery timeout in milliseconds. Default: 60000 (60s) */
+  timeout?: number;
+  /**
+   * Callback invoked when a wallet provider is discovered.
+   * Use this to show wallets to users as they approve them, rather than
+   * waiting for the full timeout.
+   */
+  onWalletDiscovered?: (provider: WalletProvider) => void;
+}
+
+/**
+ * A cancellable discovery session.
+ *
+ * Returned by `WalletManager.getAvailableWallets()` to allow consumers to
+ * cancel discovery when no longer needed (e.g., network changes, user navigates away).
+ *
+ * @example
+ * ```typescript
+ * const discovery = WalletManager.configure({...}).getAvailableWallets({...});
+ *
+ * // Iterate over discovered wallets
+ * for await (const wallet of discovery.wallets) {
+ *   console.log(`Found: ${wallet.name}`);
+ * }
+ *
+ * // Cancel discovery when no longer needed
+ * discovery.cancel();
+ * ```
+ */
+export interface DiscoverySession {
+  /** Async iterator that yields wallet providers as they're discovered */
+  wallets: AsyncIterable<WalletProvider>;
+  /** Promise that resolves when discovery completes or is cancelled */
+  done: Promise<void>;
+  /** Cancel discovery immediately and clean up resources */
+  cancel: () => void;
+}

package/src/manager/wallet_manager.ts

@@ -0,0 +1,259 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+
+import { type DiscoveredWallet, ExtensionProvider, ExtensionWallet } from '../extension/provider/index.js';
+import { WalletMessageType } from '../types.js';
+import type {
+  DiscoverWalletsOptions,
+  DiscoverySession,
+  ExtensionWalletConfig,
+  PendingConnection,
+  ProviderDisconnectionCallback,
+  WalletManagerConfig,
+  WalletProvider,
+} from './types.js';
+
+/**
+ * Manager for wallet discovery, configuration, and connection.
+ *
+ * This is the main entry point for dApps to discover and connect to wallets.
+ *
+ * @example Basic usage with async iterator
+ * ```typescript
+ * const discovery = WalletManager.configure({ extensions: { enabled: true } })
+ *   .getAvailableWallets({ chainInfo, appId: 'my-app' });
+ *
+ * // Iterate over discovered wallets
+ * for await (const provider of discovery.wallets) {
+ *   console.log(`Found wallet: ${provider.name}`);
+ * }
+ *
+ * // Or cancel early when done
+ * discovery.cancel();
+ * ```
+ *
+ * @example With callback for discovered wallets
+ * ```typescript
+ * const discovery = manager.getAvailableWallets({
+ *   chainInfo,
+ *   appId: 'my-app',
+ *   onWalletDiscovered: (provider) => console.log(`Found: ${provider.name}`),
+ * });
+ *
+ * // Wait for discovery to complete or cancel it
+ * await discovery.done;
+ * ```
+ */
+export class WalletManager {
+  private config: WalletManagerConfig = {
+    extensions: { enabled: true },
+    webWallets: { urls: [] },
+  };
+
+  private constructor() {}
+
+  /**
+   * Configures the WalletManager with provider settings
+   * @param config - Configuration options for wallet providers
+   */
+  static configure(config: WalletManagerConfig): WalletManager {
+    const instance = new WalletManager();
+    instance.config = {
+      extensions: config.extensions ?? { enabled: true },
+      webWallets: config.webWallets ?? { urls: [] },
+    };
+    return instance;
+  }
+
+  /**
+   * Discovers all available wallets for a given chain and version.
+   *
+   * Returns a `DiscoverySession` with:
+   * - `wallets`: AsyncIterable to iterate over discovered wallets
+   * - `done`: Promise that resolves when discovery completes or is cancelled
+   * - `cancel()`: Function to stop discovery immediately
+   *
+   * If `onWalletDiscovered` callback is provided, wallets are also streamed via callback.
+   *
+   * @param options - Discovery options including chain info, appId, and timeout
+   * @returns A cancellable discovery session
+   */
+  getAvailableWallets(options: DiscoverWalletsOptions): DiscoverySession {
+    const { chainInfo, appId } = options;
+    const abortController = new AbortController();
+
+    const pendingProviders: WalletProvider[] = [];
+    let pendingResolve: ((result: IteratorResult<WalletProvider>) => void) | null = null;
+    let completed = false;
+
+    const { promise: donePromise, resolve: resolveDone } = promiseWithResolvers<void>();
+
+    const markComplete = () => {
+      completed = true;
+      resolveDone();
+      if (pendingResolve) {
+        const resolve = pendingResolve;
+        pendingResolve = null;
+        resolve({ value: undefined, done: true });
+      }
+    };
+
+    if (this.config.extensions?.enabled) {
+      const extensionConfig = this.config.extensions;
+
+      void ExtensionProvider.discoverWallets(chainInfo, {
+        appId,
+        timeout: options.timeout,
+        signal: abortController.signal,
+        onWalletDiscovered: discoveredWallet => {
+          const provider = this.createProviderFromDiscoveredWallet(discoveredWallet, chainInfo, extensionConfig);
+          if (!provider) {
+            return;
+          }
+
+          // Call user's callback if provided
+          options.onWalletDiscovered?.(provider);
+
+          // Also queue for async iterator
+          if (pendingResolve) {
+            const resolve = pendingResolve;
+            pendingResolve = null;
+            resolve({ value: provider, done: false });
+          } else {
+            pendingProviders.push(provider);
+          }
+        },
+      }).then(markComplete);
+    } else {
+      markComplete();
+    }
+
+    const wallets: AsyncIterable<WalletProvider> = {
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      [Symbol.asyncIterator](): AsyncIterator<WalletProvider> {
+        return {
+          // eslint-disable-next-line jsdoc/require-jsdoc
+          next(): Promise<IteratorResult<WalletProvider>> {
+            if (pendingProviders.length > 0) {
+              return Promise.resolve({ value: pendingProviders.shift()!, done: false });
+            }
+
+            if (completed) {
+              return Promise.resolve({ value: undefined, done: true });
+            }
+
+            return new Promise(resolve => {
+              pendingResolve = resolve;
+            });
+          },
+        };
+      },
+    };
+
+    return {
+      wallets,
+      done: donePromise,
+      cancel: () => abortController.abort(),
+    };
+  }
+
+  /**
+   * Creates a WalletProvider from a discovered wallet.
+   * Returns null if the wallet is not allowed by config.
+   * @param discoveredWallet - The discovered wallet from extension discovery.
+   * @param chainInfo - Network information.
+   * @param extensionConfig - Extension wallet configuration.
+   */
+  private createProviderFromDiscoveredWallet(
+    discoveredWallet: DiscoveredWallet,
+    chainInfo: ChainInfo,
+    extensionConfig: ExtensionWalletConfig,
+  ): WalletProvider | null {
+    const { info } = discoveredWallet;
+
+    if (!this.isExtensionAllowed(info.id, extensionConfig)) {
+      return null;
+    }
+
+    let extensionWallet: ExtensionWallet | null = null;
+
+    const provider: WalletProvider = {
+      id: info.id,
+      type: 'extension',
+      name: info.name,
+      icon: info.icon,
+      metadata: {
+        version: info.version,
+      },
+      establishSecureChannel: async (connectAppId: string): Promise<PendingConnection> => {
+        const connection = await discoveredWallet.establishSecureChannel();
+
+        provider.metadata = {
+          ...provider.metadata,
+          verificationHash: connection.info.verificationHash,
+        };
+
+        return {
+          verificationHash: connection.info.verificationHash!,
+          confirm: () => {
+            return Promise.resolve(
+              ExtensionWallet.create(
+                connection.info.id,
+                connection.port,
+                connection.sharedKey,
+                chainInfo,
+                connectAppId,
+              ),
+            );
+          },
+          cancel: () => {
+            // Send disconnect to terminate the session on the extension side
+            // but keep the port open so we can retry key exchange
+            connection.port.postMessage({
+              type: WalletMessageType.DISCONNECT,
+              requestId: discoveredWallet.requestId,
+            });
+            // Don't close the port - allow retry with fresh key exchange
+          },
+        };
+      },
+      disconnect: async () => {
+        if (extensionWallet) {
+          await extensionWallet.disconnect();
+          extensionWallet = null;
+        }
+      },
+      onDisconnect: (callback: ProviderDisconnectionCallback) => {
+        if (extensionWallet) {
+          return extensionWallet.onDisconnect(callback);
+        }
+        return () => {};
+      },
+      isDisconnected: () => {
+        if (extensionWallet) {
+          return extensionWallet.isDisconnected();
+        }
+        return true;
+      },
+    };
+
+    return provider;
+  }
+
+  /**
+   * Checks if an extension is allowed based on allow/block lists
+   * @param extensionId - The extension ID to check
+   * @param config - Extension wallet configuration containing allow/block lists
+   */
+  private isExtensionAllowed(extensionId: string, config: ExtensionWalletConfig): boolean {
+    if (config.blockList && config.blockList.includes(extensionId)) {
+      return false;
+    }
+
+    if (config.allowList && config.allowList.length > 0) {
+      return config.allowList.includes(extensionId);
+    }
+
+    return true;
+  }
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+
+import type { ExportedPublicKey } from './crypto.js';
+
+/**
+ * Message types for wallet SDK communication.
+ * All types are prefixed with 'aztec-wallet-' for namespacing.
+ */
+export enum WalletMessageType {
+  /** Discovery request to find installed wallets */
+  DISCOVERY = 'aztec-wallet-discovery',
+  /** Discovery response from a wallet */
+  DISCOVERY_RESPONSE = 'aztec-wallet-discovery-response',
+  /** Disconnect message (unencrypted control message, bidirectional) */
+  DISCONNECT = 'aztec-wallet-disconnect',
+  /** Key exchange request sent over MessageChannel */
+  KEY_EXCHANGE_REQUEST = 'aztec-wallet-key-exchange-request',
+  /** Key exchange response sent over MessageChannel */
+  KEY_EXCHANGE_RESPONSE = 'aztec-wallet-key-exchange-response',
+}
+
+/**
+ * Information about an installed Aztec wallet.
+ * Used during discovery phase before key exchange.
+ */
+export interface WalletInfo {
+  /** Unique identifier for the wallet */
+  id: string;
+  /** Display name of the wallet */
+  name: string;
+  /** URL to the wallet's icon */
+  icon?: string;
+  /** Wallet version */
+  version: string;
+}
+
+/**
+ * Full information about a connected Aztec wallet including crypto material.
+ * Available after key exchange completes.
+ */
+export interface ConnectedWalletInfo extends WalletInfo {
+  /** Wallet's ECDH public key for secure channel establishment */
+  publicKey: ExportedPublicKey;
+  /**
+   * Verification hash for verification.
+   * Both dApp and wallet independently compute this from the ECDH shared secret.
+   * Use {@link hashToEmoji} to convert to a visual representation for user verification.
+   */
+  verificationHash?: string;
+}
+
+/**
+ * Message format for wallet communication (internal, before encryption)
+ */
+export interface WalletMessage {
+  /** Unique message ID for tracking responses */
+  messageId: string;
+  /** The wallet method to call */
+  type: string;
+  /** Arguments for the method */
+  args: unknown[];
+  /** Chain information */
+  chainInfo: ChainInfo;
+  /** Application ID making the request */
+  appId: string;
+  /** Wallet ID to target a specific wallet */
+  walletId: string;
+}
+
+/**
+ * Response message from wallet
+ */
+export interface WalletResponse {
+  /** Message ID matching the request */
+  messageId: string;
+  /** Result data (if successful) */
+  result?: unknown;
+  /** Error data (if failed) */
+  error?: unknown;
+  /** Wallet ID that sent the response */
+  walletId: string;
+}
+
+/**
+ * Discovery message for finding installed wallets (public, unencrypted).
+ */
+export interface DiscoveryRequest {
+  /** Message type for discovery */
+  type: WalletMessageType.DISCOVERY;
+  /** Request ID */
+  requestId: string;
+  /** Application ID making the request */
+  appId: string;
+  /** Chain information to check if wallet supports this network */
+  chainInfo: ChainInfo;
+}
+
+/**
+ * Discovery response from a wallet (public, unencrypted).
+ */
+export interface DiscoveryResponse {
+  /** Message type for discovery response */
+  type: WalletMessageType.DISCOVERY_RESPONSE;
+  /** Request ID matching the discovery request */
+  requestId: string;
+  /** Basic wallet information */
+  walletInfo: WalletInfo;
+}
+
+/**
+ * Key exchange request sent over MessageChannel after discovery approval.
+ */
+export interface KeyExchangeRequest {
+  /** Message type */
+  type: WalletMessageType.KEY_EXCHANGE_REQUEST;
+  /** Request ID matching the discovery request */
+  requestId: string;
+  /** dApp's ECDH public key for deriving shared secret */
+  publicKey: ExportedPublicKey;
+}
+
+/**
+ * Key exchange response sent over MessageChannel.
+ */
+export interface KeyExchangeResponse {
+  /** Message type */
+  type: WalletMessageType.KEY_EXCHANGE_RESPONSE;
+  /** Request ID matching the discovery request */
+  requestId: string;
+  /** Wallet's ECDH public key for deriving shared secret */
+  publicKey: ExportedPublicKey;
+}