@aztec/wallet-sdk 4.1.2 → 4.2.0-aztecnr-rc.2

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,229 @@
+/**
+ * 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 { schemaHasMethod } from '@aztec/foundation/schemas';
+import type { FunctionsOf } from '@aztec/foundation/types';
+
+import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
+import { type DisconnectCallback, type WalletMessage, WalletMessageType, type WalletResponse } 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 constructor(
+    private chainInfo: ChainInfo,
+    private appId: string,
+    private walletId: string,
+    private sessionId: string,
+    private iframeWindow: Window,
+    private walletOrigin: string,
+    private sharedKey: CryptoKey,
+  ) {}
+
+  /**
+   * 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
+   * @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,
+  ): IframeWallet {
+    const wallet = new IframeWallet(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey);
+
+    wallet.messageListener = (event: MessageEvent) => {
+      if (event.origin !== walletOrigin) {
+        return;
+      }
+      const msg = event.data;
+      if (!msg || typeof msg !== 'object') {
+        return;
+      }
+
+      if (msg.type === WalletMessageType.SECURE_RESPONSE && msg.sessionId === sessionId) {
+        void wallet.handleEncryptedResponse(msg.encrypted as EncryptedPayload);
+      } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED && msg.sessionId === sessionId) {
+        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 WalletSchema[prop.toString() as keyof typeof WalletSchema].returnType().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);
+    } catch {
+      // Decryption errors are silently ignored (message not for us or corrupted)
+    }
+  }
+
+  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 });
+    return promise;
+  }
+
+  private handleDisconnect(): void {
+    if (this.disconnected) {
+      return;
+    }
+    this.disconnected = true;
+
+    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.

package/src/manager/wallet_manager.ts

@@ -2,6 +2,7 @@ import type { ChainInfo } from '@aztec/aztec.js/account';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 
 import { type DiscoveredWallet, ExtensionProvider, ExtensionWallet } from '../extension/provider/index.js';
+import { discoverWebWallets } from '../iframe/provider/iframe_discovery.js';
 import { WalletMessageType } from '../types.js';
 import type {
   DiscoverWalletsOptions,
@@ -88,6 +89,20 @@ export class WalletManager {
 
     const { promise: donePromise, resolve: resolveDone } = promiseWithResolvers<void>();
 
+    const pendingSources = new Set<string>();
+
+    const emit = (provider: WalletProvider) => {
+      options.onWalletDiscovered?.(provider);
+
+      if (pendingResolve) {
+        const resolve = pendingResolve;
+        pendingResolve = null;
+        resolve({ value: provider, done: false });
+      } else {
+        pendingProviders.push(provider);
+      }
+    };
+
     const markComplete = () => {
       completed = true;
       resolveDone();
@@ -98,7 +113,15 @@ export class WalletManager {
       }
     };
 
+    const sourceComplete = (source: string) => {
+      pendingSources.delete(source);
+      if (pendingSources.size === 0) {
+        markComplete();
+      }
+    };
+
     if (this.config.extensions?.enabled) {
+      pendingSources.add('extensions');
       const extensionConfig = this.config.extensions;
 
       void ExtensionProvider.discoverWallets(chainInfo, {
@@ -107,24 +130,35 @@ export class WalletManager {
         signal: abortController.signal,
         onWalletDiscovered: discoveredWallet => {
           const provider = this.createProviderFromDiscoveredWallet(discoveredWallet, chainInfo, extensionConfig);
-          if (!provider) {
-            return;
+          if (provider) {
+            emit(provider);
           }
+        },
+      }).then(() => sourceComplete('extensions'));
+    }
 
-          // Call user's callback if provided
-          options.onWalletDiscovered?.(provider);
+    if (this.config.webWallets?.urls && this.config.webWallets.urls.length > 0) {
+      pendingSources.add('webWallets');
+      const webSession = discoverWebWallets(this.config.webWallets.urls, chainInfo);
 
-          // Also queue for async iterator
-          if (pendingResolve) {
-            const resolve = pendingResolve;
-            pendingResolve = null;
-            resolve({ value: provider, done: false });
-          } else {
-            pendingProviders.push(provider);
+      // Forward discovered web wallets into the shared iterator
+      void (async () => {
+        try {
+          for await (const provider of webSession.wallets) {
+            if (abortController.signal.aborted) {
+              break;
+            }
+            emit(provider);
           }
-        },
-      }).then(markComplete);
-    } else {
+        } finally {
+          sourceComplete('webWallets');
+        }
+      })();
+
+      abortController.signal.addEventListener('abort', () => webSession.cancel(), { once: true });
+    }
+
+    if (pendingSources.size === 0) {
       markComplete();
     }
 

package/src/types.ts

@@ -17,6 +17,14 @@ export enum WalletMessageType {
   KEY_EXCHANGE_REQUEST = 'aztec-wallet-key-exchange-request',
   /** Key exchange response sent over MessageChannel */
   KEY_EXCHANGE_RESPONSE = 'aztec-wallet-key-exchange-response',
+  /** Wallet ready signal */
+  WALLET_READY = 'aztec-wallet-ready',
+  /** Encrypted wallet message wrapper */
+  SECURE_MESSAGE = 'aztec-wallet-secure-message',
+  /** Encrypted wallet response wrapper */
+  SECURE_RESPONSE = 'aztec-wallet-secure-response',
+  /** Session disconnected notification */
+  SESSION_DISCONNECTED = 'aztec-wallet-session-disconnected',
 }
 
 /**
@@ -130,3 +138,8 @@ export interface KeyExchangeResponse {
   /** Wallet's ECDH public key for deriving shared secret */
   publicKey: ExportedPublicKey;
 }
+
+/**
+ * Callback invoked when a wallet connection is disconnected.
+ */
+export type DisconnectCallback = () => void;