@aztec/wallet-sdk 4.0.0-nightly.20260108 → 4.0.0-nightly.20260110

package/src/providers/extension/extension_wallet.ts

@@ -5,29 +5,74 @@ import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundati
 import { schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
-import type { WalletMessage, WalletResponse } from '../types.js';
+import {
+  type EncryptedPayload,
+  type ExportedPublicKey,
+  decrypt,
+  deriveSharedKey,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  importPublicKey,
+} from '../../crypto.js';
+import type { ConnectRequest, WalletInfo, WalletMessage, WalletResponse } from '../../types.js';
 
 /**
- * Message payload for posting to extension
+ * Internal type representing a wallet method call before encryption.
+ * @internal
  */
 type WalletMethodCall = {
-  /**
-   * The wallet method name to invoke
-   */
+  /** The wallet method name to invoke */
   type: keyof FunctionsOf<Wallet>;
-  /**
-   * Arguments to pass to the wallet method
-   */
+  /** Arguments to pass to the wallet method */
   args: unknown[];
 };
 
 /**
  * A wallet implementation that communicates with browser extension wallets
- * Supports multiple extensions by targeting specific extension IDs
+ * using a secure encrypted MessageChannel.
+ *
+ * This class establishes a private communication channel with a wallet extension
+ * using the following security mechanisms:
+ *
+ * 1. **MessageChannel**: Creates a private communication channel that is 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.
+ *
+ * 3. **AES-GCM Encryption**: All messages after channel establishment are
+ *    encrypted using AES-256-GCM, providing both confidentiality and authenticity.
+ *
+ * @example
+ * ```typescript
+ * // Discovery returns wallet info including the wallet's public key
+ * const wallets = await ExtensionProvider.discoverExtensions(chainInfo);
+ * const walletInfo = wallets[0];
+ *
+ * // Create a secure connection to the wallet
+ * const wallet = await ExtensionWallet.create(walletInfo, chainInfo, 'my-dapp');
+ *
+ * // All subsequent calls are encrypted
+ * const accounts = await wallet.getAccounts();
+ * ```
  */
 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
+   */
   private constructor(
     private chainInfo: ChainInfo,
     private appId: string,
@@ -36,75 +81,157 @@ export class ExtensionWallet {
 
   /**
    * Creates an ExtensionWallet instance that proxies wallet calls to a browser extension
-   * @param chainInfo - The chain information (chainId and version)
-   * @param appId - Application identifier for the requesting dapp
-   * @param extensionId - Specific extension ID to communicate with
-   * @returns A Proxy object that implements the Wallet interface
+   * 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 chainInfo - The chain information (chainId and version) for request context
+   * @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 wallet = await ExtensionWallet.create(
+   *   walletInfo,
+   *   { chainId: Fr(31337), version: Fr(0) },
+   *   'my-defi-app'
+   * );
+   * ```
    */
-  static create(chainInfo: ChainInfo, appId: string, extensionId: string): Wallet {
-    const wallet = new ExtensionWallet(chainInfo, appId, extensionId);
+  static async create(walletInfo: WalletInfo, chainInfo: ChainInfo, appId: string): Promise<Wallet> {
+    const wallet = new ExtensionWallet(chainInfo, appId, walletInfo.id);
 
-    // Set up message listener for responses from extensions
-    window.addEventListener('message', event => {
-      if (event.source !== window) {
-        return;
-      }
+    if (!walletInfo.publicKey) {
+      throw new Error('Wallet does not support secure channel establishment (missing public key)');
+    }
 
-      let data: WalletResponse;
-      try {
-        data = JSON.parse(event.data);
-      } catch {
-        return;
-      }
+    await wallet.establishSecureChannel(walletInfo.publicKey);
 
-      // Ignore request messages (only process responses)
-      if ('type' in data) {
-        return;
-      }
+    // Create a Proxy that intercepts wallet method calls and forwards them to the extension
+    return new Proxy(wallet, {
+      get: (target, prop) => {
+        if (schemaHasMethod(WalletSchema, prop.toString())) {
+          return async (...args: unknown[]) => {
+            const result = await target.postMessage({
+              type: prop.toString() as keyof FunctionsOf<Wallet>,
+              args,
+            });
+            return WalletSchema[prop.toString() as keyof typeof WalletSchema].returnType().parseAsync(result);
+          };
+        } else {
+          return target[prop as keyof ExtensionWallet];
+        }
+      },
+    }) as unknown as Wallet;
+  }
 
-      const { messageId, result, error, walletId: responseWalletId } = data;
+  /**
+   * 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.
+   *
+   * Decrypts the response using the shared AES key and resolves or rejects
+   * the corresponding pending promise based on the response content.
+   *
+   * @param encrypted - The encrypted response from the wallet
+   */
+  private async handleEncryptedResponse(encrypted: EncryptedPayload): Promise<void> {
+    if (!this.sharedKey) {
+      return;
+    }
+
+    try {
+      const response = await decrypt<WalletResponse>(this.sharedKey, encrypted);
+
+      const { messageId, result, error, walletId: responseWalletId } = response;
 
       if (!messageId || !responseWalletId) {
         return;
       }
 
-      if (wallet.extensionId !== responseWalletId) {
+      if (this.extensionId !== responseWalletId) {
         return;
       }
 
-      if (!wallet.inFlight.has(messageId)) {
+      if (!this.inFlight.has(messageId)) {
         return;
       }
 
-      const { resolve, reject } = wallet.inFlight.get(messageId)!;
+      const { resolve, reject } = this.inFlight.get(messageId)!;
 
       if (error) {
         reject(new Error(jsonStringify(error)));
       } else {
         resolve(result);
       }
-      wallet.inFlight.delete(messageId);
-    });
-
-    // Create a Proxy that intercepts wallet method calls and forwards them to the extension
-    return new Proxy(wallet, {
-      get: (target, prop) => {
-        if (schemaHasMethod(WalletSchema, prop.toString())) {
-          return async (...args: unknown[]) => {
-            const result = await target.postMessage({
-              type: prop.toString() as keyof FunctionsOf<Wallet>,
-              args,
-            });
-            return WalletSchema[prop.toString() as keyof typeof WalletSchema].returnType().parseAsync(result);
-          };
-        } else {
-          return target[prop as keyof ExtensionWallet];
-        }
-      },
-    }) as unknown as Wallet;
+      this.inFlight.delete(messageId);
+      // eslint-disable-next-line no-empty
+    } catch {}
   }
 
-  private postMessage(call: WalletMethodCall): Promise<unknown> {
+  /**
+   * 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
+   * the response.
+   *
+   * @param call - The wallet method call containing method name and arguments
+   * @returns A Promise that resolves with the decrypted result from the wallet
+   *
+   * @throws Error if the secure channel has not been established
+   */
+  private async postMessage(call: WalletMethodCall): Promise<unknown> {
+    if (!this.port || !this.sharedKey) {
+      throw new Error('Secure channel not established');
+    }
+
     const messageId = globalThis.crypto.randomUUID();
     const message: WalletMessage = {
       type: call.type,
@@ -115,10 +242,34 @@ export class ExtensionWallet {
       walletId: this.extensionId,
     };
 
-    window.postMessage(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>();
     this.inFlight.set(messageId, { promise, resolve, reject });
     return promise;
   }
+
+  /**
+   * Closes the secure channel and cleans up resources.
+   *
+   * After calling this method, the wallet instance can no longer be used.
+   * Any pending requests will not receive responses.
+   *
+   * @example
+   * ```typescript
+   * const wallet = await ExtensionWallet.create(walletInfo, chainInfo, 'my-app');
+   * // ... use wallet ...
+   * wallet.close(); // Clean up when done
+   * ```
+   */
+  close(): void {
+    if (this.port) {
+      this.port.close();
+      this.port = null;
+    }
+    this.sharedKey = null;
+    this.inFlight.clear();
+  }
 }

package/src/providers/extension/index.ts

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

package/src/{providers/types.ts → types.ts}

@@ -1,7 +1,9 @@
 import type { ChainInfo } from '@aztec/aztec.js/account';
 
+import type { ExportedPublicKey } from './crypto.js';
+
 /**
- * Information about an installed Aztec wallet wallet
+ * Information about an installed Aztec wallet
  */
 export interface WalletInfo {
   /** Unique identifier for the wallet */
@@ -12,10 +14,12 @@ export interface WalletInfo {
   icon?: string;
   /** Wallet version */
   version: string;
+  /** Wallet's ECDH public key for secure channel establishment */
+  publicKey: ExportedPublicKey;
 }
 
 /**
- * Message format for wallet communication
+ * Message format for wallet communication (internal, before encryption)
  */
 export interface WalletMessage {
   /** Unique message ID for tracking responses */
@@ -47,7 +51,7 @@ export interface WalletResponse {
 }
 
 /**
- * Discovery message for finding installed wallets
+ * Discovery message for finding installed wallets (public, unencrypted)
  */
 export interface DiscoveryRequest {
   /** Message type for discovery */
@@ -59,7 +63,7 @@ export interface DiscoveryRequest {
 }
 
 /**
- * Discovery response from an wallet
+ * Discovery response from a wallet (public, unencrypted)
  */
 export interface DiscoveryResponse {
   /** Message type for discovery response */
@@ -69,3 +73,17 @@ 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;
+}

package/dest/providers/types.d.ts

@@ -1,67 +0,0 @@
-import type { ChainInfo } from '@aztec/aztec.js/account';
-/**
- * Information about an installed Aztec wallet wallet
- */
-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;
-}
-/**
- * Message format for wallet communication
- */
-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
- */
-export interface DiscoveryRequest {
-    /** Message type for discovery */
-    type: 'aztec-wallet-discovery';
-    /** Request ID */
-    requestId: string;
-    /** Chain information to check if wallet supports this network */
-    chainInfo: ChainInfo;
-}
-/**
- * Discovery response from an wallet
- */
-export interface DiscoveryResponse {
-    /** Message type for discovery response */
-    type: 'aztec-wallet-discovery-response';
-    /** Request ID matching the discovery request */
-    requestId: string;
-    /** Wallet information */
-    walletInfo: WalletInfo;
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9wcm92aWRlcnMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFFekQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsVUFBVTtJQUN6Qix1Q0FBdUM7SUFDdkMsRUFBRSxFQUFFLE1BQU0sQ0FBQztJQUNYLGlDQUFpQztJQUNqQyxJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsK0JBQStCO0lBQy9CLElBQUksQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNkLHFCQUFxQjtJQUNyQixPQUFPLEVBQUUsTUFBTSxDQUFDO0NBQ2pCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsYUFBYTtJQUM1QiwrQ0FBK0M7SUFDL0MsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQixnQ0FBZ0M7SUFDaEMsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQUNiLCtCQUErQjtJQUMvQixJQUFJLEVBQUUsT0FBTyxFQUFFLENBQUM7SUFDaEIsd0JBQXdCO0lBQ3hCLFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIsd0NBQXdDO0lBQ3hDLEtBQUssRUFBRSxNQUFNLENBQUM7SUFDZCw0Q0FBNEM7SUFDNUMsUUFBUSxFQUFFLE1BQU0sQ0FBQztDQUNsQjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGNBQWM7SUFDN0Isc0NBQXNDO0lBQ3RDLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsa0NBQWtDO0lBQ2xDLE1BQU0sQ0FBQyxFQUFFLE9BQU8sQ0FBQztJQUNqQiw2QkFBNkI7SUFDN0IsS0FBSyxDQUFDLEVBQUUsT0FBTyxDQUFDO0lBQ2hCLHVDQUF1QztJQUN2QyxRQUFRLEVBQUUsTUFBTSxDQUFDO0NBQ2xCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsZ0JBQWdCO0lBQy9CLGlDQUFpQztJQUNqQyxJQUFJLEVBQUUsd0JBQXdCLENBQUM7SUFDL0IsaUJBQWlCO0lBQ2pCLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsaUVBQWlFO0lBQ2pFLFNBQVMsRUFBRSxTQUFTLENBQUM7Q0FDdEI7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxpQkFBaUI7SUFDaEMsMENBQTBDO0lBQzFDLElBQUksRUFBRSxpQ0FBaUMsQ0FBQztJQUN4QyxnREFBZ0Q7SUFDaEQsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQix5QkFBeUI7SUFDekIsVUFBVSxFQUFFLFVBQVUsQ0FBQztDQUN4QiJ9

package/dest/providers/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,wBAAwB;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,iCAAiC,CAAC;IACxC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,UAAU,EAAE,UAAU,CAAC;CACxB"}

package/dest/providers/types.js

@@ -1,3 +0,0 @@
-/**
- * Discovery response from an wallet
- */ export { };