@aztec/wallet-sdk 0.0.1-commit.d1f2d6c → 0.0.1-commit.d431d1c

package/src/{extension/provider → providers/extension}/extension_wallet.ts

@@ -6,7 +6,7 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
 import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
-import { type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+import { type WalletInfo, type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
 
 /**
  * Internal type representing a wallet method call before encryption.
@@ -26,30 +26,30 @@ export type DisconnectCallback = () => void;
 
 /**
  * A wallet implementation that communicates with browser extension wallets
- * using an encrypted MessageChannel.
+ * using a secure encrypted MessageChannel.
  *
- * This class uses a secure channel established after discovery:
+ * This class uses a pre-established secure channel from the discovery phase:
  *
- * 1. **MessageChannel**: Created during discovery and transferred via window.postMessage.
- *    Note: The port transfer is visible to page scripts, but security comes from encryption.
+ * 1. **MessageChannel**: A private communication channel created during discovery,
+ *    not visible to other scripts on the page (unlike window.postMessage).
  *
- * 2. **ECDH Key Exchange**: The shared secret was derived after discovery using
- *    Elliptic Curve Diffie-Hellman key exchange over the MessagePort.
+ * 2. **ECDH Key Exchange**: The shared secret was derived during discovery using
+ *    Elliptic Curve Diffie-Hellman key exchange.
  *
  * 3. **AES-GCM Encryption**: All messages are encrypted using AES-256-GCM,
- *    providing both confidentiality and authenticity. This is what secures the channel.
+ *    providing both confidentiality and authenticity.
  *
  * @example
  * ```typescript
- * // Discover and establish secure channel to a wallet
- * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-dapp' });
- * const connection = await discoveredWallets[0].establishSecureChannel();
+ * // Discovery returns wallets with secure channel components
+ * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
+ * const { info, port, sharedKey } = wallets[0];
  *
  * // User can verify emoji if desired
- * console.log('Verify:', hashToEmoji(connection.info.verificationHash!));
+ * console.log('Verify:', hashToEmoji(info.verificationHash!));
  *
- * // Create wallet using the connection
- * const wallet = ExtensionWallet.create(connection.info.id, connection.port, connection.sharedKey, chainInfo, 'my-dapp');
+ * // 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();
@@ -77,56 +77,81 @@ export class ExtensionWallet {
     private sharedKey: CryptoKey,
   ) {}
 
+  /** Cached Wallet proxy instance */
+  private walletProxy: Wallet | null = null;
+
   /**
-   * Creates a Wallet that communicates with a browser extension
+   * Creates an ExtensionWallet instance that communicates with a browser extension
    * over a secure encrypted MessageChannel.
    *
-   * @param extensionId - The unique identifier of the wallet extension
-   * @param port - The MessagePort for encrypted communication with the wallet
-   * @param sharedKey - The derived AES-256-GCM shared key for encryption
+   * @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 Wallet interface where all method calls are encrypted
+   * @returns The ExtensionWallet instance. Use {@link getWallet} to get the Wallet interface.
    *
    * @example
    * ```typescript
-   * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-defi-app' });
-   * const connection = await discoveredWallets[0].establishSecureChannel();
-   * const wallet = ExtensionWallet.create(
-   *   connection.info.id,
-   *   connection.port,
-   *   connection.sharedKey,
-   *   chainInfo,
+   * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
+   * const { info, port, sharedKey } = wallets[0];
+   * const extensionWallet = ExtensionWallet.create(
+   *   info,
+   *   { chainId: Fr(31337), version: Fr(0) },
+   *   port,
+   *   sharedKey,
    *   'my-defi-app'
    * );
    *
+   * // Register disconnect handler
+   * extensionWallet.onDisconnect(() => console.log('Disconnected!'));
+   *
+   * // Get the Wallet interface for dApp usage
+   * const wallet = extensionWallet.getWallet();
    * const accounts = await wallet.getAccounts();
    * ```
    */
   static create(
-    extensionId: string,
+    walletInfo: WalletInfo,
+    chainInfo: ChainInfo,
     port: MessagePort,
     sharedKey: CryptoKey,
-    chainInfo: ChainInfo,
     appId: string,
-  ): Wallet {
-    const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey);
-
-    // Set up message handler for encrypted responses and unencrypted control messages
-    wallet.port.onmessage = (event: MessageEvent) => {
-      const data = event.data;
-      // Check for unencrypted disconnect notification
-      if (data && typeof data === 'object' && 'type' in data && data.type === WalletMessageType.DISCONNECT) {
-        wallet.handleDisconnect();
-        return;
-      }
-      // Otherwise treat as encrypted payload
-      void wallet.handleEncryptedResponse(data as EncryptedPayload);
+  ): ExtensionWallet {
+    const wallet = new ExtensionWallet(chainInfo, appId, walletInfo.id, port, sharedKey);
+
+    // Set up message handler - all messages are now encrypted
+    wallet.port.onmessage = (event: MessageEvent<EncryptedPayload>) => {
+      void wallet.handleEncryptedResponse(event.data);
     };
 
     wallet.port.start();
 
-    return new Proxy(wallet, {
+    return wallet;
+  }
+
+  /**
+   * Returns a Wallet interface that proxies all method calls through the secure channel.
+   *
+   * The returned Wallet can be used directly by dApps - all method calls are automatically
+   * encrypted and sent to the wallet extension.
+   *
+   * @returns A Wallet implementation that encrypts all communication
+   *
+   * @example
+   * ```typescript
+   * const extensionWallet = ExtensionWallet.create(info, chainInfo, port, sharedKey, 'my-app');
+   * const wallet = extensionWallet.getWallet();
+   * const accounts = await wallet.getAccounts();
+   * ```
+   */
+  getWallet(): Wallet {
+    if (this.walletProxy) {
+      return this.walletProxy;
+    }
+
+    // Create a Proxy that intercepts wallet method calls and forwards them to the extension
+    this.walletProxy = new Proxy(this, {
       get: (target, prop) => {
         if (schemaHasMethod(WalletSchema, prop.toString())) {
           return async (...args: unknown[]) => {
@@ -141,6 +166,8 @@ export class ExtensionWallet {
         }
       },
     }) as unknown as Wallet;
+
+    return this.walletProxy;
   }
 
   /**
@@ -161,6 +188,18 @@ export class ExtensionWallet {
 
       const { messageId, result, error, walletId: responseWalletId } = response;
 
+      // Check for disconnect notification from the wallet backend
+      // This is sent as an encrypted error response with a special type
+      if (
+        error &&
+        typeof error === 'object' &&
+        'type' in error &&
+        (error.type as WalletMessageType) === WalletMessageType.SESSION_DISCONNECTED
+      ) {
+        this.handleDisconnect();
+        return;
+      }
+
       if (!messageId || !responseWalletId) {
         return;
       }
@@ -215,7 +254,8 @@ export class ExtensionWallet {
       walletId: this.extensionId,
     };
 
-    const encrypted = await encrypt(this.sharedKey, jsonStringify(message));
+    // Encrypt the message and send over the private MessageChannel
+    const encrypted = await encrypt(this.sharedKey, message);
     this.port.postMessage(encrypted);
 
     const { promise, resolve, reject } = promiseWithResolvers<unknown>();
@@ -234,22 +274,27 @@ export class ExtensionWallet {
     }
     this.disconnected = true;
 
+    // Close the port to prevent any further messages
     if (this.port) {
       this.port.onmessage = null;
       this.port.close();
     }
 
+    // Reject all pending requests
+    // Note: These rejections should be caught by the callers, but we log them
+    // here to help with debugging if they become unhandled
     const error = new Error('Wallet disconnected');
     for (const { reject } of this.inFlight.values()) {
       reject(error);
     }
     this.inFlight.clear();
 
+    // Notify registered callbacks
     for (const callback of this.disconnectCallbacks) {
       try {
         callback();
       } catch {
-        // Ignore errors on disconnect callbacks
+        // Ignore errors in callbacks
       }
     }
   }
@@ -298,24 +343,37 @@ export class ExtensionWallet {
    *
    * @example
    * ```typescript
-   * const extensionWallet = ExtensionWallet.create(extensionId, port, sharedKey, chainInfo, 'my-app');
+   * const wallet = await provider.connect('my-app');
    * // ... use wallet ...
-   * await extensionWallet.disconnect(); // Clean disconnect when done
+   * await wallet.disconnect(); // Clean disconnect when done
    * ```
    */
-  // eslint-disable-next-line require-await -- async for interface compatibility
   async disconnect(): Promise<void> {
     if (this.disconnected) {
       return;
     }
 
-    if (this.port) {
-      // Send unencrypted disconnect - control messages don't need encryption
-      this.port.postMessage({
-        type: WalletMessageType.DISCONNECT,
-      });
+    // Send disconnect message to extension before closing
+    if (this.port && this.sharedKey) {
+      try {
+        const message = {
+          type: WalletMessageType.DISCONNECT,
+          messageId: globalThis.crypto.randomUUID(),
+          chainInfo: this.chainInfo,
+          appId: this.appId,
+          walletId: this.extensionId,
+          args: [],
+        };
+        const encrypted = await encrypt(this.sharedKey, message);
+        this.port.postMessage(encrypted);
+      } catch {
+        // Ignore errors sending disconnect message
+      }
     }
 
     this.handleDisconnect();
+    if (this.port) {
+      this.port.close();
+    }
   }
 }

package/src/providers/extension/index.ts

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

package/src/types.ts

@@ -11,17 +11,14 @@ export enum WalletMessageType {
   DISCOVERY = 'aztec-wallet-discovery',
   /** Discovery response from a wallet */
   DISCOVERY_RESPONSE = 'aztec-wallet-discovery-response',
-  /** Disconnect message (unencrypted control message, bidirectional) */
+  /** Session disconnected notification (unencrypted control message) */
+  SESSION_DISCONNECTED = 'aztec-wallet-session-disconnected',
+  /** Explicit disconnect request from dApp */
   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.
+ * Information about an installed Aztec wallet
  */
 export interface WalletInfo {
   /** Unique identifier for the wallet */
@@ -32,17 +29,10 @@ 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;
   /**
-   * Verification hash for verification.
+   * 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.
    */
@@ -82,51 +72,27 @@ 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;
-  /** Basic wallet information */
+  /** 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/emoji_alphabet.d.ts

@@ -1,35 +0,0 @@
-/**
- * Emoji alphabet for visual verification of shared secrets.
- *
- * This alphabet contains 256 distinct, easily recognizable emojis for
- * anti-spoofing verification. With 256 emojis, each emoji represents
- * exactly 8 bits of entropy (log2(256) = 8).
- *
- * A 3x3 grid of 9 emojis provides 72 bits of security (9 × 8 = 72 bits),
- * making brute-force attacks computationally infeasible for real-time
- * MITM verification scenarios.
- *
- * Selection criteria:
- * - Visually distinct from each other
- * - Commonly supported across platforms (Unicode 12+)
- * - Easy to recognize and compare at a glance
- * - No text-based or flag emojis (platform-dependent rendering)
- * - No variation selectors (base emojis only)
- *
- * @packageDocumentation
- */
-/**
- * 256 distinct emojis for visual verification.
- * Index directly maps to byte value (0-255) for simple lookup.
- */
-export declare const EMOJI_ALPHABET: readonly string[];
-/**
- * Number of emojis in the alphabet.
- * Must be a power of 2 for clean bit mapping (256 = 2^8).
- */
-export declare const EMOJI_ALPHABET_SIZE = 256;
-/**
- * Bits of entropy per emoji (log2 of alphabet size).
- */
-export declare const BITS_PER_EMOJI = 8;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW1vamlfYWxwaGFiZXQuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9lbW9qaV9hbHBoYWJldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW1CRztBQUVIOzs7R0FHRztBQUNILGVBQU8sTUFBTSxjQUFjLEVBQUUsU0FBUyxNQUFNLEVBd1JsQyxDQUFDO0FBRVg7OztHQUdHO0FBQ0gsZUFBTyxNQUFNLG1CQUFtQixNQUFNLENBQUM7QUFFdkM7O0dBRUc7QUFDSCxlQUFPLE1BQU0sY0FBYyxJQUFJLENBQUMifQ==

package/dest/emoji_alphabet.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"emoji_alphabet.d.ts","sourceRoot":"","sources":["../src/emoji_alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAwRlC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC"}