@aztec/wallet-sdk 0.0.1-commit.21caa21 → 0.0.1-commit.3469e52

package/dest/providers/extension/extension_provider.js

@@ -1,23 +1,62 @@
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
+import { deriveSharedKey, exportPublicKey, generateKeyPair, hashSharedSecret, importPublicKey } from '../../crypto.js';
+import { WalletMessageType } from '../../types.js';
 /**
- * Provider for discovering and managing Aztec wallet extensions
+ * 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 {
-    static discoveredExtensions = new Map();
     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, timeout = 1000) {
-        // If discovery is in progress, wait for it to complete
+        // 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();
+        // Generate key pair for this discovery session
+        const keyPair = await generateKeyPair();
+        const exportedPublicKey = await exportPublicKey(keyPair.publicKey);
         const { promise, resolve } = promiseWithResolvers();
         const requestId = globalThis.crypto.randomUUID();
         const responses = [];
@@ -32,17 +71,46 @@ import { promiseWithResolvers } from '@aztec/foundation/promise';
             } catch  {
                 return;
             }
-            if (data.type === 'aztec-wallet-discovery-response' && data.requestId === requestId) {
-                responses.push(data.walletInfo);
-                this.discoveredExtensions.set(data.walletInfo.id, data.walletInfo);
+            if (data.type === WalletMessageType.DISCOVERY_RESPONSE && data.requestId === requestId) {
+                // 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 = {
+                            ...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 = {
-            type: 'aztec-wallet-discovery',
+            type: WalletMessageType.DISCOVERY,
             requestId,
-            chainInfo
+            chainInfo,
+            publicKey: exportedPublicKey
         };
         window.postMessage(jsonStringify(discoveryMessage), '*');
         // Wait for responses

package/dest/providers/extension/extension_wallet.d.ts

@@ -1,23 +1,155 @@
 import type { ChainInfo } from '@aztec/aztec.js/account';
 import { type Wallet } from '@aztec/aztec.js/wallet';
+import { type WalletInfo } from '../../types.js';
+/**
+ * Callback type for wallet disconnect events.
+ */
+export type DisconnectCallback = () => void;
 /**
  * A wallet implementation that communicates with browser extension wallets
- * Supports multiple extensions by targeting specific extension IDs
+ * using a secure encrypted MessageChannel.
+ *
+ * This class uses a pre-established secure channel from the discovery phase:
+ *
+ * 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 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.
+ *
+ * @example
+ * ```typescript
+ * // 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(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();
+ * ```
  */
 export declare class ExtensionWallet {
     private chainInfo;
     private appId;
     private extensionId;
+    private port;
+    private sharedKey;
+    /** Map of pending requests awaiting responses, keyed by message ID */
     private inFlight;
-    private constructor();
+    private disconnected;
+    private disconnectCallbacks;
     /**
-     * Creates an ExtensionWallet instance that proxies wallet calls to a browser extension
+     * 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 - Specific extension ID to communicate with
-     * @returns A Proxy object that implements the Wallet interface
+     * @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();
+    /** Cached Wallet proxy instance */
+    private walletProxy;
+    /**
+     * Creates an ExtensionWallet instance that communicates with a browser extension
+     * over a secure encrypted MessageChannel.
+     *
+     * @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 The ExtensionWallet instance. Use {@link getWallet} to get the Wallet interface.
+     *
+     * @example
+     * ```typescript
+     * 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(walletInfo: WalletInfo, chainInfo: ChainInfo, port: MessagePort, sharedKey: CryptoKey, appId: string): ExtensionWallet;
+    /**
+     * 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();
+     * ```
      */
-    static create(chainInfo: ChainInfo, appId: string, extensionId: string): Wallet;
+    getWallet(): Wallet;
+    private handleEncryptedResponse;
     private postMessage;
+    /**
+     * Handles wallet disconnection.
+     * Rejects all pending requests and notifies registered callbacks.
+     * @internal
+     */
+    private handleDisconnect;
+    /**
+     * Registers a callback to be invoked when the wallet disconnects.
+     *
+     * @param callback - Function to call when wallet disconnects
+     * @returns A function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const wallet = await ExtensionWallet.create(...);
+     * const unsubscribe = wallet.onDisconnect(() => {
+     *   console.log('Wallet disconnected! Please reconnect.');
+     *   // Clean up UI, prompt user to reconnect, etc.
+     * });
+     * // Later: unsubscribe(); to stop receiving notifications
+     * ```
+     */
+    onDisconnect(callback: DisconnectCallback): () => void;
+    /**
+     * Returns whether the wallet has been disconnected.
+     *
+     * @returns true if the wallet is no longer connected
+     */
+    isDisconnected(): boolean;
+    /**
+     * Disconnects from the wallet and cleans up resources.
+     *
+     * This method notifies the wallet extension that the session is ending,
+     * allowing it to clean up its state. After calling this method, the wallet
+     * instance can no longer be used and any pending requests will be rejected.
+     *
+     * @example
+     * ```typescript
+     * const wallet = await provider.connect('my-app');
+     * // ... use wallet ...
+     * await wallet.disconnect(); // Clean disconnect when done
+     * ```
+     */
+    disconnect(): Promise<void>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3dhbGxldC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3Byb3ZpZGVycy9leHRlbnNpb24vZXh0ZW5zaW9uX3dhbGxldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUN6RCxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQWdCLE1BQU0sd0JBQXdCLENBQUM7QUFzQm5FOzs7R0FHRztBQUNILHFCQUFhLGVBQWU7SUFJeEIsT0FBTyxDQUFDLFNBQVM7SUFDakIsT0FBTyxDQUFDLEtBQUs7SUFDYixPQUFPLENBQUMsV0FBVztJQUxyQixPQUFPLENBQUMsUUFBUSxDQUFvRDtJQUVwRSxPQUFPLGVBSUg7SUFFSjs7Ozs7O09BTUc7SUFDSCxNQUFNLENBQUMsTUFBTSxDQUFDLFNBQVMsRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLE1BQU0sRUFBRSxXQUFXLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0E2RDlFO0lBRUQsT0FBTyxDQUFDLFdBQVc7Q0FpQnBCIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3dhbGxldC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3Byb3ZpZGVycy9leHRlbnNpb24vZXh0ZW5zaW9uX3dhbGxldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUN6RCxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQWdCLE1BQU0sd0JBQXdCLENBQUM7QUFPbkUsT0FBTyxFQUFFLEtBQUssVUFBVSxFQUE4RCxNQUFNLGdCQUFnQixDQUFDO0FBYTdHOztHQUVHO0FBQ0gsTUFBTSxNQUFNLGtCQUFrQixHQUFHLE1BQU0sSUFBSSxDQUFDO0FBRTVDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0E4Qkc7QUFDSCxxQkFBYSxlQUFlO0lBZXhCLE9BQU8sQ0FBQyxTQUFTO0lBQ2pCLE9BQU8sQ0FBQyxLQUFLO0lBQ2IsT0FBTyxDQUFDLFdBQVc7SUFDbkIsT0FBTyxDQUFDLElBQUk7SUFDWixPQUFPLENBQUMsU0FBUztJQWxCbkIsc0VBQXNFO0lBQ3RFLE9BQU8sQ0FBQyxRQUFRLENBQW9EO0lBQ3BFLE9BQU8sQ0FBQyxZQUFZLENBQVM7SUFDN0IsT0FBTyxDQUFDLG1CQUFtQixDQUE0QjtJQUV2RDs7Ozs7OztPQU9HO0lBQ0gsT0FBTyxlQU1IO0lBRUosbUNBQW1DO0lBQ25DLE9BQU8sQ0FBQyxXQUFXLENBQXVCO0lBRTFDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0E4Qkc7SUFDSCxNQUFNLENBQUMsTUFBTSxDQUNYLFVBQVUsRUFBRSxVQUFVLEVBQ3RCLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLElBQUksRUFBRSxXQUFXLEVBQ2pCLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLEtBQUssRUFBRSxNQUFNLEdBQ1osZUFBZSxDQVdqQjtJQUVEOzs7Ozs7Ozs7Ozs7OztPQWNHO0lBQ0gsU0FBUyxJQUFJLE1BQU0sQ0F1QmxCO1lBVWEsdUJBQXVCO1lBMER2QixXQUFXO0lBMkJ6Qjs7OztPQUlHO0lBQ0gsT0FBTyxDQUFDLGdCQUFnQjtJQStCeEI7Ozs7Ozs7Ozs7Ozs7OztPQWVHO0lBQ0gsWUFBWSxDQUFDLFFBQVEsRUFBRSxrQkFBa0IsR0FBRyxNQUFNLElBQUksQ0FRckQ7SUFFRDs7OztPQUlHO0lBQ0gsY0FBYyxJQUFJLE9BQU8sQ0FFeEI7SUFFRDs7Ozs7Ozs7Ozs7OztPQWFHO0lBQ0csVUFBVSxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0EyQmhDO0NBQ0YifQ==

package/dest/providers/extension/extension_wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension_wallet.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/extension_wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,wBAAwB,CAAC;AAsBnE;;;GAGG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW;IALrB,OAAO,CAAC,QAAQ,CAAoD;IAEpE,OAAO,eAIH;IAEJ;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA6D9E;IAED,OAAO,CAAC,WAAW;CAiBpB"}
+{"version":3,"file":"extension_wallet.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/extension_wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,wBAAwB,CAAC;AAOnE,OAAO,EAAE,KAAK,UAAU,EAA8D,MAAM,gBAAgB,CAAC;AAa7G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAe;IAexB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,SAAS;IAlBnB,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,mBAAmB,CAA4B;IAEvD;;;;;;;OAOG;IACH,OAAO,eAMH;IAEJ,mCAAmC;IACnC,OAAO,CAAC,WAAW,CAAuB;IAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,MAAM,CACX,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GACZ,eAAe,CAWjB;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,IAAI,MAAM,CAuBlB;YAUa,uBAAuB;YA0DvB,WAAW;IA2BzB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAQrD;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;;;OAaG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA2BhC;CACF"}

package/dest/providers/extension/extension_wallet.js

@@ -2,63 +2,125 @@ import { WalletSchema } from '@aztec/aztec.js/wallet';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 import { schemaHasMethod } from '@aztec/foundation/schemas';
+import { decrypt, encrypt } from '../../crypto.js';
+import { WalletMessageType } from '../../types.js';
 /**
  * A wallet implementation that communicates with browser extension wallets
- * Supports multiple extensions by targeting specific extension IDs
+ * using a secure encrypted MessageChannel.
+ *
+ * This class uses a pre-established secure channel from the discovery phase:
+ *
+ * 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 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.
+ *
+ * @example
+ * ```typescript
+ * // 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(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();
+ * ```
  */ export class ExtensionWallet {
     chainInfo;
     appId;
     extensionId;
-    inFlight;
-    constructor(chainInfo, appId, extensionId){
+    port;
+    sharedKey;
+    /** Map of pending requests awaiting responses, keyed by message ID */ inFlight;
+    disconnected;
+    disconnectCallbacks;
+    /**
+   * 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
+   */ constructor(chainInfo, appId, extensionId, port, sharedKey){
         this.chainInfo = chainInfo;
         this.appId = appId;
         this.extensionId = extensionId;
+        this.port = port;
+        this.sharedKey = sharedKey;
         this.inFlight = new Map();
+        this.disconnected = false;
+        this.disconnectCallbacks = [];
+        this.walletProxy = null;
     }
+    /** Cached Wallet proxy instance */ walletProxy;
     /**
-   * 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
-   */ static create(chainInfo, appId, extensionId) {
-        const wallet = new ExtensionWallet(chainInfo, appId, extensionId);
-        // Set up message listener for responses from extensions
-        window.addEventListener('message', (event)=>{
-            if (event.source !== window) {
-                return;
-            }
-            let data;
-            try {
-                data = JSON.parse(event.data);
-            } catch  {
-                return;
-            }
-            // Ignore request messages (only process responses)
-            if ('type' in data) {
-                return;
-            }
-            const { messageId, result, error, walletId: responseWalletId } = data;
-            if (!messageId || !responseWalletId) {
-                return;
-            }
-            if (wallet.extensionId !== responseWalletId) {
-                return;
-            }
-            if (!wallet.inFlight.has(messageId)) {
-                return;
-            }
-            const { resolve, reject } = wallet.inFlight.get(messageId);
-            if (error) {
-                reject(new Error(jsonStringify(error)));
-            } else {
-                resolve(result);
-            }
-            wallet.inFlight.delete(messageId);
-        });
+   * Creates an ExtensionWallet instance that communicates with a browser extension
+   * over a secure encrypted MessageChannel.
+   *
+   * @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 The ExtensionWallet instance. Use {@link getWallet} to get the Wallet interface.
+   *
+   * @example
+   * ```typescript
+   * 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(walletInfo, chainInfo, port, sharedKey, appId) {
+        const wallet = new ExtensionWallet(chainInfo, appId, walletInfo.id, port, sharedKey);
+        // Set up message handler - all messages are now encrypted
+        wallet.port.onmessage = (event)=>{
+            void wallet.handleEncryptedResponse(event.data);
+        };
+        wallet.port.start();
+        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() {
+        if (this.walletProxy) {
+            return this.walletProxy;
+        }
         // Create a Proxy that intercepts wallet method calls and forwards them to the extension
-        return new Proxy(wallet, {
+        this.walletProxy = new Proxy(this, {
             get: (target, prop)=>{
                 if (schemaHasMethod(WalletSchema, prop.toString())) {
                     return async (...args)=>{
@@ -73,8 +135,65 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
                 }
             }
         });
+        return this.walletProxy;
+    }
+    /**
+   * 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
+   */ async handleEncryptedResponse(encrypted) {
+        if (!this.sharedKey) {
+            return;
+        }
+        try {
+            const response = await decrypt(this.sharedKey, encrypted);
+            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 === WalletMessageType.SESSION_DISCONNECTED) {
+                this.handleDisconnect();
+                return;
+            }
+            if (!messageId || !responseWalletId) {
+                return;
+            }
+            if (this.extensionId !== responseWalletId) {
+                return;
+            }
+            if (!this.inFlight.has(messageId)) {
+                return;
+            }
+            const { resolve, reject } = this.inFlight.get(messageId);
+            if (error) {
+                reject(new Error(jsonStringify(error)));
+            } else {
+                resolve(result);
+            }
+            this.inFlight.delete(messageId);
+        // eslint-disable-next-line no-empty
+        } catch  {}
     }
-    postMessage(call) {
+    /**
+   * Sends an encrypted wallet method call over the secure MessageChannel.
+   *
+   * The message is encrypted using AES-256-GCM with the shared key derived
+   * during discovery. 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 or wallet is disconnected
+   */ async postMessage(call) {
+        if (this.disconnected) {
+            throw new Error('Wallet has been disconnected');
+        }
+        if (!this.port || !this.sharedKey) {
+            throw new Error('Secure channel not established');
+        }
         const messageId = globalThis.crypto.randomUUID();
         const message = {
             type: call.type,
@@ -84,7 +203,9 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
             appId: this.appId,
             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();
         this.inFlight.set(messageId, {
             promise,
@@ -93,4 +214,105 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
         });
         return promise;
     }
+    /**
+   * Handles wallet disconnection.
+   * Rejects all pending requests and notifies registered callbacks.
+   * @internal
+   */ handleDisconnect() {
+        if (this.disconnected) {
+            return;
+        }
+        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 in callbacks
+            }
+        }
+    }
+    /**
+   * Registers a callback to be invoked when the wallet disconnects.
+   *
+   * @param callback - Function to call when wallet disconnects
+   * @returns A function to unregister the callback
+   *
+   * @example
+   * ```typescript
+   * const wallet = await ExtensionWallet.create(...);
+   * const unsubscribe = wallet.onDisconnect(() => {
+   *   console.log('Wallet disconnected! Please reconnect.');
+   *   // Clean up UI, prompt user to reconnect, etc.
+   * });
+   * // Later: unsubscribe(); to stop receiving notifications
+   * ```
+   */ onDisconnect(callback) {
+        this.disconnectCallbacks.push(callback);
+        return ()=>{
+            const index = this.disconnectCallbacks.indexOf(callback);
+            if (index !== -1) {
+                this.disconnectCallbacks.splice(index, 1);
+            }
+        };
+    }
+    /**
+   * Returns whether the wallet has been disconnected.
+   *
+   * @returns true if the wallet is no longer connected
+   */ isDisconnected() {
+        return this.disconnected;
+    }
+    /**
+   * Disconnects from the wallet and cleans up resources.
+   *
+   * This method notifies the wallet extension that the session is ending,
+   * allowing it to clean up its state. After calling this method, the wallet
+   * instance can no longer be used and any pending requests will be rejected.
+   *
+   * @example
+   * ```typescript
+   * const wallet = await provider.connect('my-app');
+   * // ... use wallet ...
+   * await wallet.disconnect(); // Clean disconnect when done
+   * ```
+   */ async disconnect() {
+        if (this.disconnected) {
+            return;
+        }
+        // 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/dest/providers/extension/index.d.ts

@@ -1,4 +1,6 @@
-export { ExtensionWallet } from './extension_wallet.js';
-export { ExtensionProvider } from './extension_provider.js';
-export type { WalletInfo, WalletMessage, WalletResponse, DiscoveryRequest, DiscoveryResponse } from '../types.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wcm92aWRlcnMvZXh0ZW5zaW9uL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN4RCxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUM1RCxZQUFZLEVBQUUsVUFBVSxFQUFFLGFBQWEsRUFBRSxjQUFjLEVBQUUsZ0JBQWdCLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxhQUFhLENBQUMifQ==
+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';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wcm92aWRlcnMvZXh0ZW5zaW9uL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxlQUFlLEVBQUUsS0FBSyxrQkFBa0IsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ2pGLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxLQUFLLGdCQUFnQixFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDbkYsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUNuRCxZQUFZLEVBQUUsVUFBVSxFQUFFLGFBQWEsRUFBRSxjQUFjLEVBQUUsZ0JBQWdCLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQyJ9

package/dest/providers/extension/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnF,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}