@aztec/wallet-sdk 0.0.1-commit.0208eb9

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"}

package/dest/extension/provider/extension_wallet.js

@@ -0,0 +1,271 @@
+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
+ * 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 class ExtensionWallet {
+    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 = [];
+    }
+    /**
+   * 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, port, sharedKey, chainInfo, appId) {
+        const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey);
+        // Set up message handler for encrypted responses and unencrypted control messages
+        wallet.port.onmessage = (event)=>{
+            const data = event.data;
+            // Check for unencrypted disconnect notification
+            if (data && typeof data === 'object' && 'type' in data && data.type === WalletMessageType.DISCONNECT) {
+                wallet.handleDisconnect();
+                return;
+            }
+            // Otherwise treat as encrypted payload
+            void wallet.handleEncryptedResponse(data);
+        };
+        wallet.port.start();
+        return new Proxy(wallet, {
+            get: (target, prop)=>{
+                if (schemaHasMethod(WalletSchema, prop.toString())) {
+                    return async (...args)=>{
+                        const result = await target.postMessage({
+                            type: prop.toString(),
+                            args
+                        });
+                        return WalletSchema[prop.toString()].returnType().parseAsync(result);
+                    };
+                } else {
+                    return target[prop];
+                }
+            }
+        });
+    }
+    /**
+   * 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;
+            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  {}
+    }
+    /**
+   * 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,
+            args: call.args,
+            messageId,
+            chainInfo: this.chainInfo,
+            appId: this.appId,
+            walletId: this.extensionId
+        };
+        const encrypted = await encrypt(this.sharedKey, jsonStringify(message));
+        this.port.postMessage(encrypted);
+        const { promise, resolve, reject } = promiseWithResolvers();
+        this.inFlight.set(messageId, {
+            promise,
+            resolve,
+            reject
+        });
+        return promise;
+    }
+    /**
+   * Handles wallet disconnection.
+   * Rejects all pending requests and notifies registered callbacks.
+   * @internal
+   */ handleDisconnect() {
+        if (this.disconnected) {
+            return;
+        }
+        this.disconnected = true;
+        if (this.port) {
+            this.port.onmessage = null;
+            this.port.close();
+        }
+        const error = new Error('Wallet disconnected');
+        for (const { reject } of this.inFlight.values()){
+            reject(error);
+        }
+        this.inFlight.clear();
+        for (const callback of this.disconnectCallbacks){
+            try {
+                callback();
+            } catch  {
+            // Ignore errors on disconnect 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 extensionWallet = ExtensionWallet.create(extensionId, port, sharedKey, chainInfo, 'my-app');
+   * // ... use wallet ...
+   * await extensionWallet.disconnect(); // Clean disconnect when done
+   * ```
+   */ // eslint-disable-next-line require-await -- async for interface compatibility
+    async disconnect() {
+        if (this.disconnected) {
+            return;
+        }
+        if (this.port) {
+            // Send unencrypted disconnect - control messages don't need encryption
+            this.port.postMessage({
+                type: WalletMessageType.DISCONNECT
+            });
+        }
+        this.handleDisconnect();
+    }
+}