@aztec/wallet-sdk 0.0.1-commit.fffb133c → 0.0.1-private.5d121bfd

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,24 +111,24 @@ 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.
    * @returns A promise that resolves when disconnection is complete
    */
-  disconnect?(): Promise<void>;
+  disconnect(): Promise<void>;
   /**
    * Registers a callback to be invoked when the wallet disconnects unexpectedly.
    * @param callback - Function to call when wallet disconnects
    * @returns A function to unregister the callback
    */
-  onDisconnect?(callback: ProviderDisconnectionCallback): () => void;
+  onDisconnect(callback: ProviderDisconnectionCallback): () => void;
   /**
    * Returns whether the provider's wallet connection has been disconnected.
    * @returns true if the wallet is no longer connected
    */
-  isDisconnected?(): boolean;
+  isDisconnected(): boolean;
 }
 
 /**

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();
     }
 
@@ -196,15 +230,14 @@ export class WalletManager {
         return {
           verificationHash: connection.info.verificationHash!,
           confirm: () => {
-            return Promise.resolve(
-              ExtensionWallet.create(
-                connection.info.id,
-                connection.port,
-                connection.sharedKey,
-                chainInfo,
-                connectAppId,
-              ),
+            extensionWallet = ExtensionWallet.create(
+              connection.info.id,
+              connection.port,
+              connection.sharedKey,
+              chainInfo,
+              connectAppId,
             );
+            return Promise.resolve(extensionWallet.asWallet());
           },
           cancel: () => {
             // Send disconnect to terminate the session on the extension side
@@ -213,7 +246,6 @@ export class WalletManager {
               type: WalletMessageType.DISCONNECT,
               requestId: discoveredWallet.requestId,
             });
-            // Don't close the port - allow retry with fresh key exchange
           },
         };
       },

package/src/types.ts

@@ -17,6 +17,21 @@ 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',
+  /** Liveness probe sent by the dApp while a request is in flight */
+  PING = 'aztec-wallet-ping',
+  /** Liveness response from the wallet. Any inbound message (including a regular
+   * encrypted response) is treated as proof of liveness, so a missing PONG alone
+   * never trips disconnect — the dApp also resets its liveness timer on traffic.
+   */
+  PONG = 'aztec-wallet-pong',
 }
 
 /**
@@ -130,3 +145,60 @@ 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;
+
+/**
+ * Default heartbeat tuning shared by both transports.
+ *
+ * - `intervalMs`: how often the dApp sends PING probes while a request is in flight.
+ * - `deadAfterMs`: how long the channel can stay silent (no PONG, no encrypted
+ *   response, no DISCONNECT) before the dApp declares the wallet unreachable
+ *   and rejects all in-flight requests. Generous enough that long-running
+ *   operations (proveTx, sendTx) on legacy wallets that don't reply to PING
+ *   still succeed — any inbound traffic resets the timer.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+export const DEFAULT_HEARTBEAT_DEAD_AFTER_MS = 300_000;
+
+/** Override knobs for the heartbeat — mostly useful for tests. */
+export interface HeartbeatOptions {
+  /** How often to send PING probes while a request is in flight (ms). */
+  intervalMs?: number;
+  /** Idle ceiling before declaring disconnect (ms). */
+  deadAfterMs?: number;
+}
+
+/**
+ * Minimal logger surface used by the wallet SDK.
+ *
+ * Defined locally so that wallet hosts (browser extensions, iframe wallet pages)
+ * can pass a simple `console`-backed logger without pulling in the full
+ * `@aztec/foundation` logging runtime, which is non-trivial to bundle in those
+ * contexts. Structurally compatible with `Logger` from `@aztec/foundation/log`,
+ * so dApp-side callers can pass that type directly.
+ */
+export interface WalletSdkLogger {
+  /** Diagnostic messages — typically discarded in production. */
+  debug: (message: string, data?: unknown) => void;
+  /** Informational messages — significant lifecycle events. */
+  info: (message: string, data?: unknown) => void;
+  /** Recoverable problems — channel decryption failure, missed heartbeats, etc. */
+  warn: (message: string, data?: unknown) => void;
+  /** Errors that prevent normal operation. */
+  error: (message: string, errOrData?: unknown, data?: unknown) => void;
+}
+
+/**
+ * No-op logger used as the default when callers don't provide one. Discards all
+ * messages — wallet hosts that want diagnostics should pass their own logger.
+ */
+export const NOOP_LOGGER: WalletSdkLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};