@aztec/wallet-sdk 0.0.1-commit.b6e433891 → 0.0.1-commit.b9865e97

package/src/iframe/provider/iframe_provider.ts

@@ -0,0 +1,331 @@
+/**
+ * IframeWalletProvider — implements {@link WalletProvider} for web wallets loaded in iframes.
+ *
+ * Flow (mirrors ExtensionProvider):
+ *   1. Creates an `<iframe src="walletUrl">` (in app-provided container or floating panel)
+ *   2. Waits for WALLET_READY message from the iframe
+ *   3. Sends DISCOVERY → waits for DISCOVERY_RESPONSE
+ *   4. Sends KEY_EXCHANGE_REQUEST (ECDH public key) → waits for KEY_EXCHANGE_RESPONSE
+ *   5. Derives shared session keys, exposes verificationHash
+ *   6. On confirm(): returns IframeWallet backed by the established session
+ */
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+
+import {
+  type ExportedPublicKey,
+  deriveSessionKeys,
+  exportPublicKey,
+  generateKeyPair,
+  importPublicKey,
+} from '../../crypto.js';
+import type { PendingConnection, ProviderDisconnectionCallback, WalletProvider } from '../../manager/types.js';
+import type { WalletInfo } from '../../types.js';
+import { WalletMessageType } from '../../types.js';
+import { IframeWallet } from './iframe_wallet.js';
+
+const READY_TIMEOUT_MS = 15_000;
+const DISCOVERY_TIMEOUT_MS = 15_000;
+const KEY_EXCHANGE_TIMEOUT_MS = 15_000;
+
+/**
+ * Options for {@link IframeWalletProvider.establishSecureChannel}.
+ */
+export interface IframeConnectionOptions {
+  /** Container element to inject the iframe into. If omitted, a floating panel is created. */
+  container?: HTMLElement;
+}
+
+/**
+ * A {@link WalletProvider} that connects to a web wallet loaded in a cross-origin iframe.
+ *
+ * Discovered via {@link discoverWebWallets} and used through the standard
+ * `WalletProvider.establishSecureChannel()` flow.
+ */
+export class IframeWalletProvider implements WalletProvider {
+  readonly type = 'web' as const;
+
+  private iframe: HTMLIFrameElement | null = null;
+  private _container: HTMLDivElement | null = null;
+  private _appOwnsContainer = false;
+  private _dragCleanup: (() => void) | null = null;
+  private wallet: IframeWallet | null = null;
+  private _disconnected = false;
+  private disconnectCallbacks: ProviderDisconnectionCallback[] = [];
+
+  constructor(
+    /** Unique wallet identifier. */
+    public readonly id: string,
+    /** Display name for the wallet. */
+    public readonly name: string,
+    /** Optional wallet icon URL. */
+    public readonly icon: string | undefined,
+    private readonly walletUrl: string,
+    private readonly chainInfo: ChainInfo,
+  ) {}
+
+  /**
+   * Establishes a secure encrypted channel with the iframe wallet.
+   *
+   * @param appId - Application identifier for the requesting dApp
+   * @param options - Optional container element for the iframe
+   * @returns A {@link PendingConnection} with verification hash and confirm/cancel
+   */
+  async establishSecureChannel(appId: string, options?: IframeConnectionOptions): Promise<PendingConnection> {
+    const iframe = document.createElement('iframe');
+    iframe.src = this.walletUrl;
+    iframe.style.cssText = 'flex:1;border:none;width:100%;height:100%;display:block;';
+    iframe.allow = 'storage-access; cross-origin-isolated';
+    this.iframe = iframe;
+
+    if (options?.container) {
+      this._appOwnsContainer = true;
+      options.container.appendChild(iframe);
+    } else {
+      this.createFloatingPanel(iframe);
+    }
+
+    const walletOrigin = new URL(this.walletUrl).origin;
+
+    const post = (msg: object) => {
+      if (!iframe.contentWindow) {
+        throw new Error('Iframe not ready');
+      }
+      iframe.contentWindow.postMessage(msg, walletOrigin);
+    };
+
+    await waitForMessage(msg => msg.type === WalletMessageType.WALLET_READY, READY_TIMEOUT_MS, walletOrigin);
+
+    const requestId = globalThis.crypto.randomUUID();
+    post({ type: WalletMessageType.DISCOVERY, requestId, appId });
+
+    const discoveryResp = await waitForMessage(
+      msg => msg.type === WalletMessageType.DISCOVERY_RESPONSE && msg.requestId === requestId,
+      DISCOVERY_TIMEOUT_MS,
+      walletOrigin,
+    );
+
+    const walletInfo = discoveryResp.walletInfo as WalletInfo;
+
+    const keyPair = await generateKeyPair();
+    const dAppPublicKey = await exportPublicKey(keyPair.publicKey);
+    post({ type: WalletMessageType.KEY_EXCHANGE_REQUEST, requestId, publicKey: dAppPublicKey });
+
+    const keyExchangeResp = await waitForMessage(
+      msg => msg.type === WalletMessageType.KEY_EXCHANGE_RESPONSE && msg.requestId === requestId,
+      KEY_EXCHANGE_TIMEOUT_MS,
+      walletOrigin,
+    );
+
+    const walletPublicKey = await importPublicKey(keyExchangeResp.publicKey as ExportedPublicKey);
+    const sessionKeys = await deriveSessionKeys(keyPair, walletPublicKey, true);
+    const { verificationHash, encryptionKey: sharedKey } = sessionKeys;
+
+    const iframeWallet = IframeWallet.create(
+      walletInfo.id,
+      requestId, // sessionId
+      iframe.contentWindow!,
+      walletOrigin,
+      sharedKey,
+      this.chainInfo,
+      appId,
+    );
+
+    this.wallet = iframeWallet;
+
+    iframeWallet.onDisconnect(() => {
+      this._disconnected = true;
+      for (const cb of this.disconnectCallbacks) {
+        try {
+          cb();
+        } catch {
+          // ignore
+        }
+      }
+    });
+
+    let cancelled = false;
+
+    return {
+      verificationHash,
+      confirm: (): Promise<Wallet> => {
+        if (cancelled) {
+          throw new Error('Connection was cancelled');
+        }
+        return Promise.resolve(iframeWallet.asWallet());
+      },
+      cancel: () => {
+        cancelled = true;
+        this.cleanup();
+      },
+    };
+  }
+
+  disconnect(): Promise<void> {
+    if (this.wallet && !this.wallet.isDisconnected()) {
+      this.wallet.disconnect();
+    }
+    this.cleanup();
+    return Promise.resolve();
+  }
+
+  onDisconnect(callback: ProviderDisconnectionCallback): () => void {
+    this.disconnectCallbacks.push(callback);
+    return () => {
+      const i = this.disconnectCallbacks.indexOf(callback);
+      if (i !== -1) {
+        this.disconnectCallbacks.splice(i, 1);
+      }
+    };
+  }
+
+  isDisconnected(): boolean {
+    return this._disconnected;
+  }
+
+  // ── Floating panel creation ─────────────────────────────────────────────────
+
+  private createFloatingPanel(iframe: HTMLIFrameElement): void {
+    const W = 420,
+      H = 500;
+    const initLeft = window.innerWidth - W - 24;
+    const initTop = window.innerHeight - H - 24;
+
+    const container = document.createElement('div');
+    container.style.cssText = `
+      position:fixed;left:${initLeft}px;top:${initTop}px;width:${W}px;height:${H}px;
+      border-radius:12px;box-shadow:0 8px 32px rgba(0,0,0,0.4);z-index:999999;
+      overflow:hidden;display:flex;flex-direction:column;user-select:none;
+    `;
+
+    const dragHandle = document.createElement('div');
+    dragHandle.style.cssText = `
+      height:28px;min-height:28px;background:rgba(30,30,30,0.95);cursor:grab;
+      display:flex;align-items:center;justify-content:center;
+      border-bottom:1px solid rgba(255,255,255,0.08);flex-shrink:0;
+    `;
+    dragHandle.innerHTML = `<span style="color:rgba(255,255,255,0.3);font-size:14px;letter-spacing:4px">&#8942;&#8942;&#8942;</span>`;
+
+    const resizeHandle = document.createElement('div');
+    resizeHandle.style.cssText =
+      'position:absolute;bottom:0;right:0;width:16px;height:16px;cursor:se-resize;z-index:1;';
+    resizeHandle.innerHTML = `<svg width="16" height="16" style="opacity:0.3;display:block"><path d="M2 14 L14 2 M6 14 L14 6 M10 14 L14 10" stroke="white" stroke-width="1.5"/></svg>`;
+
+    container.appendChild(dragHandle);
+    container.appendChild(iframe);
+    container.appendChild(resizeHandle);
+    document.body.appendChild(container);
+    this._container = container;
+
+    let dragging = false;
+    let dragOffsetX = 0,
+      dragOffsetY = 0;
+
+    dragHandle.addEventListener('mousedown', (e: MouseEvent) => {
+      dragging = true;
+      dragHandle.style.cursor = 'grabbing';
+      const rect = container.getBoundingClientRect();
+      dragOffsetX = e.clientX - rect.left;
+      dragOffsetY = e.clientY - rect.top;
+      iframe.style.pointerEvents = 'none';
+      e.preventDefault();
+    });
+
+    let resizing = false;
+    let resizeStartX = 0,
+      resizeStartY = 0;
+    let resizeStartW = 0,
+      resizeStartH = 0;
+    const MIN_W = 280,
+      MIN_H = 320;
+
+    resizeHandle.addEventListener('mousedown', (e: MouseEvent) => {
+      resizing = true;
+      resizeStartX = e.clientX;
+      resizeStartY = e.clientY;
+      resizeStartW = container.offsetWidth;
+      resizeStartH = container.offsetHeight;
+      iframe.style.pointerEvents = 'none';
+      e.preventDefault();
+      e.stopPropagation();
+    });
+
+    const onMouseMove = (e: MouseEvent) => {
+      if (dragging) {
+        const newLeft = Math.max(0, Math.min(window.innerWidth - container.offsetWidth, e.clientX - dragOffsetX));
+        const newTop = Math.max(0, Math.min(window.innerHeight - container.offsetHeight, e.clientY - dragOffsetY));
+        container.style.left = `${newLeft}px`;
+        container.style.top = `${newTop}px`;
+      } else if (resizing) {
+        const newW = Math.max(MIN_W, resizeStartW + (e.clientX - resizeStartX));
+        const newH = Math.max(MIN_H, resizeStartH + (e.clientY - resizeStartY));
+        container.style.width = `${newW}px`;
+        container.style.height = `${newH}px`;
+      }
+    };
+
+    const onMouseUp = () => {
+      if (dragging) {
+        dragHandle.style.cursor = 'grab';
+      }
+      dragging = false;
+      resizing = false;
+      iframe.style.pointerEvents = '';
+    };
+
+    document.addEventListener('mousemove', onMouseMove);
+    document.addEventListener('mouseup', onMouseUp);
+    this._dragCleanup = () => {
+      document.removeEventListener('mousemove', onMouseMove);
+      document.removeEventListener('mouseup', onMouseUp);
+    };
+  }
+
+  private cleanup(): void {
+    this._dragCleanup?.();
+    this._dragCleanup = null;
+
+    if (this._appOwnsContainer) {
+      if (this.iframe && this.iframe.parentNode) {
+        this.iframe.parentNode.removeChild(this.iframe);
+      }
+    } else if (this._container && this._container.parentNode) {
+      this._container.parentNode.removeChild(this._container);
+    }
+
+    this._container = null;
+    this.iframe = null;
+  }
+}
+
+/** @internal */
+function waitForMessage(
+  predicate: (msg: Record<string, unknown>) => boolean,
+  timeoutMs: number,
+  expectedOrigin: string,
+): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener('message', handler);
+      reject(new Error(`Iframe wallet: timed out waiting for message (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    /** Handles incoming postMessage events, filtering by origin and predicate. */
+    function handler(event: MessageEvent) {
+      if (event.origin !== expectedOrigin) {
+        return;
+      }
+      const msg = event.data;
+      if (!msg || typeof msg !== 'object') {
+        return;
+      }
+      if (predicate(msg as Record<string, unknown>)) {
+        clearTimeout(timer);
+        window.removeEventListener('message', handler);
+        resolve(msg as Record<string, unknown>);
+      }
+    }
+
+    window.addEventListener('message', handler);
+  });
+}

package/src/iframe/provider/iframe_wallet.ts

@@ -0,0 +1,323 @@
+/**
+ * IframeWallet — Wallet proxy that communicates with a web wallet loaded in an iframe.
+ *
+ * This mirrors {@link ExtensionWallet} from `@aztec/wallet-sdk/extension/provider` but uses
+ * `window.postMessage` / `window.addEventListener('message')` instead of MessagePort.
+ *
+ * The wire protocol (encrypted {@link WalletMessage} / {@link WalletResponse}) is identical.
+ */
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { type Wallet, WalletSchema } from '@aztec/aztec.js/wallet';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import { getSchemaReturnType, schemaHasMethod } from '@aztec/foundation/schemas';
+import type { FunctionsOf } from '@aztec/foundation/types';
+
+import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
+import {
+  DEFAULT_HEARTBEAT_DEAD_AFTER_MS,
+  DEFAULT_HEARTBEAT_INTERVAL_MS,
+  type DisconnectCallback,
+  type HeartbeatOptions,
+  NOOP_LOGGER,
+  type WalletMessage,
+  WalletMessageType,
+  type WalletResponse,
+  type WalletSdkLogger,
+} from '../../types.js';
+
+/**
+ * Internal type representing a wallet method call before encryption.
+ * @internal
+ */
+type WalletMethodCall = {
+  /** Wallet method name to invoke. */
+  type: keyof FunctionsOf<Wallet>;
+  /** Arguments to pass to the wallet method. */
+  args: unknown[];
+};
+
+/**
+ * A wallet implementation that communicates with a web wallet loaded in an iframe
+ * using encrypted postMessage.
+ *
+ * Uses the same Proxy pattern as {@link ExtensionWallet}: intercepts property access,
+ * checks if the property is a Wallet method via {@link WalletSchema}, and routes the
+ * call through an encrypted postMessage channel.
+ *
+ * @example
+ * ```typescript
+ * const wallet = IframeWallet.create(walletId, sessionId, iframeWindow, walletOrigin, sharedKey, chainInfo, appId);
+ * const accounts = await wallet.asWallet().getAccounts();
+ * ```
+ */
+export class IframeWallet {
+  private inFlight = new Map<string, PromiseWithResolvers<unknown>>();
+  private disconnected = false;
+  private disconnectCallbacks: DisconnectCallback[] = [];
+  private messageListener: ((e: MessageEvent) => void) | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastInboundAt = 0;
+  private log: WalletSdkLogger;
+  private heartbeatIntervalMs: number;
+  private heartbeatDeadAfterMs: number;
+
+  private constructor(
+    private chainInfo: ChainInfo,
+    private appId: string,
+    private walletId: string,
+    private sessionId: string,
+    private iframeWindow: Window,
+    private walletOrigin: string,
+    private sharedKey: CryptoKey,
+    logger?: WalletSdkLogger,
+    heartbeatOptions?: HeartbeatOptions,
+  ) {
+    this.log = logger ?? NOOP_LOGGER;
+    this.heartbeatIntervalMs = heartbeatOptions?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.heartbeatDeadAfterMs = heartbeatOptions?.deadAfterMs ?? DEFAULT_HEARTBEAT_DEAD_AFTER_MS;
+  }
+
+  /**
+   * Creates a proxied IframeWallet that implements the {@link Wallet} interface.
+   *
+   * All Wallet method calls are intercepted by a Proxy, encrypted with the shared
+   * AES-256-GCM key, sent via postMessage, and the response is decrypted and
+   * validated against {@link WalletSchema}.
+   *
+   * @param walletId - Unique identifier of the remote wallet
+   * @param sessionId - Session identifier from the key exchange
+   * @param iframeWindow - The iframe's contentWindow to post messages to
+   * @param walletOrigin - Origin of the wallet iframe (for postMessage targeting)
+   * @param sharedKey - AES-256-GCM key derived from ECDH key exchange
+   * @param chainInfo - Network information (chainId and version)
+   * @param appId - Application identifier for the requesting dApp
+   * @param logger - Optional logger; defaults to a no-op logger to keep extension/page bundles small
+   * @param heartbeatOptions - Optional override for heartbeat tuning (mostly useful for tests)
+   * @returns A proxied IframeWallet — call `.asWallet()` to get the typed `Wallet`
+   */
+  static create(
+    walletId: string,
+    sessionId: string,
+    iframeWindow: Window,
+    walletOrigin: string,
+    sharedKey: CryptoKey,
+    chainInfo: ChainInfo,
+    appId: string,
+    logger?: WalletSdkLogger,
+    heartbeatOptions?: HeartbeatOptions,
+  ): IframeWallet {
+    const wallet = new IframeWallet(
+      chainInfo,
+      appId,
+      walletId,
+      sessionId,
+      iframeWindow,
+      walletOrigin,
+      sharedKey,
+      logger,
+      heartbeatOptions,
+    );
+
+    wallet.messageListener = (event: MessageEvent) => {
+      if (event.origin !== walletOrigin) {
+        return;
+      }
+      const msg = event.data;
+      if (!msg || typeof msg !== 'object') {
+        return;
+      }
+
+      if (msg.sessionId !== sessionId) {
+        return;
+      }
+
+      // Any inbound traffic on our session counts as proof of liveness.
+      wallet.lastInboundAt = Date.now();
+
+      if (msg.type === WalletMessageType.SECURE_RESPONSE) {
+        void wallet.handleEncryptedResponse(msg.encrypted as EncryptedPayload);
+      } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED) {
+        wallet.handleDisconnect();
+      }
+    };
+    window.addEventListener('message', wallet.messageListener);
+
+    return new Proxy(wallet, {
+      get: (target, prop, receiver) => {
+        if (prop === 'asWallet') {
+          return () => receiver as unknown as Wallet;
+        } else if (schemaHasMethod(WalletSchema, prop.toString())) {
+          return async (...args: unknown[]) => {
+            const result = await target.postMessage({
+              type: prop.toString() as keyof FunctionsOf<Wallet>,
+              args,
+            });
+            return getSchemaReturnType(WalletSchema[prop.toString() as keyof typeof WalletSchema]).parseAsync(result);
+          };
+        } else {
+          return target[prop as keyof IframeWallet];
+        }
+      },
+    });
+  }
+
+  /**
+   * Returns this wallet as a typed {@link Wallet} interface.
+   * When accessed through the Proxy (via `create()`), returns the proxy itself.
+   */
+  asWallet(): Wallet {
+    return this as unknown as Wallet;
+  }
+
+  private async handleEncryptedResponse(encrypted: EncryptedPayload): Promise<void> {
+    try {
+      const response = await decrypt<WalletResponse>(this.sharedKey, encrypted);
+      const { messageId, result, error, walletId: responseWalletId } = response;
+
+      if (!messageId || responseWalletId !== this.walletId) {
+        return;
+      }
+
+      const pending = this.inFlight.get(messageId);
+      if (!pending) {
+        return;
+      }
+
+      if (error) {
+        pending.reject(new Error(jsonStringify(error)));
+      } else {
+        pending.resolve(result);
+      }
+      this.inFlight.delete(messageId);
+      this.maybeStopHeartbeat();
+    } catch (err) {
+      this.log.warn('Failed to decrypt wallet response', { err });
+    }
+  }
+
+  private async postMessage(call: WalletMethodCall): Promise<unknown> {
+    if (this.disconnected) {
+      throw new Error('Wallet has been disconnected');
+    }
+
+    const messageId = globalThis.crypto.randomUUID();
+    const message: WalletMessage = {
+      type: call.type,
+      args: call.args,
+      messageId,
+      chainInfo: this.chainInfo,
+      appId: this.appId,
+      walletId: this.walletId,
+    };
+
+    const encrypted = await encrypt(this.sharedKey, jsonStringify(message));
+    this.iframeWindow.postMessage(
+      { type: WalletMessageType.SECURE_MESSAGE, sessionId: this.sessionId, encrypted },
+      this.walletOrigin,
+    );
+
+    const { promise, resolve, reject } = promiseWithResolvers<unknown>();
+    this.inFlight.set(messageId, { promise, resolve, reject });
+    this.startHeartbeat();
+    return promise;
+  }
+
+  /**
+   * Start liveness probing while at least one request is in flight. PINGs are
+   * unencrypted control messages — older wallet handlers that don't understand
+   * them simply drop them, but any inbound traffic (PONG, encrypted response,
+   * disconnect notice) resets the idle timer, so a slow-but-alive legacy wallet
+   * never trips a false disconnect.
+   */
+  private startHeartbeat(): void {
+    if (this.heartbeatTimer !== null || this.disconnected) {
+      return;
+    }
+    this.lastInboundAt = Date.now();
+    this.heartbeatTimer = setInterval(() => this.heartbeatTick(), this.heartbeatIntervalMs);
+  }
+
+  private maybeStopHeartbeat(): void {
+    if (this.inFlight.size === 0 && this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private heartbeatTick(): void {
+    if (this.disconnected || this.inFlight.size === 0) {
+      this.maybeStopHeartbeat();
+      return;
+    }
+
+    const idleMs = Date.now() - this.lastInboundAt;
+    if (idleMs >= this.heartbeatDeadAfterMs) {
+      this.log.warn('Iframe wallet channel unresponsive — declaring disconnect', {
+        idleMs,
+        inFlight: this.inFlight.size,
+      });
+      this.handleDisconnect();
+      return;
+    }
+
+    try {
+      this.iframeWindow.postMessage({ type: WalletMessageType.PING, sessionId: this.sessionId }, this.walletOrigin);
+    } catch (err) {
+      this.log.warn('Failed to send heartbeat PING', { err });
+    }
+  }
+
+  private handleDisconnect(): void {
+    if (this.disconnected) {
+      return;
+    }
+    this.disconnected = true;
+
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    if (this.messageListener) {
+      window.removeEventListener('message', this.messageListener);
+      this.messageListener = null;
+    }
+
+    const error = new Error('Wallet disconnected');
+    for (const { reject } of this.inFlight.values()) {
+      reject(error);
+    }
+    this.inFlight.clear();
+
+    for (const cb of this.disconnectCallbacks) {
+      try {
+        cb();
+      } catch {
+        // Ignore errors in disconnect callbacks
+      }
+    }
+  }
+
+  onDisconnect(callback: DisconnectCallback): () => void {
+    this.disconnectCallbacks.push(callback);
+    return () => {
+      const i = this.disconnectCallbacks.indexOf(callback);
+      if (i !== -1) {
+        this.disconnectCallbacks.splice(i, 1);
+      }
+    };
+  }
+
+  isDisconnected(): boolean {
+    return this.disconnected;
+  }
+
+  disconnect(): void {
+    if (this.disconnected) {
+      return;
+    }
+    this.iframeWindow.postMessage({ type: WalletMessageType.DISCONNECT, sessionId: this.sessionId }, this.walletOrigin);
+    this.handleDisconnect();
+  }
+}

package/src/iframe/provider/index.ts

@@ -0,0 +1,3 @@
+export { IframeWallet } from './iframe_wallet.js';
+export { IframeWalletProvider, type IframeConnectionOptions } from './iframe_provider.js';
+export { discoverWebWallets } from './iframe_discovery.js';

package/src/manager/types.ts

@@ -96,6 +96,7 @@ export interface WalletProvider {
    * matches their wallet before calling `confirm()`.
    *
    * @param appId - Application identifier for the requesting dapp
+   * @param options - Optional provider-specific options (e.g. container element for iframe wallets)
    * @returns A pending connection with verification hash and confirm/cancel methods
    *
    * @example
@@ -110,7 +111,7 @@ export interface WalletProvider {
    * const wallet = await pending.confirm();
    * ```
    */
-  establishSecureChannel(appId: string): Promise<PendingConnection>;
+  establishSecureChannel(appId: string, options?: Record<string, unknown>): Promise<PendingConnection>;
   /**
    * Disconnects the current wallet and cleans up resources.
    * After calling this, the wallet returned from confirm() should no longer be used.