@aztec/wallet-sdk 0.0.1-commit.f295ac2 → 0.0.1-commit.fc805bf

package/src/manager/types.ts

@@ -1,6 +1,37 @@
 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
  */
@@ -34,7 +65,7 @@ export interface WalletManagerConfig {
 /**
  * Type of wallet provider
  */
-export type WalletProviderType = 'extension' | 'web' | 'embedded';
+export type WalletProviderType = 'extension' | 'web';
 
 /**
  * Callback type for wallet disconnect events at the provider level.
@@ -57,13 +88,32 @@ export interface WalletProvider {
   /** Additional metadata */
   metadata?: Record<string, unknown>;
   /**
-   * Connect to this wallet provider with an application ID
+   * 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();
+   * ```
    */
-  connect(appId: string): Promise<Wallet>;
+  establishSecureChannel(appId: string): Promise<PendingConnection>;
   /**
    * Disconnects the current wallet and cleans up resources.
-   * After calling this, the wallet returned from connect() should no longer be used.
+   * 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>;
@@ -86,6 +136,42 @@ export interface WalletProvider {
 export interface DiscoverWalletsOptions {
   /** Chain information to filter by */
   chainInfo: ChainInfo;
-  /** Discovery timeout in milliseconds */
+  /** 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

@@ -1,14 +1,48 @@
-import { ExtensionProvider, ExtensionWallet } from '../providers/extension/index.js';
+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
+ * 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 = {
@@ -33,65 +67,177 @@ export class WalletManager {
 
   /**
    * Discovers all available wallets for a given chain and version.
-   * Only returns wallets that support the requested chain and version.
-   * @param options - Discovery options including chain info and timeout
-   * @returns Array of wallet providers with baked-in chain info
+   *
+   * 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
    */
-  async getAvailableWallets(options: DiscoverWalletsOptions): Promise<WalletProvider[]> {
-    const providers: WalletProvider[] = [];
-    const { chainInfo } = options;
+  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 discoveredWallets = await ExtensionProvider.discoverExtensions(chainInfo, options.timeout);
       const extensionConfig = this.config.extensions;
 
-      for (const { info, port, sharedKey } of discoveredWallets) {
-        if (!this.isExtensionAllowed(info.id, extensionConfig)) {
-          continue;
-        }
+      void ExtensionProvider.discoverWallets(chainInfo, {
+        appId,
+        timeout: options.timeout,
+        signal: abortController.signal,
+        onWalletDiscovered: discoveredWallet => {
+          const provider = this.createProviderFromDiscoveredWallet(discoveredWallet, chainInfo, extensionConfig);
+          if (!provider) {
+            return;
+          }
 
-        let extensionWallet: ExtensionWallet | null = null;
+          // Call user's callback if provided
+          options.onWalletDiscovered?.(provider);
 
-        const provider: WalletProvider = {
-          id: info.id,
-          type: 'extension',
-          name: info.name,
-          icon: info.icon,
-          metadata: {
-            version: info.version,
-            verificationHash: info.verificationHash,
-          },
-          connect: (appId: string) => {
-            extensionWallet = ExtensionWallet.create(info, chainInfo, port, sharedKey, appId);
-            return Promise.resolve(extensionWallet.getWallet());
-          },
-          disconnect: async () => {
-            if (extensionWallet) {
-              await extensionWallet.disconnect();
-              extensionWallet = null;
-            }
-          },
-          onDisconnect: (callback: ProviderDisconnectionCallback) => {
-            if (extensionWallet) {
-              return extensionWallet.onDisconnect(callback);
+          // 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 });
             }
-            return () => {};
-          },
-          isDisconnected: () => {
-            if (extensionWallet) {
-              return extensionWallet.isDisconnected();
+
+            if (completed) {
+              return Promise.resolve({ value: undefined, done: true });
             }
-            return true;
+
+            return new Promise(resolve => {
+              pendingResolve = resolve;
+            });
           },
         };
+      },
+    };
 
-        providers.push(provider);
-      }
+    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;
     }
 
-    // TODO: Add web wallet discovery when implemented
+    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 providers;
+    return provider;
   }
 
   /**

package/src/types.ts

@@ -11,14 +11,17 @@ export enum WalletMessageType {
   DISCOVERY = 'aztec-wallet-discovery',
   /** Discovery response from a wallet */
   DISCOVERY_RESPONSE = 'aztec-wallet-discovery-response',
-  /** Session disconnected notification (unencrypted control message) */
-  SESSION_DISCONNECTED = 'aztec-wallet-session-disconnected',
-  /** Explicit disconnect request from dApp */
+  /** 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
+ * Information about an installed Aztec wallet.
+ * Used during discovery phase before key exchange.
  */
 export interface WalletInfo {
   /** Unique identifier for the wallet */
@@ -29,10 +32,17 @@ export interface WalletInfo {
   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;
   /**
-   * Hash of the shared secret for anti-MITM verification.
+   * 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.
    */
@@ -72,27 +82,51 @@ export interface WalletResponse {
 }
 
 /**
- * Discovery message for finding installed wallets (public, unencrypted)
+ * 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;
-  /** dApp's ECDH public key for deriving shared secret */
-  publicKey: ExportedPublicKey;
 }
 
 /**
- * Discovery response from a wallet (public, unencrypted)
+ * 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;
-  /** Wallet information */
+  /** 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;
+}

package/dest/providers/extension/extension_provider.d.ts

@@ -1,63 +0,0 @@
-import type { ChainInfo } from '@aztec/aztec.js/account';
-import { type WalletInfo } from '../../types.js';
-/**
- * A discovered wallet with its secure channel components.
- * Returned by {@link ExtensionProvider.discoverExtensions}.
- */
-export interface DiscoveredWallet {
-    /** Basic wallet information (id, name, icon, version, publicKey, verificationHash) */
-    info: WalletInfo;
-    /** The MessagePort for private communication with the wallet */
-    port: MessagePort;
-    /** The derived AES-256-GCM shared key for encryption */
-    sharedKey: CryptoKey;
-}
-/**
- * Provider for discovering Aztec wallet extensions.
- *
- * This class handles the discovery phase of wallet communication:
- * 1. Broadcasts a discovery request with the dApp's public key
- * 2. Receives responses from installed wallets with their public keys
- * 3. Derives shared secrets and computes verification hashes
- * 4. Returns discovered wallets with their secure channel components
- *
- * @example
- * ```typescript
- * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
- * // Display wallets to user with optional emoji verification
- * for (const wallet of wallets) {
- *   const emoji = hashToEmoji(wallet.info.verificationHash!);
- *   console.log(`${wallet.info.name}: ${emoji}`);
- * }
- * // User selects a wallet after verifying
- * const wallet = await ExtensionWallet.create(wallets[0], chainInfo, 'my-app');
- * ```
- */
-export declare class ExtensionProvider {
-    private static discoveryInProgress;
-    /**
-     * Discovers all installed Aztec wallet extensions and establishes secure channel components.
-     *
-     * This method:
-     * 1. Generates an ECDH key pair for this discovery session
-     * 2. Broadcasts a discovery request with the dApp's public key
-     * 3. Receives responses from wallets with their public keys and MessagePorts
-     * 4. Derives shared secrets and computes verification hashes
-     *
-     * @param chainInfo - Chain information to check if extensions support this network
-     * @param timeout - How long to wait for extensions to respond (ms)
-     * @returns Array of discovered wallets with their secure channel components
-     *
-     * @example
-     * ```typescript
-     * const wallets = await ExtensionProvider.discoverExtensions({
-     *   chainId: Fr(31337),
-     *   version: Fr(0)
-     * });
-     * // Access wallet info and secure channel
-     * const { info, port, sharedKey } = wallets[0];
-     * ```
-     */
-    static discoverExtensions(chainInfo: ChainInfo, timeout?: number): Promise<DiscoveredWallet[]>;
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3Byb3ZpZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHJvdmlkZXJzL2V4dGVuc2lvbi9leHRlbnNpb25fcHJvdmlkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFLekQsT0FBTyxFQUFpRCxLQUFLLFVBQVUsRUFBcUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUVuSDs7O0dBR0c7QUFDSCxNQUFNLFdBQVcsZ0JBQWdCO0lBQy9CLHNGQUFzRjtJQUN0RixJQUFJLEVBQUUsVUFBVSxDQUFDO0lBQ2pCLGdFQUFnRTtJQUNoRSxJQUFJLEVBQUUsV0FBVyxDQUFDO0lBQ2xCLHdEQUF3RDtJQUN4RCxTQUFTLEVBQUUsU0FBUyxDQUFDO0NBQ3RCO0FBV0Q7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBb0JHO0FBQ0gscUJBQWEsaUJBQWlCO0lBQzVCLE9BQU8sQ0FBQyxNQUFNLENBQUMsbUJBQW1CLENBQVM7SUFFM0M7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0FzQkc7SUFDSCxPQUFhLGtCQUFrQixDQUFDLFNBQVMsRUFBRSxTQUFTLEVBQUUsT0FBTyxHQUFFLE1BQWEsR0FBRyxPQUFPLENBQUMsZ0JBQWdCLEVBQUUsQ0FBQyxDQXlGekc7Q0FDRiJ9

package/dest/providers/extension/extension_provider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extension_provider.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/extension_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAKzD,OAAO,EAAiD,KAAK,UAAU,EAAqB,MAAM,gBAAgB,CAAC;AAEnH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,IAAI,EAAE,UAAU,CAAC;IACjB,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,SAAS,CAAC;CACtB;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAS;IAE3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAa,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyFzG;CACF"}