@aztec/wallet-sdk 0.0.1-commit.9593d84 → 0.0.1-commit.96bb3f7

package/src/crypto.ts

@@ -0,0 +1,283 @@
+/**
+ * Cryptographic utilities for secure wallet communication.
+ *
+ * This module provides ECDH key exchange and AES-GCM encryption primitives
+ * for establishing secure communication channels between dApps and wallet extensions.
+ *
+ * The crypto flow:
+ * 1. Both parties generate ECDH key pairs using {@link generateKeyPair}
+ * 2. Public keys are exchanged (exported via {@link exportPublicKey}, imported via {@link importPublicKey})
+ * 3. Both parties derive the same shared secret using {@link deriveSharedKey}
+ * 4. Messages are encrypted/decrypted using {@link encrypt} and {@link decrypt}
+ *
+ * @example
+ * ```typescript
+ * // Party A
+ * const keyPairA = await generateKeyPair();
+ * const publicKeyA = await exportPublicKey(keyPairA.publicKey);
+ *
+ * // Party B
+ * const keyPairB = await generateKeyPair();
+ * const publicKeyB = await exportPublicKey(keyPairB.publicKey);
+ *
+ * // Exchange public keys, then derive shared secret
+ * const importedB = await importPublicKey(publicKeyB);
+ * const sharedKeyA = await deriveSharedKey(keyPairA.privateKey, importedB);
+ *
+ * // Encrypt and decrypt
+ * const encrypted = await encrypt(sharedKeyA, { message: 'hello' });
+ * const decrypted = await decrypt(sharedKeyB, encrypted);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+
+/**
+ * Exported public key in JWK format for transmission over untrusted channels.
+ *
+ * Contains only the public components of an ECDH P-256 key, safe to share.
+ */
+export interface ExportedPublicKey {
+  /** Key type - always "EC" for elliptic curve */
+  kty: string;
+  /** Curve name - always "P-256" */
+  crv: string;
+  /** X coordinate (base64url encoded) */
+  x: string;
+  /** Y coordinate (base64url encoded) */
+  y: string;
+}
+
+/**
+ * Encrypted message payload containing ciphertext and initialization vector.
+ *
+ * Both fields are base64-encoded for safe transmission as JSON.
+ */
+export interface EncryptedPayload {
+  /** Initialization vector (base64 encoded, 12 bytes) */
+  iv: string;
+  /** Ciphertext (base64 encoded) */
+  ciphertext: string;
+}
+
+/**
+ * ECDH key pair for secure communication.
+ *
+ * The private key should never be exported or transmitted.
+ * The public key can be exported via {@link exportPublicKey} for exchange.
+ */
+export interface SecureKeyPair {
+  /** Public key - safe to share */
+  publicKey: CryptoKey;
+  /** Private key - keep secret, used for key derivation */
+  privateKey: CryptoKey;
+}
+
+/**
+ * Generates an ECDH P-256 key pair for key exchange.
+ *
+ * The generated key pair can be used to derive a shared secret with another
+ * party's public key using {@link deriveSharedKey}.
+ *
+ * @returns A new ECDH key pair
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateKeyPair();
+ * const publicKey = await exportPublicKey(keyPair.publicKey);
+ * // Send publicKey to the other party
+ * ```
+ */
+export async function generateKeyPair(): Promise<SecureKeyPair> {
+  const keyPair = await crypto.subtle.generateKey(
+    {
+      name: 'ECDH',
+      namedCurve: 'P-256',
+    },
+    true, // extractable (needed to export public key)
+    ['deriveKey'],
+  );
+  return {
+    publicKey: keyPair.publicKey,
+    privateKey: keyPair.privateKey,
+  };
+}
+
+/**
+ * Exports a public key to JWK format for transmission.
+ *
+ * The exported key contains only public components and is safe to transmit
+ * over untrusted channels.
+ *
+ * @param publicKey - The CryptoKey public key to export
+ * @returns The public key in JWK format
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateKeyPair();
+ * const exported = await exportPublicKey(keyPair.publicKey);
+ * // exported can be JSON serialized and sent to another party
+ * ```
+ */
+export async function exportPublicKey(publicKey: CryptoKey): Promise<ExportedPublicKey> {
+  const jwk = await crypto.subtle.exportKey('jwk', publicKey);
+  return {
+    kty: jwk.kty!,
+    crv: jwk.crv!,
+    x: jwk.x!,
+    y: jwk.y!,
+  };
+}
+
+/**
+ * Imports a public key from JWK format.
+ *
+ * Used to import the other party's public key for deriving a shared secret.
+ *
+ * @param exported - The public key in JWK format
+ * @returns A CryptoKey that can be used with {@link deriveSharedKey}
+ *
+ * @example
+ * ```typescript
+ * // Receive exported public key from other party
+ * const theirPublicKey = await importPublicKey(receivedPublicKey);
+ * const sharedKey = await deriveSharedKey(myPrivateKey, theirPublicKey);
+ * ```
+ */
+export function importPublicKey(exported: ExportedPublicKey): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'jwk',
+    {
+      kty: exported.kty,
+      crv: exported.crv,
+      x: exported.x,
+      y: exported.y,
+    },
+    {
+      name: 'ECDH',
+      namedCurve: 'P-256',
+    },
+    false,
+    [],
+  );
+}
+
+/**
+ * Derives a shared AES-256-GCM key from ECDH key exchange.
+ *
+ * Both parties will derive the same shared key when using their own private key
+ * and the other party's public key. This is the core of ECDH key agreement.
+ *
+ * @param privateKey - Your ECDH private key
+ * @param publicKey - The other party's ECDH public key
+ * @returns An AES-256-GCM key for encryption/decryption
+ *
+ * @example
+ * ```typescript
+ * // Both parties derive the same key
+ * const sharedKeyA = await deriveSharedKey(privateKeyA, publicKeyB);
+ * const sharedKeyB = await deriveSharedKey(privateKeyB, publicKeyA);
+ * // sharedKeyA and sharedKeyB are equivalent
+ * ```
+ */
+export function deriveSharedKey(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey> {
+  return crypto.subtle.deriveKey(
+    {
+      name: 'ECDH',
+      public: publicKey,
+    },
+    privateKey,
+    {
+      name: 'AES-GCM',
+      length: 256,
+    },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/**
+ * Encrypts data using AES-256-GCM.
+ *
+ * The data is JSON serialized before encryption. A random 12-byte IV is
+ * generated for each encryption operation.
+ *
+ * AES-GCM provides both confidentiality and authenticity - any tampering
+ * with the ciphertext will cause decryption to fail.
+ *
+ * @param key - The AES-GCM key (from {@link deriveSharedKey})
+ * @param data - The data to encrypt (will be JSON serialized)
+ * @returns The encrypted payload with IV and ciphertext
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await encrypt(sharedKey, { action: 'transfer', amount: 100 });
+ * // encrypted.iv and encrypted.ciphertext are base64 strings
+ * ```
+ */
+export async function encrypt(key: CryptoKey, data: unknown): Promise<EncryptedPayload> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encoded = new TextEncoder().encode(jsonStringify(data));
+
+  const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded);
+
+  return {
+    iv: arrayBufferToBase64(iv),
+    ciphertext: arrayBufferToBase64(ciphertext),
+  };
+}
+
+/**
+ * Decrypts data using AES-256-GCM.
+ *
+ * The decrypted data is JSON parsed before returning.
+ *
+ * @typeParam T - The expected type of the decrypted data
+ * @param key - The AES-GCM key (from {@link deriveSharedKey})
+ * @param payload - The encrypted payload from {@link encrypt}
+ * @returns The decrypted and parsed data
+ *
+ * @throws Error if decryption fails (wrong key or tampered ciphertext)
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await decrypt<{ action: string; amount: number }>(sharedKey, encrypted);
+ * console.log(decrypted.action); // 'transfer'
+ * ```
+ */
+export async function decrypt<T = unknown>(key: CryptoKey, payload: EncryptedPayload): Promise<T> {
+  const iv = base64ToArrayBuffer(payload.iv);
+  const ciphertext = base64ToArrayBuffer(payload.ciphertext);
+
+  const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+
+  const decoded = new TextDecoder().decode(decrypted);
+  return JSON.parse(decoded) as T;
+}
+
+/**
+ * Converts ArrayBuffer to base64 string.
+ * @internal
+ */
+function arrayBufferToBase64(buffer: ArrayBuffer | Uint8Array): string {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Converts base64 string to ArrayBuffer.
+ * @internal
+ */
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}

package/src/manager/index.ts

@@ -9,13 +9,7 @@ export type {
 } from './types.js';
 
 // Re-export types from providers for convenience
-export type {
-  WalletInfo,
-  WalletMessage,
-  WalletResponse,
-  DiscoveryRequest,
-  DiscoveryResponse,
-} from '../providers/types.js';
+export type { WalletInfo, WalletMessage, WalletResponse, DiscoveryRequest, DiscoveryResponse } from '../types.js';
 
 // Re-export commonly needed utilities for wallet integration
 export { ChainInfoSchema } from '@aztec/aztec.js/account';

package/src/manager/wallet_manager.ts

@@ -54,7 +54,7 @@ export class WalletManager {
           metadata: {
             version: ext.version,
           },
-          connect: (appId: string) => Promise.resolve(ExtensionWallet.create(chainInfo, appId, ext.id)),
+          connect: (appId: string) => ExtensionWallet.create(ext, chainInfo, appId),
         });
       }
     }

package/src/providers/extension/extension_provider.ts

@@ -2,7 +2,7 @@ import type { ChainInfo } from '@aztec/aztec.js/account';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 
-import type { DiscoveryRequest, DiscoveryResponse, WalletInfo } from '../types.js';
+import type { DiscoveryRequest, DiscoveryResponse, WalletInfo } from '../../types.js';
 
 /**
  * Provider for discovering and managing Aztec wallet extensions

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';