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

package/README.md

@@ -4,66 +4,76 @@ This guide explains how to integrate your wallet with the Aztec Wallet SDK, enab
 
 ## Available Types
 
-All types and utilities needed for wallet integration are exported from `@aztec/wallet-sdk/manager`:
+All types and utilities needed for wallet integration are exported from `@aztec/wallet-sdk/types`:
 
 ```typescript
 import type {
-  ChainInfo,
   DiscoveryRequest,
   DiscoveryResponse,
   WalletInfo,
   WalletMessage,
   WalletResponse,
-} from '@aztec/wallet-sdk/manager';
-import { ChainInfoSchema, WalletSchema, jsonStringify } from '@aztec/wallet-sdk/manager';
+} from '@aztec/wallet-sdk/types';
+```
+
+Cryptographic utilities for secure channel establishment are exported from `@aztec/wallet-sdk/crypto`:
+
+```typescript
+import type { EncryptedPayload, ExportedPublicKey } from '@aztec/wallet-sdk/crypto';
+import {
+  decrypt,
+  deriveSharedKey,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  hashSharedSecret,
+  hashToEmoji,
+  importPublicKey,
+} from '@aztec/wallet-sdk/crypto';
 ```
 
 ## Overview
 
-The Wallet SDK uses a **request-based discovery** model:
+The Wallet SDK uses a **unified discovery and connection** model with **end-to-end encryption**:
 
 1. **dApp requests wallets** for a specific chain/version via `WalletManager.getAvailableWallets({ chainInfo })`
-2. **SDK broadcasts** a discovery message with chain information
-3. **Your wallet responds** ONLY if it supports that specific network
-4. **dApp receives** only compatible wallets
-5. **dApp calls wallet methods** which your wallet handles and responds to
+2. **SDK broadcasts** a discovery message with chain information and the dApp's ECDH public key
+3. **Your wallet responds** with its ECDH public key and a MessagePort ONLY if it supports that network
+4. **Both parties derive** the same shared secret via ECDH key exchange
+5. **SDK receives** discovered wallets with secure channel already established (port + sharedKey)
+6. **All subsequent communication** is encrypted using AES-256-GCM over the private MessagePort
 
-### Transport Mechanisms
+### Key Features
 
-This guide uses **browser extension wallets** as the primary example, which communicate via `window.postMessage`. However, the same message protocol can be used with other transport mechanisms:
+- **No separate connection step**: The secure channel is established during discovery
+- **MessagePort transferred immediately**: The discovery response includes a MessagePort for private communication
+- **Anti-MITM verification**: Both parties can display emoji verification codes derived from the shared secret
 
-- **Extension wallets**: Use `window.postMessage` (examples shown throughout this guide)
-- **Web wallets**: Could use WebSockets, HTTP, or other protocols (see comments in examples for hypothetical WebSocket usage)
-- **Mobile wallets**: Could use deep links, app-to-app communication, or custom protocols
+### Transport Mechanisms
 
-The message format remains the same regardless of transport - only the delivery mechanism changes.
+This guide uses **browser extension wallets** as the primary example, which communicate via `window.postMessage` for discovery and MessageChannel for secure communication. The same message protocol can be adapted for other transport mechanisms.
 
 ## Discovery Protocol
 
 ### 1. Listen for Discovery Requests
 
-**Extension wallet example:**
+**Extension wallet (content script):**
 
 ```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
+window.addEventListener('message', async (event) => {
+  if (event.source !== window) return;
+
+  let data: DiscoveryRequest;
+  try {
+    data = JSON.parse(event.data);
+  } catch {
     return;
   }
 
-  const data = JSON.parse(event.data);
-
   if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
+    await handleDiscoveryRequest(data);
   }
 });
-
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   }
-// });
 ```
 
 ### 2. Discovery Message Format
@@ -71,328 +81,291 @@ window.addEventListener('message', event => {
 Discovery messages have this structure:
 
 ```typescript
-{
-  type: 'aztec-wallet-discovery',
-  requestId: string,              // UUID for tracking this request
-  chainInfo: {
-    chainId: Fr,                  // Chain ID
-    version: Fr                   // Protocol version
-  }
+interface DiscoveryRequest {
+  type: 'aztec-wallet-discovery';
+  requestId: string;              // UUID for tracking this request
+  chainInfo: ChainInfo;           // Chain ID and protocol version
+  publicKey: ExportedPublicKey;   // dApp's ECDH public key for key exchange
 }
 ```
 
-### 3. Check Network Support
-
-Before responding, verify your wallet supports the requested network:
-
-```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+### 3. Handle Discovery and Establish Secure Channel
 
-function handleDiscovery(message: any) {
-  const { requestId, chainInfo } = message;
+When your wallet receives a discovery request:
 
-  // Parse and validate chain info
-  const { chainId, version } = ChainInfoSchema.parse(chainInfo);
+1. Check if you support the requested network
+2. Derive the shared secret from the dApp's public key
+3. Create a MessageChannel for secure communication
+4. Respond with your wallet info and transfer one end of the channel
 
-  // Check if your wallet supports this network
-  const isSupported = checkNetworkSupport(chainId, version);
+**Extension wallet (background script):**
 
-  if (!isSupported) {
-    // Do NOT respond if you don't support this network
-    return;
+```typescript
+import {
+  deriveSharedKey,
+  exportPublicKey,
+  generateKeyPair,
+  hashSharedSecret,
+  importPublicKey,
+} from '@aztec/wallet-sdk/crypto';
+
+// Generate key pair on wallet initialization (per session)
+let walletKeyPair = await generateKeyPair();
+let walletPublicKey = await exportPublicKey(walletKeyPair.publicKey);
+
+// Store sessions by requestId
+const sessions = new Map<string, { sharedKey: CryptoKey; verificationHash: string; tabId: number }>();
+
+async function handleDiscovery(
+  request: DiscoveryRequest,
+  tabId: number
+): Promise<{ success: true; response: DiscoveryResponse }> {
+  // Check network support
+  if (!supportsNetwork(request.chainInfo)) {
+    throw new Error('Network not supported');
   }
 
-  // Respond if supported
-  respondToDiscovery(requestId);
-}
-```
-
-### 4. Respond to Discovery
+  // Import dApp's public key and derive shared secret
+  const dAppPublicKey = await importPublicKey(request.publicKey);
+  const sharedKey = await deriveSharedKey(walletKeyPair.privateKey, dAppPublicKey);
 
-If your wallet supports the network, respond with your wallet information:
+  // Compute verification hash for anti-MITM verification
+  const verificationHash = await hashSharedSecret(sharedKey);
 
-**Extension wallet example:**
+  // Store the session with verificationHash (emoji computed lazily for display)
+  sessions.set(request.requestId, { sharedKey, verificationHash, tabId });
 
-```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
-
-function respondToDiscovery(requestId: string) {
-  const response = {
+  const response: DiscoveryResponse = {
     type: 'aztec-wallet-discovery-response',
-    requestId,
+    requestId: request.requestId,
     walletInfo: {
-      id: 'my-aztec-wallet', // Unique wallet identifier
-      name: 'My Aztec Wallet', // Display name
-      icon: 'https://example.com/icon.png', // Optional icon URL
-      version: '1.0.0', // Wallet version
+      id: 'my-aztec-wallet',
+      name: 'My Aztec Wallet',
+      version: '1.0.0',
+      publicKey: walletPublicKey,
     },
   };
 
-  // Send as JSON string via window.postMessage
-  window.postMessage(jsonStringify(response), '*');
+  return { success: true, response };
 }
-
-// Using WebSocket:
-// websocket.send(jsonStringify(response));
 ```
 
-**Important Notes:**
-
-- Both the SDK and wallets send messages as JSON strings (using `jsonStringify`)
-- Both the SDK and wallets must parse incoming JSON strings
-- Always use `jsonStringify` from `@aztec/foundation/json-rpc` for sending messages
-- Always parse incoming messages with `JSON.parse` and the proper schemas
-
-## Message Format
-
-### Wallet Method Request
-
-After discovery, dApps will call wallet methods. These arrive as:
+**Content script (creates MessageChannel and sends response):**
 
 ```typescript
-{
-  type: string,                    // Wallet method name from the Wallet interface
-  messageId: string,               // UUID for tracking this request
-  args: unknown[],                 // Method arguments
-  chainInfo: {
-    chainId: Fr,                   // Same chain that was used in discovery
-    version: Fr
-  },
-  appId: string,                   // Application identifier
-  walletId: string                 // Your wallet's ID (from discovery response)
+async function handleDiscoveryRequest(request: DiscoveryRequest) {
+  // Forward to background script for key derivation
+  const result = await browser.runtime.sendMessage({
+    type: 'aztec-wallet-discovery',
+    content: request,
+  });
+
+  if (!result?.success) return;
+
+  // Create MessageChannel for secure communication
+  const channel = new MessageChannel();
+
+  // Set up relay from page to background
+  channel.port1.onmessage = (event) => {
+    browser.runtime.sendMessage({
+      type: 'secure-message',
+      requestId: request.requestId,
+      content: event.data,  // Encrypted payload
+    });
+  };
+  channel.port1.start();
+
+  // Send response with port2 to the page
+  window.postMessage(JSON.stringify(result.response), '*', [channel.port2]);
 }
 ```
 
-Example method calls:
-
-- `type: 'getAccounts'` - Get list of accounts
-- `type: 'getChainInfo'` - Get chain information
-- `type: 'sendTx'` - Send a transaction
-- `type: 'registerContract'` - Register a contract instance
-
-### Wallet Method Response
-
-Your wallet must respond with:
+### 4. Discovery Response Format
 
 ```typescript
-{
-  messageId: string,               // MUST match the request's messageId
-  result?: unknown,                // Method result (if successful)
-  error?: unknown,                 // Error (if failed)
-  walletId: string                 // Your wallet's ID
+interface DiscoveryResponse {
+  type: 'aztec-wallet-discovery-response';
+  requestId: string;              // Must match the request
+  walletInfo: WalletInfo;         // Wallet info including public key
+}
+
+interface WalletInfo {
+  id: string;                     // Unique wallet identifier
+  name: string;                   // Display name
+  icon?: string;                  // Optional icon URL
+  version: string;                // Wallet version
+  publicKey: ExportedPublicKey;   // ECDH public key for key exchange
 }
 ```
 
-## Handling Wallet Methods
+**Important:** The response is sent via `window.postMessage` with a MessagePort transferred as the third argument. The SDK receives the port and uses it for all subsequent encrypted communication.
 
-### 1. Set Up Message Listener
+## Secure Communication
 
-**Extension wallet example:**
+### Architecture for Extension Wallets
 
-```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
-    return;
-  }
+```
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄───(discovery only)─────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (decrypt+process)│
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │         MessagePort (private channel)    │
+       └──────────(encrypted messages)────────────┘
+```
 
-  let data;
-  try {
-    data = JSON.parse(event.data);
-  } catch {
-    return; // Not a valid JSON message
-  }
+**Security benefits:**
 
-  // Handle discovery
-  if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
-    return;
-  }
+- Content script never has access to private keys or shared secrets
+- All cryptographic operations happen in the background script (service worker)
+- MessagePort provides a private channel not visible to other page scripts
+- Only discovery uses `window.postMessage`; all wallet calls are encrypted on the MessagePort
 
-  // Handle wallet methods
-  if (data.messageId && data.type && data.walletId === 'my-aztec-wallet') {
-    handleWalletMethod(data);
-  }
-});
+### Handle Encrypted Messages
+
+All wallet method calls arrive as encrypted payloads on the MessagePort:
 
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   } else if (data.messageId && data.type) {
-//     handleWalletMethod(data);
-//   }
-// });
+```typescript
+interface EncryptedPayload {
+  iv: string;         // Base64-encoded initialization vector
+  ciphertext: string; // Base64-encoded encrypted data
+}
 ```
 
-### 2. Route to Wallet Implementation
+**Background script:**
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+import { decrypt, encrypt } from '@aztec/wallet-sdk/crypto';
 
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, appId, walletId } = message;
+async function handleSecureMessage(requestId: string, encrypted: EncryptedPayload) {
+  const session = sessions.get(requestId);
+  if (!session) return;
 
   try {
-    // Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
-
-    // Get the wallet instance for this chain
-    const wallet = await getWalletForChain(parsedChainInfo);
-
-    // Verify the method exists on the Wallet interface
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
-    }
+    // Decrypt the incoming message
+    const message = await decrypt<WalletMessage>(session.sharedKey, encrypted);
+    const { type, messageId, args, chainInfo, walletId } = message;
 
-    // Call the wallet method
+    // Process the wallet method call
+    const wallet = await getWalletForChain(chainInfo);
     const result = await wallet[type](...args);
 
-    // Send success response
-    sendResponse(messageId, walletId, result);
+    // Create and encrypt response
+    const response: WalletResponse = { messageId, result, walletId };
+    const encryptedResponse = await encrypt(session.sharedKey, response);
+
+    // Send back through content script
+    browser.tabs.sendMessage(session.tabId, {
+      type: 'secure-response',
+      requestId,
+      content: encryptedResponse,
+    });
   } catch (error) {
-    // Send error response
-    sendError(messageId, walletId, error);
+    // Send encrypted error response
+    const errorResponse: WalletResponse = {
+      messageId: message?.messageId ?? '',
+      error: { message: error.message },
+      walletId: message?.walletId ?? '',
+    };
+    const encryptedError = await encrypt(session.sharedKey, errorResponse);
+    // ... send error response
   }
 }
 ```
 
-### 3. Send Response
+## Message Formats
 
-**Extension wallet example:**
+### Wallet Method Request (Decrypted)
 
 ```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
-
-function sendResponse(messageId: string, walletId: string, result: unknown) {
-  const response = {
-    messageId,
-    result,
-    walletId,
-  };
-
-  // Send as JSON string
-  window.postMessage(jsonStringify(response), '*');
+interface WalletMessage {
+  type: string;        // Wallet method name (e.g., 'getAccounts', 'sendTx')
+  messageId: string;   // UUID for tracking this request
+  args: unknown[];     // Method arguments
+  chainInfo: ChainInfo;
+  appId: string;       // Application identifier
+  walletId: string;    // Your wallet's ID
 }
+```
 
-function sendError(messageId: string, walletId: string, error: Error) {
-  const response = {
-    messageId,
-    error: {
-      message: error.message,
-      stack: error.stack,
-    },
-    walletId,
-  };
+### Wallet Method Response
 
-  window.postMessage(jsonStringify(response), '*');
+```typescript
+interface WalletResponse {
+  messageId: string;   // Must match the request
+  result?: unknown;    // Method result (if successful)
+  error?: unknown;     // Error (if failed)
+  walletId: string;    // Your wallet's ID
 }
-
-// Using WebSocket:
-// websocket.send(jsonStringify({ messageId, result, walletId }));
 ```
 
-## Parsing Messages
-
-### Using Zod Schemas
+## Anti-MITM Verification
 
-Use the provided Zod schemas to parse and validate incoming messages:
+Both the dApp and wallet independently compute a `verificationHash` from the shared secret. If both parties compute the same hash, they know there's no man-in-the-middle attack.
 
 ```typescript
-import { ChainInfoSchema, WalletSchema } from '@aztec/wallet-sdk/manager';
+import { hashSharedSecret } from '@aztec/wallet-sdk/crypto';
 
-// Parse chain info
-const chainInfo = ChainInfoSchema.parse(message.chainInfo);
+// Compute verification hash from shared key
+const verificationHash = await hashSharedSecret(sharedKey);
 
-// Validate result against expected schema for a method
-const accountsResult = await wallet.getAccounts(...args);
-// The SDK handles schema validation on the client side
+// Store verificationHash in session - this is the cryptographic proof
+sessions.set(requestId, { sharedKey, verificationHash, tabId });
 ```
 
-The Wallet SDK automatically validates return values using `WalletSchema` on the client side, so your wallet implementation should return values that match the `Wallet` interface specification.
-
-## Error Handling
-
-### Error Response Format
-
-Always send error responses with this structure:
+For user-friendly display, convert the hash to an emoji sequence:
 
 ```typescript
-{
-  messageId: string,               // Match the request
-  error: {
-    message: string,               // Error message
-    code?: string,                 // Optional error code
-    stack?: string                 // Optional stack trace
-  },
-  walletId: string
-}
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
+
+// Convert to emoji only when displaying to the user
+const emoji = hashToEmoji(verificationHash);  // e.g., "🔵🦋🎯🐼"
 ```
 
-### Common Error Scenarios
+The dApp displays the same emoji sequence. If they match, the connection is secure.
 
-```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+## Session Management
 
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, walletId } = message;
+Sessions should be cleaned up when:
 
-  try {
-    // 1. Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
+- **Tab closes**: Browser tabs API `onRemoved` event
+- **Tab navigates**: Browser tabs API `onUpdated` event with `status === 'loading'`
 
-    // 2. Check network support
-    if (!isNetworkSupported(parsedChainInfo)) {
-      throw new Error('Network not supported by wallet');
+```typescript
+// Clean up when tab closes
+browser.tabs.onRemoved.addListener((tabId) => {
+  for (const [requestId, session] of sessions) {
+    if (session.tabId === tabId) {
+      sessions.delete(requestId);
     }
+  }
+});
 
-    // 3. Get wallet instance
-    const wallet = await getWalletForChain(parsedChainInfo);
-
-    // 4. Validate method exists
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
+// Clean up when tab navigates
+browser.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  if (changeInfo.status === 'loading') {
+    for (const [requestId, session] of sessions) {
+      if (session.tabId === tabId) {
+        sessions.delete(requestId);
+      }
     }
-
-    // 5. Execute method
-    const result = await wallet[type](...args);
-    sendResponse(messageId, walletId, result);
-  } catch (error) {
-    sendError(messageId, walletId, error);
   }
-}
-```
-
-### User Rejection Handling
-
-If a user rejects an action:
-
-```typescript
-{
-  messageId: 'abc-123',
-  error: {
-    message: 'User rejected the request',
-    code: 'USER_REJECTED'
-  },
-  walletId: 'my-wallet'
-}
+});
 ```
 
 ## Testing Your Integration
 
-### WalletManager
-
-In a dApp using the Wallet SDK:
+### Using WalletManager
 
 ```typescript
 import { Fr } from '@aztec/foundation/fields';
-import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { WalletManager, hashToEmoji } from '@aztec/wallet-sdk/manager';
 
 const manager = WalletManager.configure({
   extensions: { enabled: true },
 });
 
-// Discover wallets
+// Discover wallets (secure channel established automatically)
 const wallets = await manager.getAvailableWallets({
   chainInfo: {
     chainId: new Fr(31337),
@@ -401,19 +374,20 @@ const wallets = await manager.getAvailableWallets({
   timeout: 2000,
 });
 
-console.log('Discovered wallets:', wallets);
+// Each wallet provider has verification info
+for (const provider of wallets) {
+  const emoji = hashToEmoji(provider.metadata.verificationHash);
+  console.log(`${provider.name}: ${emoji}`);
+}
 
-// Connect to your wallet
+// Connect and use
 const walletProvider = wallets.find(w => w.id === 'my-aztec-wallet');
 if (walletProvider) {
-  const wallet = await walletProvider.connect('test-app');
+  const wallet = await walletProvider.connect('my-app-id');
 
-  // Test wallet methods from the Wallet interface
+  // All calls are automatically encrypted
   const accounts = await wallet.getAccounts();
   console.log('Accounts:', accounts);
-
-  const chainInfo = await wallet.getChainInfo();
-  console.log('Chain info:', chainInfo);
 }
 ```