@aztec/wallet-sdk 0.0.1-commit.0c875d939 → 0.0.1-commit.0ec55a70b

package/src/base-wallet/utils.ts

@@ -1,9 +1,12 @@
 import type { AztecNode } from '@aztec/aztec.js/node';
+import { TxSimulationResultWithAppOffset } from '@aztec/aztec.js/wallet';
 import { MAX_ENQUEUED_CALLS_PER_CALL } from '@aztec/constants';
 import type { ChainInfo } from '@aztec/entrypoints/interfaces';
 import { makeTuple } from '@aztec/foundation/array';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { Tuple } from '@aztec/foundation/serialize';
+import type { ContractNameResolver } from '@aztec/pxe/client/lazy';
+import { displayDebugLogs } from '@aztec/pxe/client/lazy';
 import { generateSimulatedProvingResult } from '@aztec/pxe/simulator';
 import { type FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -72,6 +75,7 @@ async function simulateBatchViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean,
+  getContractName: ContractNameResolver,
 ): Promise<TxSimulationResult> {
   const txContext = new TxContext(chainInfo.chainId, chainInfo.version, gasSettings);
 
@@ -145,6 +149,9 @@ async function simulateBatchViaNode(
     throw publicOutput.revertReason;
   }
 
+  // Display debug logs from the public simulation.
+  await displayDebugLogs(publicOutput.debugLogs, getContractName);
+
   return new TxSimulationResult(privateResult, provingResult.publicInputs, publicOutput, undefined);
 }
 
@@ -169,6 +176,7 @@ export async function simulateViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean = true,
+  getContractName: ContractNameResolver,
 ): Promise<TxSimulationResult[]> {
   const batches: FunctionCall[][] = [];
 
@@ -187,6 +195,7 @@ export async function simulateViaNode(
       gasSettings,
       blockHeader,
       skipFeeEnforcement,
+      getContractName,
     );
     results.push(result);
   }
@@ -206,13 +215,13 @@ export async function simulateViaNode(
  */
 export function buildMergedSimulationResult(
   optimizedResults: TxSimulationResult[],
-  normalResult: TxSimulationResult | null,
-): TxSimulationResult {
+  normalResult: TxSimulationResultWithAppOffset | null,
+): TxSimulationResultWithAppOffset {
   const optimizedReturnValues = optimizedResults.flatMap(r => r.publicOutput?.publicReturnValues ?? []);
   const normalReturnValues = normalResult?.publicOutput?.publicReturnValues ?? [];
   const allReturnValues = [...optimizedReturnValues, ...normalReturnValues];
 
-  const baseResult = normalResult ?? optimizedResults[0];
+  const baseResult: TxSimulationResult = normalResult ?? optimizedResults[0];
 
   const mergedPublicOutput: PublicSimulationOutput | undefined = baseResult.publicOutput
     ? {
@@ -221,10 +230,11 @@ export function buildMergedSimulationResult(
       }
     : undefined;
 
-  return new TxSimulationResult(
+  const merged = new TxSimulationResult(
     baseResult.privateExecutionResult,
     baseResult.publicInputs,
     mergedPublicOutput,
     normalResult?.stats,
   );
+  return TxSimulationResultWithAppOffset.fromResultAndOffset(merged, normalResult?.appCallOffset ?? 0);
 }

package/src/crypto.ts

@@ -497,3 +497,107 @@ export function hashToEmoji(hash: string, count: number = DEFAULT_EMOJI_GRID_SIZ
   }
   return emojis.join('');
 }
+
+// ─── Passphrase-based encryption (PBKDF2 + AES-256-GCM) ───────────────────
+
+/** Default PBKDF2 iteration count. High to compensate for short PINs (~1-2s on modern hardware). */
+const DEFAULT_PBKDF2_ITERATIONS = 2_000_000;
+const PBKDF2_SALT_BYTES = 16;
+const PBKDF2_IV_BYTES = 12;
+
+/**
+ * Derives an AES-256-GCM key from a passphrase using PBKDF2-SHA256.
+ *
+ * @param passphrase - The user-provided passphrase or PIN
+ * @param salt - Random salt bytes
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns An AES-256-GCM CryptoKey
+ */
+export async function deriveKeyFromPassphrase(
+  passphrase: string,
+  salt: Uint8Array,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, [
+    'deriveKey',
+  ]);
+  return crypto.subtle.deriveKey(
+    { name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' },
+    keyMaterial,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/**
+ * Encrypts arbitrary bytes with a passphrase using PBKDF2 + AES-256-GCM.
+ *
+ * Output layout: `[salt (16)] [iv (12)] [ciphertext (...)]`
+ *
+ * @param plaintext - Data to encrypt
+ * @param passphrase - User passphrase or PIN
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns A Uint8Array containing salt + iv + ciphertext
+ */
+export async function encryptWithPassphrase(
+  plaintext: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(PBKDF2_IV_BYTES));
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext as BufferSource),
+  );
+  const result = new Uint8Array(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES + ciphertext.length);
+  result.set(salt, 0);
+  result.set(iv, PBKDF2_SALT_BYTES);
+  result.set(ciphertext, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  return result;
+}
+
+/**
+ * Decrypts data produced by {@link encryptWithPassphrase}.
+ *
+ * @param data - The encrypted blob (salt + iv + ciphertext)
+ * @param passphrase - The passphrase used during encryption
+ * @param iterations - PBKDF2 iteration count (must match encryption)
+ * @returns The decrypted plaintext bytes
+ * @throws On wrong passphrase (AES-GCM auth tag mismatch)
+ */
+export async function decryptWithPassphrase(
+  data: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = data.slice(0, PBKDF2_SALT_BYTES);
+  const iv = data.slice(PBKDF2_SALT_BYTES, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const ciphertext = data.slice(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext as BufferSource));
+}
+
+/**
+ * Converts a Uint8Array to a base64 string.
+ */
+export function uint8ToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Converts a base64 string to a Uint8Array.
+ */
+export function base64ToUint8(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/extension/provider/extension_wallet.ts

@@ -6,7 +6,7 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
 import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
-import { type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+import { type DisconnectCallback, type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
 
 /**
  * Internal type representing a wallet method call before encryption.
@@ -19,11 +19,6 @@ type WalletMethodCall = {
   args: unknown[];
 };
 
-/**
- * Callback type for wallet disconnect events.
- */
-export type DisconnectCallback = () => void;
-
 /**
  * A wallet implementation that communicates with browser extension wallets
  * using an encrypted MessageChannel.
@@ -109,7 +104,7 @@ export class ExtensionWallet {
     sharedKey: CryptoKey,
     chainInfo: ChainInfo,
     appId: string,
-  ): Wallet {
+  ): ExtensionWallet {
     const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey);
 
     // Set up message handler for encrypted responses and unencrypted control messages
@@ -127,8 +122,10 @@ export class ExtensionWallet {
     wallet.port.start();
 
     return new Proxy(wallet, {
-      get: (target, prop) => {
-        if (schemaHasMethod(WalletSchema, prop.toString())) {
+      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>,
@@ -140,7 +137,13 @@ export class ExtensionWallet {
           return target[prop as keyof ExtensionWallet];
         }
       },
-    }) as unknown as Wallet;
+    });
+  }
+
+  asWallet(): Wallet {
+    // Overridden by the proxy in create() to return the proxy itself.
+    // This body is never reached when accessed through create().
+    return this as unknown as Wallet;
   }
 
   /**

package/src/extension/provider/index.ts

@@ -1,4 +1,4 @@
-export { ExtensionWallet, type DisconnectCallback } from './extension_wallet.js';
+export { ExtensionWallet } from './extension_wallet.js';
 export {
   ExtensionProvider,
   type DiscoveredWallet,

package/src/iframe/handlers/iframe_connection_handler.ts

@@ -0,0 +1,328 @@
+/**
+ * IframeConnectionHandler — wallet-side of the cross-origin iframe protocol.
+ *
+ * This mirrors {@link BackgroundConnectionHandler} from `@aztec/wallet-sdk/extension/handlers`
+ * but uses `window.postMessage` instead of browser.runtime messaging.
+ *
+ * Message flow (wallet receives):
+ *   parent → DISCOVERY            → show approval UI → send DISCOVERY_RESPONSE
+ *   parent → KEY_EXCHANGE_REQUEST → ECDH             → send KEY_EXCHANGE_RESPONSE
+ *   parent → SECURE_MESSAGE       → decrypt → Wallet → encrypt → SECURE_RESPONSE
+ *   parent → DISCONNECT           → terminate session
+ *
+ * The wallet announces itself by posting WALLET_READY as soon as the handler starts,
+ * so the dApp knows it can send a discovery request.
+ */
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { createLogger } from '@aztec/aztec.js/log';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import { WalletSchema } from '@aztec/aztec.js/wallet';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { parseWithOptionals, schemaHasMethod } from '@aztec/foundation/schemas';
+
+import {
+  type EncryptedPayload,
+  decrypt,
+  deriveSessionKeys,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  importPublicKey,
+} from '../../crypto.js';
+import { type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+
+/**
+ * A pending discovery request from a dApp (before user approval).
+ */
+export interface PendingSession {
+  /** Unique request identifier */
+  requestId: string;
+  /** Application identifier */
+  appId: string;
+  /** Origin URL of the requesting page */
+  origin: string;
+  /** Approval status */
+  status: 'pending' | 'approved';
+}
+
+/**
+ * An active session (after key exchange).
+ */
+export interface ActiveSession {
+  /** Session identifier (same as the discovery requestId) */
+  sessionId: string;
+  /** AES-256-GCM shared key for this session */
+  sharedKey: CryptoKey;
+  /** Verification hash for emoji display */
+  verificationHash: string;
+  /** Origin URL of the connected dApp */
+  origin: string;
+  /** Application identifier */
+  appId: string;
+}
+
+/**
+ * Configuration for the iframe connection handler.
+ */
+export interface IframeConnectionConfig {
+  /** Unique wallet identifier */
+  walletId: string;
+  /** Display name for the wallet */
+  walletName: string;
+  /** Wallet version string */
+  walletVersion: string;
+  /** Optional wallet icon URL */
+  walletIcon?: string;
+  /** Origins allowed to connect. If empty or undefined, all origins are allowed (dev mode). */
+  allowedOrigins?: string[];
+}
+
+/**
+ * Event callbacks for the iframe connection handler.
+ */
+export interface IframeConnectionCallbacks {
+  /** Called when a new discovery request arrives — wallet can show approval UI */
+  onPendingDiscovery?: (session: PendingSession) => void;
+  /** Called when a session is established (key exchange complete) */
+  onSessionEstablished?: (session: ActiveSession) => void;
+  /** Called when a session is terminated */
+  onSessionTerminated?: (sessionId: string) => void;
+  /** Called when a key exchange completes — show verificationHash as emojis to the user */
+  onVerificationHash?: (verificationHash: string) => void;
+  /**
+   * Resolves the Wallet instance to use for a given dApp and chain.
+   * Called when an encrypted message arrives and needs to be dispatched.
+   */
+  getWallet: (appId: string, chainInfo: ChainInfo) => Promise<Wallet>;
+}
+
+/**
+ * Handles the wallet side of the cross-origin iframe protocol.
+ *
+ * Manages the full lifecycle: discovery, ECDH key exchange, encrypted message
+ * dispatch to a {@link Wallet} instance, and session termination.
+ *
+ * @example
+ * ```typescript
+ * const handler = new IframeConnectionHandler(
+ *   { walletId: 'my-wallet', walletName: 'My Wallet', walletVersion: '1.0.0' },
+ *   {
+ *     onPendingDiscovery: (session) => showApprovalUI(session),
+ *     getWallet: (appId, chainInfo) => createWalletForApp(appId, chainInfo),
+ *   },
+ * );
+ * handler.start();
+ * ```
+ */
+export class IframeConnectionHandler {
+  private pendingSessions = new Map<string, PendingSession>();
+  private activeSessions = new Map<string, ActiveSession>();
+  private log = createLogger('wallet:iframe-handler');
+
+  constructor(
+    private config: IframeConnectionConfig,
+    private callbacks: IframeConnectionCallbacks,
+  ) {}
+
+  start(): void {
+    window.addEventListener('message', this.handleMessage);
+    this.postToParent({ type: WalletMessageType.WALLET_READY });
+    this.log.info('IframeConnectionHandler started, posted WALLET_READY');
+  }
+
+  stop(): void {
+    window.removeEventListener('message', this.handleMessage);
+  }
+
+  approveDiscovery(requestId: string): void {
+    const pending = this.pendingSessions.get(requestId);
+    if (!pending || pending.status !== 'pending') {
+      return;
+    }
+
+    pending.status = 'approved';
+    this.postToOrigin(pending.origin, {
+      type: WalletMessageType.DISCOVERY_RESPONSE,
+      requestId,
+      walletInfo: {
+        id: this.config.walletId,
+        name: this.config.walletName,
+        version: this.config.walletVersion,
+        icon: this.config.walletIcon,
+      },
+    });
+    this.log.info(`Discovery approved for requestId=${requestId}`);
+  }
+
+  rejectDiscovery(requestId: string): void {
+    this.pendingSessions.delete(requestId);
+  }
+
+  terminateSession(sessionId: string): void {
+    const session = this.activeSessions.get(sessionId);
+    if (session) {
+      this.postToOrigin(session.origin, {
+        type: WalletMessageType.SESSION_DISCONNECTED,
+        sessionId,
+      });
+      this.activeSessions.delete(sessionId);
+      this.callbacks.onSessionTerminated?.(sessionId);
+    }
+  }
+
+  getPendingSessions(): PendingSession[] {
+    return Array.from(this.pendingSessions.values()).filter(s => s.status === 'pending');
+  }
+
+  private handleMessage = (event: MessageEvent): void => {
+    void this.handleMessageAsync(event);
+  };
+
+  private async handleMessageAsync(event: MessageEvent): Promise<void> {
+    if (this.config.allowedOrigins && this.config.allowedOrigins.length > 0) {
+      if (!this.config.allowedOrigins.includes(event.origin)) {
+        return;
+      }
+    }
+
+    const msg = event.data;
+    if (!msg || typeof msg !== 'object' || !msg.type) {
+      return;
+    }
+
+    switch (msg.type) {
+      case WalletMessageType.DISCOVERY:
+        this.handleDiscoveryRequest(msg, event.origin);
+        break;
+      case WalletMessageType.KEY_EXCHANGE_REQUEST:
+        await this.handleKeyExchangeRequest(msg, event.origin);
+        break;
+      case WalletMessageType.SECURE_MESSAGE:
+        await this.handleSecureMessage(msg);
+        break;
+      case WalletMessageType.DISCONNECT:
+        this.terminateSession(msg.sessionId);
+        break;
+    }
+  }
+
+  private handleDiscoveryRequest(msg: Record<string, unknown>, origin: string): void {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    const { requestId, appId } = msg as { requestId: string; appId: string };
+    const pending: PendingSession = { requestId, appId, origin, status: 'pending' };
+    this.pendingSessions.set(requestId, pending);
+    this.log.info(`Discovery request from appId=${appId} origin=${origin}`);
+    this.callbacks.onPendingDiscovery?.(pending);
+  }
+
+  private async handleKeyExchangeRequest(msg: Record<string, unknown>, origin: string): Promise<void> {
+    const { requestId, publicKey: appPublicKeyRaw } = msg as {
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      requestId: string;
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      publicKey: { kty: string; crv: string; x: string; y: string };
+    };
+    const pending = this.pendingSessions.get(requestId);
+    if (!pending || pending.status !== 'approved') {
+      this.log.warn(`Key exchange for unknown/unapproved requestId=${requestId}`);
+      return;
+    }
+
+    try {
+      const keyPair = await generateKeyPair();
+      const walletPublicKey = await exportPublicKey(keyPair.publicKey);
+      const appPublicKey = await importPublicKey(appPublicKeyRaw);
+      const sessionKeys = await deriveSessionKeys(keyPair, appPublicKey, false);
+
+      const session: ActiveSession = {
+        sessionId: requestId,
+        sharedKey: sessionKeys.encryptionKey,
+        verificationHash: sessionKeys.verificationHash,
+        origin: pending.origin,
+        appId: pending.appId,
+      };
+
+      this.activeSessions.set(requestId, session);
+      this.pendingSessions.delete(requestId);
+
+      this.postToOrigin(origin, {
+        type: WalletMessageType.KEY_EXCHANGE_RESPONSE,
+        requestId,
+        publicKey: walletPublicKey,
+        verificationHash: sessionKeys.verificationHash,
+      });
+
+      this.callbacks.onVerificationHash?.(sessionKeys.verificationHash);
+      this.callbacks.onSessionEstablished?.(session);
+      this.log.info(`Key exchange complete, sessionId=${requestId}`);
+    } catch (err) {
+      this.log.error(`Key exchange failed: ${err}`);
+    }
+  }
+
+  private async handleSecureMessage(msg: Record<string, unknown>): Promise<void> {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    const { sessionId, encrypted } = msg as { sessionId: string; encrypted: EncryptedPayload };
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+
+    let walletMessage: WalletMessage;
+    try {
+      walletMessage = await decrypt<WalletMessage>(session.sharedKey, encrypted);
+    } catch {
+      this.log.warn(`Decryption failed for sessionId=${sessionId}`);
+      return;
+    }
+
+    const { messageId, type, args, chainInfo, appId } = walletMessage;
+
+    let result: unknown;
+    let error: string | undefined;
+
+    try {
+      const wallet = await this.callbacks.getWallet(appId, chainInfo);
+
+      if (!schemaHasMethod(WalletSchema, type)) {
+        throw new Error(`Unknown wallet method: ${type}`);
+      }
+      // Zod's AnyZodTuple rejects optional tuple items typed as `T | undefined`
+      const sanitizedArgs = await parseWithOptionals(args, WalletSchema[type].parameters() as any);
+      result = await (wallet as Record<string, (...a: unknown[]) => Promise<unknown>>)[type](...sanitizedArgs);
+    } catch (err: unknown) {
+      error = err instanceof Error ? err.message : String(err);
+      this.log.error(`Error handling ${type}: ${error}`);
+    }
+
+    const response: WalletResponse = {
+      messageId,
+      walletId: this.config.walletId,
+      result,
+      error,
+    };
+
+    try {
+      const encryptedResponse = await encrypt(session.sharedKey, jsonStringify(response));
+      this.postToOrigin(session.origin, {
+        type: WalletMessageType.SECURE_RESPONSE,
+        sessionId,
+        encrypted: encryptedResponse,
+      });
+    } catch (err) {
+      this.log.error(`Encryption of response failed: ${err}`);
+    }
+  }
+
+  private postToParent(msg: object): void {
+    if (window.parent !== window) {
+      window.parent.postMessage(msg, '*');
+    }
+  }
+
+  private postToOrigin(origin: string, msg: object): void {
+    if (window.parent !== window) {
+      window.parent.postMessage(msg, origin);
+    }
+  }
+}

package/src/iframe/handlers/index.ts

@@ -0,0 +1,7 @@
+export {
+  IframeConnectionHandler,
+  type IframeConnectionConfig,
+  type IframeConnectionCallbacks,
+  type PendingSession,
+  type ActiveSession,
+} from './iframe_connection_handler.js';