@aztec/wallet-sdk 4.0.0-nightly.20260113 → 4.0.0-nightly.20260114

package/src/manager/wallet_manager.ts

@@ -35,26 +35,25 @@ export class WalletManager {
     const providers: WalletProvider[] = [];
     const { chainInfo } = options;
 
-    // Discover extension wallets
     if (this.config.extensions?.enabled) {
-      const extensions = await ExtensionProvider.discoverExtensions(chainInfo, options.timeout);
+      const discoveredWallets = await ExtensionProvider.discoverExtensions(chainInfo, options.timeout);
       const extensionConfig = this.config.extensions;
 
-      for (const ext of extensions) {
-        // Apply allow/block lists
-        if (!this.isExtensionAllowed(ext.id, extensionConfig)) {
+      for (const { info, port, sharedKey } of discoveredWallets) {
+        if (!this.isExtensionAllowed(info.id, extensionConfig)) {
           continue;
         }
 
         providers.push({
-          id: ext.id,
+          id: info.id,
           type: 'extension',
-          name: ext.name,
-          icon: ext.icon,
+          name: info.name,
+          icon: info.icon,
           metadata: {
-            version: ext.version,
+            version: info.version,
+            verificationHash: info.verificationHash,
           },
-          connect: (appId: string) => ExtensionWallet.create(ext, chainInfo, appId),
+          connect: (appId: string) => Promise.resolve(ExtensionWallet.create(info, chainInfo, port, sharedKey, appId)),
         });
       }
     }
@@ -70,17 +69,14 @@ export class WalletManager {
    * @param config - Extension wallet configuration containing allow/block lists
    */
   private isExtensionAllowed(extensionId: string, config: ExtensionWalletConfig): boolean {
-    // Check block list first
     if (config.blockList && config.blockList.includes(extensionId)) {
       return false;
     }
 
-    // If allow list exists, extension must be in it
     if (config.allowList && config.allowList.length > 0) {
       return config.allowList.includes(extensionId);
     }
 
-    // If no allow list, extension is allowed (unless blocked)
     return true;
   }
 }

package/src/providers/extension/extension_provider.ts

@@ -2,34 +2,95 @@ import type { ChainInfo } from '@aztec/aztec.js/account';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 
+import { deriveSharedKey, exportPublicKey, generateKeyPair, hashSharedSecret, importPublicKey } from '../../crypto.js';
 import type { DiscoveryRequest, DiscoveryResponse, WalletInfo } from '../../types.js';
 
 /**
- * Provider for discovering and managing Aztec wallet extensions
+ * 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;
+}
+
+/**
+ * Internal type for discovery response with MessagePort
+ * @internal
+ */
+interface DiscoveryResponseWithPort extends DiscoveryResponse {
+  /** The MessagePort transferred from the wallet */
+  port?: MessagePort;
+}
+
+/**
+ * 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 class ExtensionProvider {
-  private static discoveredExtensions: Map<string, WalletInfo> = new Map();
   private static discoveryInProgress = false;
 
   /**
-   * Discovers all installed Aztec wallet extensions
+   * 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 extension information
+   * @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 async discoverExtensions(chainInfo: ChainInfo, timeout: number = 1000): Promise<WalletInfo[]> {
-    // If discovery is in progress, wait for it to complete
+  static async discoverExtensions(chainInfo: ChainInfo, timeout: number = 1000): Promise<DiscoveredWallet[]> {
+    // If discovery is already in progress, wait and return empty
+    // (caller should retry or handle appropriately)
     if (this.discoveryInProgress) {
       await new Promise(resolve => setTimeout(resolve, timeout));
-      return Array.from(this.discoveredExtensions.values());
+      return [];
     }
 
     this.discoveryInProgress = true;
-    this.discoveredExtensions.clear();
 
-    const { promise, resolve } = promiseWithResolvers<WalletInfo[]>();
+    // Generate key pair for this discovery session
+    const keyPair = await generateKeyPair();
+    const exportedPublicKey = await exportPublicKey(keyPair.publicKey);
+
+    const { promise, resolve } = promiseWithResolvers<DiscoveredWallet[]>();
     const requestId = globalThis.crypto.randomUUID();
-    const responses: WalletInfo[] = [];
+    const responses: DiscoveredWallet[] = [];
 
     // Set up listener for discovery responses
     const handleMessage = (event: MessageEvent) => {
@@ -37,7 +98,7 @@ export class ExtensionProvider {
         return;
       }
 
-      let data: DiscoveryResponse;
+      let data: DiscoveryResponseWithPort;
       try {
         data = JSON.parse(event.data);
       } catch {
@@ -45,18 +106,52 @@ export class ExtensionProvider {
       }
 
       if (data.type === 'aztec-wallet-discovery-response' && data.requestId === requestId) {
-        responses.push(data.walletInfo);
-        this.discoveredExtensions.set(data.walletInfo.id, data.walletInfo);
+        // Get the MessagePort from the event
+        const port = event.ports?.[0];
+        if (!port) {
+          return;
+        }
+
+        // Derive shared key from wallet's public key
+        const walletPublicKey = data.walletInfo.publicKey;
+        if (!walletPublicKey) {
+          return;
+        }
+
+        void (async () => {
+          try {
+            const importedWalletKey = await importPublicKey(walletPublicKey);
+            const sharedKey = await deriveSharedKey(keyPair.privateKey, importedWalletKey);
+
+            // Compute verification hash
+            const verificationHash = await hashSharedSecret(sharedKey);
+
+            // Create wallet info with verification hash
+            const walletInfo: WalletInfo = {
+              ...data.walletInfo,
+              verificationHash,
+            };
+
+            responses.push({
+              info: walletInfo,
+              port,
+              sharedKey,
+            });
+          } catch {
+            // Failed to derive key, skip this wallet
+          }
+        })();
       }
     };
 
     window.addEventListener('message', handleMessage);
 
-    // Send discovery message
+    // Send discovery message with our public key
     const discoveryMessage: DiscoveryRequest = {
       type: 'aztec-wallet-discovery',
       requestId,
       chainInfo,
+      publicKey: exportedPublicKey,
     };
     window.postMessage(jsonStringify(discoveryMessage), '*');
 

package/src/providers/extension/extension_wallet.ts

@@ -5,17 +5,8 @@ import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundati
 import { schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
-import {
-  type EncryptedPayload,
-  type ExportedPublicKey,
-  decrypt,
-  deriveSharedKey,
-  encrypt,
-  exportPublicKey,
-  generateKeyPair,
-  importPublicKey,
-} from '../../crypto.js';
-import type { ConnectRequest, WalletInfo, WalletMessage, WalletResponse } from '../../types.js';
+import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
+import type { WalletInfo, WalletMessage, WalletResponse } from '../../types.js';
 
 /**
  * Internal type representing a wallet method call before encryption.
@@ -32,26 +23,28 @@ type WalletMethodCall = {
  * A wallet implementation that communicates with browser extension wallets
  * using a secure encrypted MessageChannel.
  *
- * This class establishes a private communication channel with a wallet extension
- * using the following security mechanisms:
+ * This class uses a pre-established secure channel from the discovery phase:
  *
- * 1. **MessageChannel**: Creates a private communication channel that is not
- *    visible to other scripts on the page (unlike window.postMessage).
+ * 1. **MessageChannel**: A private communication channel created during discovery,
+ *    not visible to other scripts on the page (unlike window.postMessage).
  *
- * 2. **ECDH Key Exchange**: Uses Elliptic Curve Diffie-Hellman to derive a
- *    shared secret between the dApp and wallet without transmitting private keys.
+ * 2. **ECDH Key Exchange**: The shared secret was derived during discovery using
+ *    Elliptic Curve Diffie-Hellman key exchange.
  *
- * 3. **AES-GCM Encryption**: All messages after channel establishment are
- *    encrypted using AES-256-GCM, providing both confidentiality and authenticity.
+ * 3. **AES-GCM Encryption**: All messages are encrypted using AES-256-GCM,
+ *    providing both confidentiality and authenticity.
  *
  * @example
  * ```typescript
- * // Discovery returns wallet info including the wallet's public key
+ * // Discovery returns wallets with secure channel components
  * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
- * const walletInfo = wallets[0];
+ * const { info, port, sharedKey } = wallets[0];
  *
- * // Create a secure connection to the wallet
- * const wallet = await ExtensionWallet.create(walletInfo, chainInfo, 'my-dapp');
+ * // User can verify emoji if desired
+ * console.log('Verify:', hashToEmoji(info.verificationHash!));
+ *
+ * // Create wallet using the discovered components
+ * const wallet = await ExtensionWallet.create(info, chainInfo, port, sharedKey, 'my-dapp');
  *
  * // All subsequent calls are encrypted
  * const accounts = await wallet.getAccounts();
@@ -61,58 +54,61 @@ export class ExtensionWallet {
   /** Map of pending requests awaiting responses, keyed by message ID */
   private inFlight = new Map<string, PromiseWithResolvers<unknown>>();
 
-  /** The MessagePort for private communication with the extension */
-  private port: MessagePort | null = null;
-
-  /** The derived AES-GCM key for encrypting/decrypting messages */
-  private sharedKey: CryptoKey | null = null;
-
   /**
    * Private constructor - use {@link ExtensionWallet.create} to instantiate.
    * @param chainInfo - The chain information (chainId and version)
    * @param appId - Application identifier for the requesting dApp
    * @param extensionId - The unique identifier of the target wallet extension
+   * @param port - The MessagePort for private communication with the wallet
+   * @param sharedKey - The derived AES-256-GCM shared key for encryption
    */
   private constructor(
     private chainInfo: ChainInfo,
     private appId: string,
     private extensionId: string,
+    private port: MessagePort,
+    private sharedKey: CryptoKey,
   ) {}
 
   /**
    * Creates an ExtensionWallet instance that proxies wallet calls to a browser extension
    * over a secure encrypted MessageChannel.
    *
-   * The connection process:
-   * 1. Generates an ECDH key pair for this session
-   * 2. Derives a shared AES-256 key using the wallet's public key
-   * 3. Creates a MessageChannel and transfers one port to the extension
-   * 4. Returns a Proxy that encrypts all wallet method calls
-   *
-   * @param walletInfo - The discovered wallet information, including the wallet's ECDH public key
+   * @param walletInfo - The wallet info from ExtensionProvider.discoverExtensions()
    * @param chainInfo - The chain information (chainId and version) for request context
+   * @param port - The MessagePort for private communication with the wallet
+   * @param sharedKey - The derived AES-256-GCM shared key for encryption
    * @param appId - Application identifier used to identify the requesting dApp to the wallet
    * @returns A Promise resolving to a Wallet implementation that encrypts all communication
    *
-   * @throws Error if the secure channel cannot be established
-   *
    * @example
    * ```typescript
+   * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
+   * const { info, port, sharedKey } = wallets[0];
    * const wallet = await ExtensionWallet.create(
-   *   walletInfo,
+   *   info,
    *   { chainId: Fr(31337), version: Fr(0) },
+   *   port,
+   *   sharedKey,
    *   'my-defi-app'
    * );
    * ```
    */
-  static async create(walletInfo: WalletInfo, chainInfo: ChainInfo, appId: string): Promise<Wallet> {
-    const wallet = new ExtensionWallet(chainInfo, appId, walletInfo.id);
-
-    if (!walletInfo.publicKey) {
-      throw new Error('Wallet does not support secure channel establishment (missing public key)');
-    }
+  static create(
+    walletInfo: WalletInfo,
+    chainInfo: ChainInfo,
+    port: MessagePort,
+    sharedKey: CryptoKey,
+    appId: string,
+  ): Wallet {
+    const wallet = new ExtensionWallet(chainInfo, appId, walletInfo.id, port, sharedKey);
+
+    // Set up message handler
+    wallet.port.onmessage = (event: MessageEvent<EncryptedPayload>) => {
+      void wallet.handleEncryptedResponse(event.data);
+    };
 
-    await wallet.establishSecureChannel(walletInfo.publicKey);
+    wallet.port.start();
 
     // Create a Proxy that intercepts wallet method calls and forwards them to the extension
     return new Proxy(wallet, {
@@ -132,47 +128,6 @@ export class ExtensionWallet {
     }) as unknown as Wallet;
   }
 
-  /**
-   * Establishes a secure MessageChannel with ECDH key exchange.
-   *
-   * This method performs the cryptographic handshake:
-   * 1. Generates a new ECDH P-256 key pair for this session
-   * 2. Imports the wallet's public key and derives a shared secret
-   * 3. Creates a MessageChannel for private communication
-   * 4. Sends a connection request with our public key via window.postMessage
-   *    (this is the only public message - subsequent communication uses the private channel)
-   *
-   * @param walletExportedPublicKey - The wallet's ECDH public key in JWK format
-   */
-  private async establishSecureChannel(walletExportedPublicKey: ExportedPublicKey): Promise<void> {
-    const keyPair = await generateKeyPair();
-    const exportedPublicKey = await exportPublicKey(keyPair.publicKey);
-
-    const walletPublicKey = await importPublicKey(walletExportedPublicKey);
-    this.sharedKey = await deriveSharedKey(keyPair.privateKey, walletPublicKey);
-
-    const channel = new MessageChannel();
-    this.port = channel.port1;
-
-    this.port.onmessage = async (event: MessageEvent<EncryptedPayload>) => {
-      await this.handleEncryptedResponse(event.data);
-    };
-
-    this.port.start();
-
-    // Send connection request with our public key and transfer port2 to content script
-    // This is the only public postMessage - it contains our public key (safe to expose)
-    // and transfers the MessagePort for subsequent private communication
-    const connectRequest: ConnectRequest = {
-      type: 'aztec-wallet-connect',
-      walletId: this.extensionId,
-      appId: this.appId,
-      publicKey: exportedPublicKey,
-    };
-
-    window.postMessage(jsonStringify(connectRequest), '*', [channel.port2]);
-  }
-
   /**
    * Handles an encrypted response received from the wallet extension.
    *
@@ -219,7 +174,7 @@ export class ExtensionWallet {
    * Sends an encrypted wallet method call over the secure MessageChannel.
    *
    * The message is encrypted using AES-256-GCM with the shared key derived
-   * during channel establishment. A unique message ID is generated to correlate
+   * during discovery. A unique message ID is generated to correlate
    * the response.
    *
    * @param call - The wallet method call containing method name and arguments
@@ -259,7 +214,8 @@ export class ExtensionWallet {
    *
    * @example
    * ```typescript
-   * const wallet = await ExtensionWallet.create(walletInfo, chainInfo, 'my-app');
+   * const { info, port, sharedKey } = wallets[0];
+   * const wallet = await ExtensionWallet.create(info, chainInfo, port, sharedKey, 'my-app');
    * // ... use wallet ...
    * wallet.close(); // Clean up when done
    * ```
@@ -267,9 +223,7 @@ export class ExtensionWallet {
   close(): void {
     if (this.port) {
       this.port.close();
-      this.port = null;
     }
-    this.sharedKey = null;
     this.inFlight.clear();
   }
 }

package/src/providers/extension/index.ts

@@ -1,11 +1,4 @@
 export { ExtensionWallet } from './extension_wallet.js';
-export { ExtensionProvider } from './extension_provider.js';
+export { ExtensionProvider, type DiscoveredWallet } from './extension_provider.js';
 export * from '../../crypto.js';
-export type {
-  WalletInfo,
-  WalletMessage,
-  WalletResponse,
-  DiscoveryRequest,
-  DiscoveryResponse,
-  ConnectRequest,
-} from '../../types.js';
+export type { WalletInfo, WalletMessage, WalletResponse, DiscoveryRequest, DiscoveryResponse } from '../../types.js';

package/src/types.ts

@@ -16,6 +16,12 @@ export interface WalletInfo {
   version: string;
   /** Wallet's ECDH public key for secure channel establishment */
   publicKey: ExportedPublicKey;
+  /**
+   * Hash of the shared secret for anti-MITM 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;
 }
 
 /**
@@ -60,6 +66,8 @@ export interface DiscoveryRequest {
   requestId: string;
   /** Chain information to check if wallet supports this network */
   chainInfo: ChainInfo;
+  /** dApp's ECDH public key for deriving shared secret */
+  publicKey: ExportedPublicKey;
 }
 
 /**
@@ -73,17 +81,3 @@ export interface DiscoveryResponse {
   /** Wallet information */
   walletInfo: WalletInfo;
 }
-
-/**
- * Connection request to establish secure channel
- */
-export interface ConnectRequest {
-  /** Message type for connection */
-  type: 'aztec-wallet-connect';
-  /** Target wallet ID */
-  walletId: string;
-  /** Application ID */
-  appId: string;
-  /** dApp's ECDH public key for deriving shared secret */
-  publicKey: ExportedPublicKey;
-}