@aztec/wallet-sdk 0.0.1-commit.7d4e6cd → 0.0.1-commit.9372f48

package/dest/extension/handlers/index.js

@@ -0,0 +1,10 @@
+/**
+ * Browser-safe exports for extension background and content scripts.
+ *
+ * This module contains ONLY handlers that work in service worker/content script
+ * environments without Node.js polyfills.
+ *
+ * @packageDocumentation
+ */ export { BackgroundConnectionHandler } from './background_connection_handler.js';
+export { ContentScriptConnectionHandler } from './content_script_connection_handler.js';
+export { MessageOrigin } from './internal_message_types.js';

package/dest/extension/handlers/internal_message_types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Internal message types for content script ↔ background communication.
+ * These are NOT part of the public wallet protocol - they are implementation
+ * details for coordinating between extension components.
+ */
+export declare const InternalMessageType: {
+    readonly DISCOVERY_REQUEST: "discovery-request";
+    readonly KEY_EXCHANGE_REQUEST: "key-exchange-request";
+    readonly SECURE_MESSAGE: "secure-message";
+    readonly DISCONNECT_REQUEST: "disconnect-request";
+    readonly DISCOVERY_APPROVED: "discovery-approved";
+    readonly KEY_EXCHANGE_RESPONSE: "key-exchange-response";
+    readonly SECURE_RESPONSE: "secure-response";
+    readonly SESSION_DISCONNECTED: "session-disconnected";
+};
+/**
+ * Message origins for internal extension communication.
+ */
+export declare const MessageOrigin: {
+    readonly BACKGROUND: "background";
+    readonly CONTENT_SCRIPT: "content-script";
+};
+/** Union type of message origins. */
+export type MessageOriginType = (typeof MessageOrigin)[keyof typeof MessageOrigin];
+/**
+ * Message sent from content script to background.
+ */
+export interface ContentScriptMessage {
+    /** Message source identifier. */
+    origin: typeof MessageOrigin.CONTENT_SCRIPT;
+    /** Message type. */
+    type: string;
+    /** Optional session identifier. */
+    sessionId?: string;
+    /** Optional message payload. */
+    content?: unknown;
+}
+/**
+ * Message sent from background to content script.
+ */
+export interface BackgroundMessage {
+    /** Message source identifier. */
+    origin: typeof MessageOrigin.BACKGROUND;
+    /** Message type. */
+    type: string;
+    /** Session identifier. */
+    sessionId: string;
+    /** Optional message payload. */
+    content?: unknown;
+}
+/**
+ * Sender information for messages from browser runtime.
+ */
+export interface MessageSender {
+    /** Tab information if available. */
+    tab?: {
+        /** Tab identifier. */
+        id?: number;
+        /** Tab URL. */
+        url?: string;
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJuYWxfbWVzc2FnZV90eXBlcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2V4dGVuc2lvbi9oYW5kbGVycy9pbnRlcm5hbF9tZXNzYWdlX3R5cGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7O0dBSUc7QUFDSCxlQUFPLE1BQU0sbUJBQW1COzs7Ozs7Ozs7Q0FXdEIsQ0FBQztBQUVYOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGFBQWE7OztDQUdoQixDQUFDO0FBRVgscUNBQXFDO0FBQ3JDLE1BQU0sTUFBTSxpQkFBaUIsR0FBRyxDQUFDLE9BQU8sYUFBYSxDQUFDLENBQUMsTUFBTSxPQUFPLGFBQWEsQ0FBQyxDQUFDO0FBRW5GOztHQUVHO0FBQ0gsTUFBTSxXQUFXLG9CQUFvQjtJQUNuQyxpQ0FBaUM7SUFDakMsTUFBTSxFQUFFLE9BQU8sYUFBYSxDQUFDLGNBQWMsQ0FBQztJQUM1QyxvQkFBb0I7SUFDcEIsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQUNiLG1DQUFtQztJQUNuQyxTQUFTLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDbkIsZ0NBQWdDO0lBQ2hDLE9BQU8sQ0FBQyxFQUFFLE9BQU8sQ0FBQztDQUNuQjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGlCQUFpQjtJQUNoQyxpQ0FBaUM7SUFDakMsTUFBTSxFQUFFLE9BQU8sYUFBYSxDQUFDLFVBQVUsQ0FBQztJQUN4QyxvQkFBb0I7SUFDcEIsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQUNiLDBCQUEwQjtJQUMxQixTQUFTLEVBQUUsTUFBTSxDQUFDO0lBQ2xCLGdDQUFnQztJQUNoQyxPQUFPLENBQUMsRUFBRSxPQUFPLENBQUM7Q0FDbkI7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxhQUFhO0lBQzVCLG9DQUFvQztJQUNwQyxHQUFHLENBQUMsRUFBRTtRQUNKLHNCQUFzQjtRQUN0QixFQUFFLENBQUMsRUFBRSxNQUFNLENBQUM7UUFDWixlQUFlO1FBQ2YsR0FBRyxDQUFDLEVBQUUsTUFBTSxDQUFDO0tBQ2QsQ0FBQztDQUNIIn0=

package/dest/extension/handlers/internal_message_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal_message_types.d.ts","sourceRoot":"","sources":["../../../src/extension/handlers/internal_message_types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;CAWtB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AAEX,qCAAqC;AACrC,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,MAAM,EAAE,OAAO,aAAa,CAAC,cAAc,CAAC;IAC5C,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,MAAM,EAAE,OAAO,aAAa,CAAC,UAAU,CAAC;IACxC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,GAAG,CAAC,EAAE;QACJ,sBAAsB;QACtB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,eAAe;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH"}

package/dest/extension/handlers/internal_message_types.js

@@ -0,0 +1,22 @@
+/**
+ * Internal message types for content script ↔ background communication.
+ * These are NOT part of the public wallet protocol - they are implementation
+ * details for coordinating between extension components.
+ */ export const InternalMessageType = {
+    // Content script → Background
+    DISCOVERY_REQUEST: 'discovery-request',
+    KEY_EXCHANGE_REQUEST: 'key-exchange-request',
+    SECURE_MESSAGE: 'secure-message',
+    DISCONNECT_REQUEST: 'disconnect-request',
+    // Background → Content script
+    DISCOVERY_APPROVED: 'discovery-approved',
+    KEY_EXCHANGE_RESPONSE: 'key-exchange-response',
+    SECURE_RESPONSE: 'secure-response',
+    SESSION_DISCONNECTED: 'session-disconnected'
+};
+/**
+ * Message origins for internal extension communication.
+ */ export const MessageOrigin = {
+    BACKGROUND: 'background',
+    CONTENT_SCRIPT: 'content-script'
+};

package/dest/extension/provider/extension_provider.d.ts

@@ -0,0 +1,107 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { type ConnectedWalletInfo, type WalletInfo } from '../../types.js';
+/**
+ * A discovered wallet before key exchange.
+ * Has basic info and MessagePort, but no shared key yet.
+ *
+ * Call {@link establishSecureChannel} to perform key exchange and get a connected wallet.
+ */
+export declare class DiscoveredWallet {
+    /** Basic wallet information (id, name, icon, version) */
+    readonly info: WalletInfo;
+    /** The MessagePort for private communication with the wallet */
+    readonly port: MessagePort;
+    /** Request ID for correlation */
+    readonly requestId: string;
+    constructor(
+    /** Basic wallet information (id, name, icon, version) */
+    info: WalletInfo, 
+    /** The MessagePort for private communication with the wallet */
+    port: MessagePort, 
+    /** Request ID for correlation */
+    requestId: string);
+    /**
+     * Establishes a secure connection with this wallet.
+     *
+     * This method:
+     * 1. Generates an ECDH key pair
+     * 2. Sends public key to wallet over the MessagePort
+     * 3. Receives wallet's public key
+     * 4. Derives shared secret and computes verification hash locally
+     *
+     * **IMPORTANT**: Has a 2 second timeout for MITM defense.
+     * Both parties must exchange keys relatively quickly.
+     *
+     * The verification hash is computed independently by both parties
+     * and should be displayed to the user for visual comparison.
+     *
+     * @returns Connected wallet with shared key and verification hash
+     * @throws Error if key exchange fails or times out
+     */
+    establishSecureChannel(): Promise<ConnectedWallet>;
+}
+/**
+ * A fully connected wallet with secure channel established.
+ * Available after key exchange completes.
+ */
+export interface ConnectedWallet {
+    /** Full wallet info including public key and verification hash */
+    info: ConnectedWalletInfo;
+    /** The MessagePort for encrypted communication */
+    port: MessagePort;
+    /** The derived AES-256-GCM shared key for encryption */
+    sharedKey: CryptoKey;
+}
+/**
+ * Options for wallet discovery.
+ */
+export interface DiscoveryOptions {
+    /** Application ID making the request */
+    appId: string;
+    /** How long to wait for user approval (ms). Default: 60000 (60s) */
+    timeout?: number;
+    /**
+     * Callback invoked when a wallet is discovered.
+     * Wallets are streamed as users approve them.
+     */
+    onWalletDiscovered?: (wallet: DiscoveredWallet) => void;
+    /**
+     * AbortSignal for cancelling discovery early.
+     * When aborted, cleanup happens immediately instead of waiting for timeout.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Provider for discovering Aztec wallet extensions.
+ *
+ * NOTE: Most users should use WalletManager instead of this class directly.
+ * WalletManager provides a higher-level API with streaming support.
+ *
+ * The connection flow is split into two phases for security:
+ *
+ * 1. **Discovery Phase** ({@link discoverWallets}):
+ *    - Broadcasts a discovery request (NO public keys)
+ *    - Wallet shows pending request to user
+ *    - User must approve before wallet reveals itself
+ *    - Wallets are streamed via callback as they're approved
+ *
+ * 2. **Secure Channel Phase** ({@link DiscoveredWallet.establishSecureChannel}):
+ *    - Performs ECDH key exchange over private MessageChannel
+ *    - Both parties compute verification hash locally
+ *    - Has a 2s timeout for MITM defense
+ *    - Returns connected wallet with shared key and verification hash
+ */
+export declare class ExtensionProvider {
+    /**
+     * Discovers wallet extensions that user has approved.
+     *
+     * Wallets are streamed via the `onWalletDiscovered` callback as users approve them.
+     * The promise resolves when the timeout expires or signal is aborted.
+     *
+     * @param chainInfo - Chain information to check if extensions support this network
+     * @param options - Discovery options including appId, appName, timeout, and callback
+     * @returns Promise that resolves when discovery completes
+     */
+    static discoverWallets(chainInfo: ChainInfo, options: DiscoveryOptions): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3Byb3ZpZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvZXh0ZW5zaW9uL3Byb3ZpZGVyL2V4dGVuc2lvbl9wcm92aWRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUt6RCxPQUFPLEVBQ0wsS0FBSyxtQkFBbUIsRUFLeEIsS0FBSyxVQUFVLEVBRWhCLE1BQU0sZ0JBQWdCLENBQUM7QUFReEI7Ozs7O0dBS0c7QUFDSCxxQkFBYSxnQkFBZ0I7SUFFekIseURBQXlEO2FBQ3pDLElBQUksRUFBRSxVQUFVO0lBQ2hDLGdFQUFnRTthQUNoRCxJQUFJLEVBQUUsV0FBVztJQUNqQyxpQ0FBaUM7YUFDakIsU0FBUyxFQUFFLE1BQU07SUFObkM7SUFDRSx5REFBeUQ7SUFDekMsSUFBSSxFQUFFLFVBQVU7SUFDaEMsZ0VBQWdFO0lBQ2hELElBQUksRUFBRSxXQUFXO0lBQ2pDLGlDQUFpQztJQUNqQixTQUFTLEVBQUUsTUFBTSxFQUMvQjtJQUVKOzs7Ozs7Ozs7Ozs7Ozs7OztPQWlCRztJQUNHLHNCQUFzQixJQUFJLE9BQU8sQ0FBQyxlQUFlLENBQUMsQ0ErQ3ZEO0NBQ0Y7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFdBQVcsZUFBZTtJQUM5QixrRUFBa0U7SUFDbEUsSUFBSSxFQUFFLG1CQUFtQixDQUFDO0lBQzFCLGtEQUFrRDtJQUNsRCxJQUFJLEVBQUUsV0FBVyxDQUFDO0lBQ2xCLHdEQUF3RDtJQUN4RCxTQUFTLEVBQUUsU0FBUyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsZ0JBQWdCO0lBQy9CLHdDQUF3QztJQUN4QyxLQUFLLEVBQUUsTUFBTSxDQUFDO0lBQ2Qsb0VBQW9FO0lBQ3BFLE9BQU8sQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNqQjs7O09BR0c7SUFDSCxrQkFBa0IsQ0FBQyxFQUFFLENBQUMsTUFBTSxFQUFFLGdCQUFnQixLQUFLLElBQUksQ0FBQztJQUN4RDs7O09BR0c7SUFDSCxNQUFNLENBQUMsRUFBRSxXQUFXLENBQUM7Q0FDdEI7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW1CRztBQUNILHFCQUFhLGlCQUFpQjtJQUM1Qjs7Ozs7Ozs7O09BU0c7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLFNBQVMsRUFBRSxTQUFTLEVBQUUsT0FBTyxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E4RHJGO0NBQ0YifQ==

package/dest/extension/provider/extension_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension_provider.d.ts","sourceRoot":"","sources":["../../../src/extension/provider/extension_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAKzD,OAAO,EACL,KAAK,mBAAmB,EAKxB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAQxB;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEzB,yDAAyD;aACzC,IAAI,EAAE,UAAU;IAChC,gEAAgE;aAChD,IAAI,EAAE,WAAW;IACjC,iCAAiC;aACjB,SAAS,EAAE,MAAM;IANnC;IACE,yDAAyD;IACzC,IAAI,EAAE,UAAU;IAChC,gEAAgE;IAChD,IAAI,EAAE,WAAW;IACjC,iCAAiC;IACjB,SAAS,EAAE,MAAM,EAC/B;IAEJ;;;;;;;;;;;;;;;;;OAiBG;IACG,sBAAsB,IAAI,OAAO,CAAC,eAAe,CAAC,CA+CvD;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,WAAW,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxD;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8DrF;CACF"}

package/dest/extension/provider/extension_provider.js

@@ -0,0 +1,160 @@
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+import { deriveSessionKeys, exportPublicKey, generateKeyPair, importPublicKey } from '../../crypto.js';
+import { WalletMessageType } from '../../types.js';
+/** Default discovery timeout - long to give users time to approve */ const DEFAULT_DISCOVERY_TIMEOUT_MS = 60000; // 60 seconds
+/** Key exchange timeout - short, wallet should respond quickly after discovery approval */ const KEY_EXCHANGE_TIMEOUT_MS = 2000; // 2 seconds
+/**
+ * A discovered wallet before key exchange.
+ * Has basic info and MessagePort, but no shared key yet.
+ *
+ * Call {@link establishSecureChannel} to perform key exchange and get a connected wallet.
+ */ export class DiscoveredWallet {
+    info;
+    port;
+    requestId;
+    constructor(/** Basic wallet information (id, name, icon, version) */ info, /** The MessagePort for private communication with the wallet */ port, /** Request ID for correlation */ requestId){
+        this.info = info;
+        this.port = port;
+        this.requestId = requestId;
+    }
+    /**
+   * Establishes a secure connection with this wallet.
+   *
+   * This method:
+   * 1. Generates an ECDH key pair
+   * 2. Sends public key to wallet over the MessagePort
+   * 3. Receives wallet's public key
+   * 4. Derives shared secret and computes verification hash locally
+   *
+   * **IMPORTANT**: Has a 2 second timeout for MITM defense.
+   * Both parties must exchange keys relatively quickly.
+   *
+   * The verification hash is computed independently by both parties
+   * and should be displayed to the user for visual comparison.
+   *
+   * @returns Connected wallet with shared key and verification hash
+   * @throws Error if key exchange fails or times out
+   */ async establishSecureChannel() {
+        const keyPair = await generateKeyPair();
+        const exportedPublicKey = await exportPublicKey(keyPair.publicKey);
+        const { promise, resolve, reject } = promiseWithResolvers();
+        const timeoutId = setTimeout(()=>{
+            reject(new Error('Key exchange timeout'));
+        }, KEY_EXCHANGE_TIMEOUT_MS);
+        this.port.onmessage = async (event)=>{
+            const data = event.data;
+            if (data.type === WalletMessageType.KEY_EXCHANGE_RESPONSE && data.requestId === this.requestId) {
+                clearTimeout(timeoutId);
+                try {
+                    const walletPublicKey = await importPublicKey(data.publicKey);
+                    const session = await deriveSessionKeys(keyPair, walletPublicKey, true);
+                    const connectedInfo = {
+                        ...this.info,
+                        publicKey: data.publicKey,
+                        verificationHash: session.verificationHash
+                    };
+                    resolve({
+                        info: connectedInfo,
+                        port: this.port,
+                        sharedKey: session.encryptionKey
+                    });
+                } catch (err) {
+                    reject(new Error(`Key exchange failed: ${err}`));
+                }
+            }
+        };
+        this.port.start();
+        const keyExchangeRequest = {
+            type: WalletMessageType.KEY_EXCHANGE_REQUEST,
+            requestId: this.requestId,
+            publicKey: exportedPublicKey
+        };
+        this.port.postMessage(keyExchangeRequest);
+        return promise;
+    }
+}
+/**
+ * Provider for discovering Aztec wallet extensions.
+ *
+ * NOTE: Most users should use WalletManager instead of this class directly.
+ * WalletManager provides a higher-level API with streaming support.
+ *
+ * The connection flow is split into two phases for security:
+ *
+ * 1. **Discovery Phase** ({@link discoverWallets}):
+ *    - Broadcasts a discovery request (NO public keys)
+ *    - Wallet shows pending request to user
+ *    - User must approve before wallet reveals itself
+ *    - Wallets are streamed via callback as they're approved
+ *
+ * 2. **Secure Channel Phase** ({@link DiscoveredWallet.establishSecureChannel}):
+ *    - Performs ECDH key exchange over private MessageChannel
+ *    - Both parties compute verification hash locally
+ *    - Has a 2s timeout for MITM defense
+ *    - Returns connected wallet with shared key and verification hash
+ */ export class ExtensionProvider {
+    /**
+   * Discovers wallet extensions that user has approved.
+   *
+   * Wallets are streamed via the `onWalletDiscovered` callback as users approve them.
+   * The promise resolves when the timeout expires or signal is aborted.
+   *
+   * @param chainInfo - Chain information to check if extensions support this network
+   * @param options - Discovery options including appId, appName, timeout, and callback
+   * @returns Promise that resolves when discovery completes
+   */ static discoverWallets(chainInfo, options) {
+        if (options.signal?.aborted) {
+            return Promise.resolve();
+        }
+        const timeout = options.timeout ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+        return new Promise((resolve)=>{
+            const requestId = globalThis.crypto.randomUUID();
+            let timeoutId = null;
+            let completed = false;
+            const finish = ()=>{
+                if (completed) {
+                    return;
+                }
+                completed = true;
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                }
+                window.removeEventListener('message', onMessage);
+                options.signal?.removeEventListener('abort', onAbort);
+                resolve();
+            };
+            const onAbort = ()=>finish();
+            const onMessage = (event)=>{
+                if (completed || event.source !== window) {
+                    return;
+                }
+                let data;
+                try {
+                    data = JSON.parse(event.data);
+                } catch  {
+                    return;
+                }
+                if (data.type !== WalletMessageType.DISCOVERY_RESPONSE || data.requestId !== requestId) {
+                    return;
+                }
+                const port = event.ports?.[0];
+                if (port) {
+                    options.onWalletDiscovered?.(new DiscoveredWallet(data.walletInfo, port, requestId));
+                }
+            };
+            options.signal?.addEventListener('abort', onAbort, {
+                once: true
+            });
+            window.addEventListener('message', onMessage);
+            const discoveryMessage = {
+                type: WalletMessageType.DISCOVERY,
+                requestId,
+                appId: options.appId,
+                chainInfo
+            };
+            window.postMessage(jsonStringify(discoveryMessage), '*');
+            timeoutId = setTimeout(finish, timeout);
+        });
+    }
+}

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

@@ -0,0 +1,131 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { type Wallet } from '@aztec/aztec.js/wallet';
+/**
+ * Callback type for wallet disconnect events.
+ */
+export type DisconnectCallback = () => void;
+/**
+ * A wallet implementation that communicates with browser extension wallets
+ * using an encrypted MessageChannel.
+ *
+ * This class uses a secure channel established after discovery:
+ *
+ * 1. **MessageChannel**: Created during discovery and transferred via window.postMessage.
+ *    Note: The port transfer is visible to page scripts, but security comes from encryption.
+ *
+ * 2. **ECDH Key Exchange**: The shared secret was derived after discovery using
+ *    Elliptic Curve Diffie-Hellman key exchange over the MessagePort.
+ *
+ * 3. **AES-GCM Encryption**: All messages are encrypted using AES-256-GCM,
+ *    providing both confidentiality and authenticity. This is what secures the channel.
+ *
+ * @example
+ * ```typescript
+ * // Discover and establish secure channel to a wallet
+ * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-dapp' });
+ * const connection = await discoveredWallets[0].establishSecureChannel();
+ *
+ * // User can verify emoji if desired
+ * console.log('Verify:', hashToEmoji(connection.info.verificationHash!));
+ *
+ * // Create wallet using the connection
+ * const wallet = ExtensionWallet.create(connection.info.id, connection.port, connection.sharedKey, chainInfo, '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 disconnected;
+    private 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
+     */
+    private constructor();
+    /**
+     * Creates a Wallet that communicates with a browser extension
+     * over a secure encrypted MessageChannel.
+     *
+     * @param extensionId - The unique identifier of the wallet extension
+     * @param port - The MessagePort for encrypted communication with the wallet
+     * @param sharedKey - The derived AES-256-GCM shared key for encryption
+     * @param 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 Wallet interface where all method calls are encrypted
+     *
+     * @example
+     * ```typescript
+     * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-defi-app' });
+     * const connection = await discoveredWallets[0].establishSecureChannel();
+     * const wallet = ExtensionWallet.create(
+     *   connection.info.id,
+     *   connection.port,
+     *   connection.sharedKey,
+     *   chainInfo,
+     *   'my-defi-app'
+     * );
+     *
+     * const accounts = await wallet.getAccounts();
+     * ```
+     */
+    static create(extensionId: string, port: MessagePort, sharedKey: CryptoKey, chainInfo: ChainInfo, appId: string): 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 extensionWallet = ExtensionWallet.create(extensionId, port, sharedKey, chainInfo, 'my-app');
+     * // ... use wallet ...
+     * await extensionWallet.disconnect(); // Clean disconnect when done
+     * ```
+     */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3dhbGxldC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2V4dGVuc2lvbi9wcm92aWRlci9leHRlbnNpb25fd2FsbGV0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx3QkFBd0IsQ0FBQztBQW9CbkU7O0dBRUc7QUFDSCxNQUFNLE1BQU0sa0JBQWtCLEdBQUcsTUFBTSxJQUFJLENBQUM7QUFFNUM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQThCRztBQUNILHFCQUFhLGVBQWU7SUFleEIsT0FBTyxDQUFDLFNBQVM7SUFDakIsT0FBTyxDQUFDLEtBQUs7SUFDYixPQUFPLENBQUMsV0FBVztJQUNuQixPQUFPLENBQUMsSUFBSTtJQUNaLE9BQU8sQ0FBQyxTQUFTO0lBbEJuQixzRUFBc0U7SUFDdEUsT0FBTyxDQUFDLFFBQVEsQ0FBb0Q7SUFDcEUsT0FBTyxDQUFDLFlBQVksQ0FBUztJQUM3QixPQUFPLENBQUMsbUJBQW1CLENBQTRCO0lBRXZEOzs7Ozs7O09BT0c7SUFDSCxPQUFPLGVBTUg7SUFFSjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztPQXlCRztJQUNILE1BQU0sQ0FBQyxNQUFNLENBQ1gsV0FBVyxFQUFFLE1BQU0sRUFDbkIsSUFBSSxFQUFFLFdBQVcsRUFDakIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsS0FBSyxFQUFFLE1BQU0sR0FDWixNQUFNLENBZ0NSO1lBVWEsdUJBQXVCO1lBOEN2QixXQUFXO0lBMEJ6Qjs7OztPQUlHO0lBQ0gsT0FBTyxDQUFDLGdCQUFnQjtJQTBCeEI7Ozs7Ozs7Ozs7Ozs7OztPQWVHO0lBQ0gsWUFBWSxDQUFDLFFBQVEsRUFBRSxrQkFBa0IsR0FBRyxNQUFNLElBQUksQ0FRckQ7SUFFRDs7OztPQUlHO0lBQ0gsY0FBYyxJQUFJLE9BQU8sQ0FFeEI7SUFFRDs7Ozs7Ozs7Ozs7OztPQWFHO0lBRUcsVUFBVSxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FhaEM7Q0FDRiJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension_wallet.d.ts","sourceRoot":"","sources":["../../../src/extension/provider/extension_wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,wBAAwB,CAAC;AAoBnE;;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;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,MAAM,CACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GACZ,MAAM,CAgCR;YAUa,uBAAuB;YA8CvB,WAAW;IA0BzB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAQrD;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;;;OAaG;IAEG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAahC;CACF"}