@aztec/wallet-sdk 0.0.1-commit.f295ac2 → 0.0.1-commit.f8ca9b2f3

package/dest/crypto.d.ts

@@ -36,11 +36,23 @@ export interface SecureKeyPair {
     /** Private key - keep secret, used for key derivation */
     privateKey: CryptoKey;
 }
+/**
+ * Session keys derived from ECDH key exchange.
+ *
+ * Contains both the encryption key and the verification hash (verificationHash)
+ * computed from a separate HMAC key.
+ */
+export interface SessionKeys {
+    /** AES-256-GCM key for message encryption/decryption */
+    encryptionKey: CryptoKey;
+    /** Hex-encoded verificationHash for verification */
+    verificationHash: string;
+}
 /**
  * Generates an ECDH P-256 key pair for key exchange.
  *
- * The generated key pair can be used to derive a shared secret with another
- * party's public key using {@link deriveSharedKey}.
+ * The generated key pair can be used to derive session keys with another
+ * party's public key using {@link deriveSessionKeys}.
  *
  * @returns A new ECDH key pair
  *
@@ -72,65 +84,71 @@ export declare function exportPublicKey(publicKey: CryptoKey): Promise<ExportedP
 /**
  * Imports a public key from JWK format.
  *
- * Used to import the other party's public key for deriving a shared secret.
+ * Used to import the other party's public key for deriving session keys.
  *
  * @param exported - The public key in JWK format
- * @returns A CryptoKey that can be used with {@link deriveSharedKey}
+ * @returns A CryptoKey that can be used with {@link deriveSessionKeys}
  *
  * @example
  * ```typescript
- * // Receive exported public key from other party
- * const theirPublicKey = await importPublicKey(receivedPublicKey);
- * const sharedKey = await deriveSharedKey(myPrivateKey, theirPublicKey);
+ * // App side: receive wallet's public key and derive session
+ * const walletPublicKey = await importPublicKey(receivedWalletKey);
+ * const session = await deriveSessionKeys(appKeyPair, walletPublicKey, true);
  * ```
  */
 export declare function importPublicKey(exported: ExportedPublicKey): Promise<CryptoKey>;
 /**
- * Derives a shared AES-256-GCM key from ECDH key exchange.
+ * Derives session keys from ECDH key exchange using HKDF.
+ *
+ * This is the main key derivation function that produces:
+ * 1. An AES-256-GCM encryption key (first 256 bits)
+ * 2. An HMAC key for verificationHash computation (second 256 bits)
+ * 3. A verificationHash computed as HMAC(hmacKey, "aztec-wallet-verification-verificationHash")
  *
- * Both parties will derive the same shared key when using their own private key
- * and the other party's public key. This is the core of ECDH key agreement.
+ * The keys are derived using a single HKDF call that produces 512 bits,
+ * then split into the two keys.
  *
- * @param privateKey - Your ECDH private key
- * @param publicKey - The other party's ECDH public key
- * @returns An AES-256-GCM key for encryption/decryption
+ * @param ownKeyPair - The caller's ECDH key pair (private for ECDH, public for salt)
+ * @param peerPublicKey - The peer's ECDH public key (for ECDH and salt)
+ * @param isApp - true if caller is the app, false if caller is the wallet
+ * @returns Session keys containing encryption key and verificationHash
  *
  * @example
  * ```typescript
- * // Both parties derive the same key
- * const sharedKeyA = await deriveSharedKey(privateKeyA, publicKeyB);
- * const sharedKeyB = await deriveSharedKey(privateKeyB, publicKeyA);
- * // sharedKeyA and sharedKeyB are equivalent
+ * // App side
+ * const sessionA = await deriveSessionKeys(appKeyPair, walletPublicKey, true);
+ * // Wallet side
+ * const sessionB = await deriveSessionKeys(walletKeyPair, appPublicKey, false);
+ * // sessionA.verificationHash === sessionB.verificationHash
  * ```
  */
-export declare function deriveSharedKey(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
+export declare function deriveSessionKeys(ownKeyPair: SecureKeyPair, peerPublicKey: CryptoKey, isApp: boolean): Promise<SessionKeys>;
 /**
  * Encrypts data using AES-256-GCM.
  *
- * The data is JSON serialized before encryption. A random 12-byte IV is
- * generated for each encryption operation.
+ * A random 12-byte IV is generated for each encryption operation.
  *
  * AES-GCM provides both confidentiality and authenticity - any tampering
  * with the ciphertext will cause decryption to fail.
  *
- * @param key - The AES-GCM key (from {@link deriveSharedKey})
- * @param data - The data to encrypt (will be JSON serialized)
+ * @param key - The AES-GCM key (from {@link deriveSessionKeys})
+ * @param data - The string data to encrypt (caller is responsible for serialization)
  * @returns The encrypted payload with IV and ciphertext
  *
  * @example
  * ```typescript
- * const encrypted = await encrypt(sharedKey, { action: 'transfer', amount: 100 });
+ * const encrypted = await encrypt(session.encryptionKey, JSON.stringify({ action: 'transfer', amount: 100 }));
  * // encrypted.iv and encrypted.ciphertext are base64 strings
  * ```
  */
-export declare function encrypt(key: CryptoKey, data: unknown): Promise<EncryptedPayload>;
+export declare function encrypt(key: CryptoKey, data: string): Promise<EncryptedPayload>;
 /**
  * Decrypts data using AES-256-GCM.
  *
  * The decrypted data is JSON parsed before returning.
  *
  * @typeParam T - The expected type of the decrypted data
- * @param key - The AES-GCM key (from {@link deriveSharedKey})
+ * @param key - The AES-GCM key (from {@link deriveSessionKeys})
  * @param payload - The encrypted payload from {@link encrypt}
  * @returns The decrypted and parsed data
  *
@@ -138,46 +156,37 @@ export declare function encrypt(key: CryptoKey, data: unknown): Promise<Encrypte
  *
  * @example
  * ```typescript
- * const decrypted = await decrypt<{ action: string; amount: number }>(sharedKey, encrypted);
+ * const decrypted = await decrypt<{ action: string; amount: number }>(session.encryptionKey, encrypted);
  * console.log(decrypted.action); // 'transfer'
  * ```
  */
 export declare function decrypt<T = unknown>(key: CryptoKey, payload: EncryptedPayload): Promise<T>;
 /**
- * Hashes a shared AES key to a hex string for verification.
- *
- * This extracts the raw key material and hashes it with SHA-256,
- * returning the first 16 bytes as a hex string.
- *
- * @param sharedKey - The AES-GCM shared key (must be extractable)
- * @returns A hex string representation of the hash
- *
- * @example
- * ```typescript
- * const hash = await hashSharedSecret(sharedKey);
- * const emoji = hashToEmoji(hash);
- * ```
+ * Default grid size for emoji verification display.
+ * 3x3 grid = 9 emojis = 72 bits of security.
  */
-export declare function hashSharedSecret(sharedKey: CryptoKey): Promise<string>;
+export declare const DEFAULT_EMOJI_GRID_SIZE = 9;
 /**
  * Converts a hex hash to an emoji sequence for visual verification.
  *
- * This is used for anti-MITM verification - both the dApp and wallet
- * independently compute the same emoji sequence from the shared secret.
+ * This is used for verification - both the dApp and wallet
+ * independently compute the same emoji sequence from the derived keys.
  * Users can visually compare the sequences to detect interception.
  *
- * Similar to SAS (Short Authentication String) in ZRTP/Signal.
+ * With a 256-emoji alphabet and 9 emojis (3x3 grid), this provides
+ * 72 bits of security (9 * 8 = 72 bits), making brute-force attacks
+ * computationally infeasible.
  *
- * @param hash - Hex string from {@link hashSharedSecret}
- * @param length - Number of emojis to generate (default: 4)
+ * @param hash - Hex string from verification hash (64 chars = 32 bytes)
+ * @param count - Number of emojis to generate (default: 9 for 3x3 grid)
  * @returns A string of emojis representing the hash
  *
  * @example
  * ```typescript
- * const hash = await hashSharedSecret(sharedKey);
- * const emoji = hashToEmoji(hash); // e.g., "🔵🦋🎯🐼"
- * // Display to user for verification
+ * const session = await deriveSessionKeys(...);
+ * const emoji = hashToEmoji(session.verificationHash); // e.g., "🔵🦋🎯🐼🌟🎲🦊🐸💎"
+ * // Display as 3x3 grid to user for verification
  * ```
  */
-export declare function hashToEmoji(hash: string, length?: number): string;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3J5cHRvLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY3J5cHRvLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW1DQTs7OztHQUlHO0FBQ0gsTUFBTSxXQUFXLGlCQUFpQjtJQUNoQyxnREFBZ0Q7SUFDaEQsR0FBRyxFQUFFLE1BQU0sQ0FBQztJQUNaLGtDQUFrQztJQUNsQyxHQUFHLEVBQUUsTUFBTSxDQUFDO0lBQ1osdUNBQXVDO0lBQ3ZDLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDVix1Q0FBdUM7SUFDdkMsQ0FBQyxFQUFFLE1BQU0sQ0FBQztDQUNYO0FBRUQ7Ozs7R0FJRztBQUNILE1BQU0sV0FBVyxnQkFBZ0I7SUFDL0IsdURBQXVEO0lBQ3ZELEVBQUUsRUFBRSxNQUFNLENBQUM7SUFDWCxrQ0FBa0M7SUFDbEMsVUFBVSxFQUFFLE1BQU0sQ0FBQztDQUNwQjtBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxXQUFXLGFBQWE7SUFDNUIsaUNBQWlDO0lBQ2pDLFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIseURBQXlEO0lBQ3pELFVBQVUsRUFBRSxTQUFTLENBQUM7Q0FDdkI7QUFFRDs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHdCQUFzQixlQUFlLElBQUksT0FBTyxDQUFDLGFBQWEsQ0FBQyxDQWE5RDtBQUVEOzs7Ozs7Ozs7Ozs7Ozs7R0FlRztBQUNILHdCQUFzQixlQUFlLENBQUMsU0FBUyxFQUFFLFNBQVMsR0FBRyxPQUFPLENBQUMsaUJBQWlCLENBQUMsQ0FRdEY7QUFFRDs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHdCQUFnQixlQUFlLENBQUMsUUFBUSxFQUFFLGlCQUFpQixHQUFHLE9BQU8sQ0FBQyxTQUFTLENBQUMsQ0FnQi9FO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBaUJHO0FBQ0gsd0JBQWdCLGVBQWUsQ0FBQyxVQUFVLEVBQUUsU0FBUyxFQUFFLFNBQVMsRUFBRSxTQUFTLEdBQUcsT0FBTyxDQUFDLFNBQVMsQ0FBQyxDQWMvRjtBQUVEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FrQkc7QUFDSCx3QkFBc0IsT0FBTyxDQUFDLEdBQUcsRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsZ0JBQWdCLENBQUMsQ0FVdEY7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FpQkc7QUFDSCx3QkFBc0IsT0FBTyxDQUFDLENBQUMsR0FBRyxPQUFPLEVBQUUsR0FBRyxFQUFFLFNBQVMsRUFBRSxPQUFPLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLENBQUMsQ0FBQyxDQVFoRztBQW9FRDs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHdCQUFzQixnQkFBZ0IsQ0FBQyxTQUFTLEVBQUUsU0FBUyxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FPNUU7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW1CRztBQUNILHdCQUFnQixXQUFXLENBQUMsSUFBSSxFQUFFLE1BQU0sRUFBRSxNQUFNLEdBQUUsTUFBVSxHQUFHLE1BQU0sQ0FNcEUifQ==
+export declare function hashToEmoji(hash: string, count?: number): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3J5cHRvLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY3J5cHRvLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQThEQTs7OztHQUlHO0FBQ0gsTUFBTSxXQUFXLGlCQUFpQjtJQUNoQyxnREFBZ0Q7SUFDaEQsR0FBRyxFQUFFLE1BQU0sQ0FBQztJQUNaLGtDQUFrQztJQUNsQyxHQUFHLEVBQUUsTUFBTSxDQUFDO0lBQ1osdUNBQXVDO0lBQ3ZDLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDVix1Q0FBdUM7SUFDdkMsQ0FBQyxFQUFFLE1BQU0sQ0FBQztDQUNYO0FBRUQ7Ozs7R0FJRztBQUNILE1BQU0sV0FBVyxnQkFBZ0I7SUFDL0IsdURBQXVEO0lBQ3ZELEVBQUUsRUFBRSxNQUFNLENBQUM7SUFDWCxrQ0FBa0M7SUFDbEMsVUFBVSxFQUFFLE1BQU0sQ0FBQztDQUNwQjtBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxXQUFXLGFBQWE7SUFDNUIsaUNBQWlDO0lBQ2pDLFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIseURBQXlEO0lBQ3pELFVBQVUsRUFBRSxTQUFTLENBQUM7Q0FDdkI7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sV0FBVyxXQUFXO0lBQzFCLHdEQUF3RDtJQUN4RCxhQUFhLEVBQUUsU0FBUyxDQUFDO0lBQ3pCLG9EQUFvRDtJQUNwRCxnQkFBZ0IsRUFBRSxNQUFNLENBQUM7Q0FDMUI7QUFTRDs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHdCQUFzQixlQUFlLElBQUksT0FBTyxDQUFDLGFBQWEsQ0FBQyxDQWE5RDtBQUVEOzs7Ozs7Ozs7Ozs7Ozs7R0FlRztBQUNILHdCQUFzQixlQUFlLENBQUMsU0FBUyxFQUFFLFNBQVMsR0FBRyxPQUFPLENBQUMsaUJBQWlCLENBQUMsQ0FRdEY7QUFFRDs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHdCQUFnQixlQUFlLENBQUMsUUFBUSxFQUFFLGlCQUFpQixHQUFHLE9BQU8sQ0FBQyxTQUFTLENBQUMsQ0FnQi9FO0FBc0REOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0F3Qkc7QUFDSCx3QkFBc0IsaUJBQWlCLENBQ3JDLFVBQVUsRUFBRSxhQUFhLEVBQ3pCLGFBQWEsRUFBRSxTQUFTLEVBQ3hCLEtBQUssRUFBRSxPQUFPLEdBQ2IsT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQXdEdEI7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FpQkc7QUFDSCx3QkFBc0IsT0FBTyxDQUFDLEdBQUcsRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsZ0JBQWdCLENBQUMsQ0FVckY7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FpQkc7QUFDSCx3QkFBc0IsT0FBTyxDQUFDLENBQUMsR0FBRyxPQUFPLEVBQUUsR0FBRyxFQUFFLFNBQVMsRUFBRSxPQUFPLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLENBQUMsQ0FBQyxDQVFoRztBQXdERDs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sdUJBQXVCLElBQUksQ0FBQztBQUV6Qzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBcUJHO0FBQ0gsd0JBQWdCLFdBQVcsQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLEtBQUssR0FBRSxNQUFnQyxHQUFHLE1BQU0sQ0FPekYifQ==

package/dest/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,CAAC,EAAE,MAAM,CAAC;IACV,uCAAuC;IACvC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,yDAAyD;IACzD,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC,CAa9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAQtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB/E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAc/F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAUtF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAQhG;AAoED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM,CAMpE"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AA8DA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,CAAC,EAAE,MAAM,CAAC;IACV,uCAAuC;IACvC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,yDAAyD;IACzD,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,aAAa,EAAE,SAAS,CAAC;IACzB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC,CAa9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAQtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB/E;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,aAAa,EACzB,aAAa,EAAE,SAAS,EACxB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,WAAW,CAAC,CAwDtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAUrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAQhG;AAwDD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAgC,GAAG,MAAM,CAOzF"}

package/dest/crypto.js

@@ -4,38 +4,69 @@
  * This module provides ECDH key exchange and AES-GCM encryption primitives
  * for establishing secure communication channels between dApps and wallet extensions.
  *
- * The crypto flow:
+ * ## Security Model
+ *
+ * The crypto flow uses HKDF for key derivation with domain separation:
+ *
  * 1. Both parties generate ECDH key pairs using {@link generateKeyPair}
  * 2. Public keys are exchanged (exported via {@link exportPublicKey}, imported via {@link importPublicKey})
- * 3. Both parties derive the same shared secret using {@link deriveSharedKey}
- * 4. Messages are encrypted/decrypted using {@link encrypt} and {@link decrypt}
+ * 3. Both parties derive keys using {@link deriveSessionKeys}:
+ *    - ECDH produces raw shared secret
+ *    - HKDF expands the secret into 512 bits using concatenated public keys as salt
+ *    - The 512 bits are split: first 256 bits for AES-GCM, second 256 bits for HMAC
+ * 4. Fingerprint is computed as HMAC(HMAC_KEY, "aztec-wallet-verification-verificationHash")
+ * 5. Messages are encrypted/decrypted using {@link encrypt} and {@link decrypt}
+ *
+ * This design ensures:
+ * - The encryption key is never exposed (verificationHash uses separate HMAC key)
+ * - Public keys are bound to the derived keys via HKDF salt
+ * - Single HKDF derivation with domain-separated output splitting
+ *
+ * ## Curve Choice
+ *
+ * We use P-256 (secp256r1) because it's the only ECDH curve with broad Web Crypto API
+ * support across all browsers. X25519 would be preferable for its simplicity and
+ * resistance to implementation errors, but it lacks universal browser support.
  *
  * @example
  * ```typescript
- * // Party A
+ * // Party A (dApp)
  * const keyPairA = await generateKeyPair();
  * const publicKeyA = await exportPublicKey(keyPairA.publicKey);
  *
- * // Party B
+ * // Party B (wallet)
  * const keyPairB = await generateKeyPair();
  * const publicKeyB = await exportPublicKey(keyPairB.publicKey);
  *
- * // Exchange public keys, then derive shared secret
+ * // Exchange public keys, then derive session keys
+ * // App side: isApp = true
  * const importedB = await importPublicKey(publicKeyB);
- * const sharedKeyA = await deriveSharedKey(keyPairA.privateKey, importedB);
+ * const sessionA = await deriveSessionKeys(keyPairA, importedB, true);
+ *
+ * // Wallet side: isApp = false
+ * const importedA = await importPublicKey(publicKeyA);
+ * const sessionB = await deriveSessionKeys(keyPairB, importedA, false);
+ *
+ * // Both parties compute the same verificationHash for verification
+ * const verificationHashA = sessionA.verificationHash;
+ * const emojiA = hashToEmoji(verificationHashA);
  *
  * // Encrypt and decrypt
- * const encrypted = await encrypt(sharedKeyA, { message: 'hello' });
- * const decrypted = await decrypt(sharedKeyB, encrypted);
+ * const encrypted = await encrypt(sessionA.encryptionKey, JSON.stringify({ message: 'hello' }));
+ * const decrypted = await decrypt(sessionB.encryptionKey, encrypted);
  * ```
  *
  * @packageDocumentation
- */ import { jsonStringify } from '@aztec/foundation/json-rpc';
+ */ import { EMOJI_ALPHABET, EMOJI_ALPHABET_SIZE } from './emoji_alphabet.js';
+/** P-256 coordinate size in bytes */ const P256_COORDINATE_SIZE = 32;
+// HKDF info string for key derivation
+const HKDF_INFO = new TextEncoder().encode('Aztec Wallet DAPP Key derivation');
+const FINGERPRINT_DATA = new TextEncoder().encode('aztec-wallet-verification-verificationHash');
 /**
  * Generates an ECDH P-256 key pair for key exchange.
  *
- * The generated key pair can be used to derive a shared secret with another
- * party's public key using {@link deriveSharedKey}.
+ * The generated key pair can be used to derive session keys with another
+ * party's public key using {@link deriveSessionKeys}.
  *
  * @returns A new ECDH key pair
  *
@@ -50,7 +81,7 @@
         name: 'ECDH',
         namedCurve: 'P-256'
     }, true, [
-        'deriveKey'
+        'deriveBits'
     ]);
     return {
         publicKey: keyPair.publicKey,
@@ -84,16 +115,16 @@
 /**
  * Imports a public key from JWK format.
  *
- * Used to import the other party's public key for deriving a shared secret.
+ * Used to import the other party's public key for deriving session keys.
  *
  * @param exported - The public key in JWK format
- * @returns A CryptoKey that can be used with {@link deriveSharedKey}
+ * @returns A CryptoKey that can be used with {@link deriveSessionKeys}
  *
  * @example
  * ```typescript
- * // Receive exported public key from other party
- * const theirPublicKey = await importPublicKey(receivedPublicKey);
- * const sharedKey = await deriveSharedKey(myPrivateKey, theirPublicKey);
+ * // App side: receive wallet's public key and derive session
+ * const walletPublicKey = await importPublicKey(receivedWalletKey);
+ * const session = await deriveSessionKeys(appKeyPair, walletPublicKey, true);
  * ```
  */ export function importPublicKey(exported) {
     return crypto.subtle.importKey('jwk', {
@@ -104,58 +135,150 @@
     }, {
         name: 'ECDH',
         namedCurve: 'P-256'
-    }, false, []);
+    }, true, []);
+}
+/**
+ * Decodes a base64url-encoded coordinate to fixed-size bytes.
+ *
+ * For P-256, coordinates are always 32 bytes. This function ensures
+ * consistent serialization regardless of leading zeros.
+ *
+ * @param base64url - Base64url-encoded coordinate
+ * @param size - Expected size in bytes (32 for P-256)
+ * @returns Fixed-size Uint8Array, left-padded with zeros if needed
+ */ function decodeCoordinateFixedSize(base64url, size) {
+    const decoded = base64UrlToBytes(base64url);
+    if (decoded.length === size) {
+        return decoded;
+    }
+    if (decoded.length > size) {
+        throw new Error(`Invalid P-256 coordinate: expected ${size} bytes, got ${decoded.length}`);
+    }
+    // Left-pad with zeros
+    const padded = new Uint8Array(size);
+    padded.set(decoded, size - decoded.length);
+    return padded;
+}
+/**
+ * Creates HKDF salt from public keys with fixed ordering by party role.
+ *
+ * The app's public key always comes first, followed by the wallet's public key.
+ * This ensures both parties produce the same salt.
+ *
+ * @param appKey - The app's public key in exported format
+ * @param walletKey - The wallet's public key in exported format
+ * @returns Concatenated bytes: app_x || app_y || wallet_x || wallet_y (128 bytes for P-256)
+ */ function createSaltFromPublicKeys(appKey, walletKey) {
+    // Fixed ordering: app first, then wallet
+    // Each coordinate is fixed at 32 bytes for P-256
+    const appX = decodeCoordinateFixedSize(appKey.x, P256_COORDINATE_SIZE);
+    const appY = decodeCoordinateFixedSize(appKey.y, P256_COORDINATE_SIZE);
+    const walletX = decodeCoordinateFixedSize(walletKey.x, P256_COORDINATE_SIZE);
+    const walletY = decodeCoordinateFixedSize(walletKey.y, P256_COORDINATE_SIZE);
+    // Total: 4 * 32 = 128 bytes
+    const salt = new Uint8Array(4 * P256_COORDINATE_SIZE);
+    salt.set(appX, 0);
+    salt.set(appY, P256_COORDINATE_SIZE);
+    salt.set(walletX, 2 * P256_COORDINATE_SIZE);
+    salt.set(walletY, 3 * P256_COORDINATE_SIZE);
+    return salt.buffer;
 }
 /**
- * Derives a shared AES-256-GCM key from ECDH key exchange.
+ * Derives session keys from ECDH key exchange using HKDF.
+ *
+ * This is the main key derivation function that produces:
+ * 1. An AES-256-GCM encryption key (first 256 bits)
+ * 2. An HMAC key for verificationHash computation (second 256 bits)
+ * 3. A verificationHash computed as HMAC(hmacKey, "aztec-wallet-verification-verificationHash")
  *
- * Both parties will derive the same shared key when using their own private key
- * and the other party's public key. This is the core of ECDH key agreement.
+ * The keys are derived using a single HKDF call that produces 512 bits,
+ * then split into the two keys.
  *
- * @param privateKey - Your ECDH private key
- * @param publicKey - The other party's ECDH public key
- * @returns An AES-256-GCM key for encryption/decryption
+ * @param ownKeyPair - The caller's ECDH key pair (private for ECDH, public for salt)
+ * @param peerPublicKey - The peer's ECDH public key (for ECDH and salt)
+ * @param isApp - true if caller is the app, false if caller is the wallet
+ * @returns Session keys containing encryption key and verificationHash
  *
  * @example
  * ```typescript
- * // Both parties derive the same key
- * const sharedKeyA = await deriveSharedKey(privateKeyA, publicKeyB);
- * const sharedKeyB = await deriveSharedKey(privateKeyB, publicKeyA);
- * // sharedKeyA and sharedKeyB are equivalent
+ * // App side
+ * const sessionA = await deriveSessionKeys(appKeyPair, walletPublicKey, true);
+ * // Wallet side
+ * const sessionB = await deriveSessionKeys(walletKeyPair, appPublicKey, false);
+ * // sessionA.verificationHash === sessionB.verificationHash
  * ```
- */ export function deriveSharedKey(privateKey, publicKey) {
-    return crypto.subtle.deriveKey({
+ */ export async function deriveSessionKeys(ownKeyPair, peerPublicKey, isApp) {
+    // Step 1: ECDH to get raw shared secret
+    const sharedSecretBits = await crypto.subtle.deriveBits({
         name: 'ECDH',
-        public: publicKey
-    }, privateKey, {
+        public: peerPublicKey
+    }, ownKeyPair.privateKey, 256);
+    // Step 2: Import shared secret as HKDF key material
+    const hkdfKey = await crypto.subtle.importKey('raw', sharedSecretBits, {
+        name: 'HKDF'
+    }, false, [
+        'deriveBits'
+    ]);
+    // Step 3: Export public keys and create salt (app first, wallet second)
+    const ownExportedKey = await exportPublicKey(ownKeyPair.publicKey);
+    const peerExportedKey = await exportPublicKey(peerPublicKey);
+    const appPublicKey = isApp ? ownExportedKey : peerExportedKey;
+    const walletPublicKey = isApp ? peerExportedKey : ownExportedKey;
+    const salt = createSaltFromPublicKeys(appPublicKey, walletPublicKey);
+    // Step 4: Derive 512 bits in a single HKDF call
+    const derivedBits = await crypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt,
+        info: HKDF_INFO
+    }, hkdfKey, 512);
+    // Step 5: Split into GCM key (first 256 bits) and HMAC key (second 256 bits)
+    const gcmKeyBits = derivedBits.slice(0, 32);
+    const hmacKeyBits = derivedBits.slice(32, 64);
+    // Step 6: Import GCM key
+    const encryptionKey = await crypto.subtle.importKey('raw', gcmKeyBits, {
         name: 'AES-GCM',
         length: 256
-    }, true, [
+    }, false, [
         'encrypt',
         'decrypt'
     ]);
+    // Step 7: Import HMAC key
+    const hmacKey = await crypto.subtle.importKey('raw', hmacKeyBits, {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'sign'
+    ]);
+    // Step 8: Compute verificationHash as HMAC of fixed string
+    const verificationHashBytes = await crypto.subtle.sign('HMAC', hmacKey, FINGERPRINT_DATA);
+    // Convert to hex string
+    const verificationHash = arrayBufferToHex(verificationHashBytes);
+    return {
+        encryptionKey,
+        verificationHash
+    };
 }
 /**
  * Encrypts data using AES-256-GCM.
  *
- * The data is JSON serialized before encryption. A random 12-byte IV is
- * generated for each encryption operation.
+ * A random 12-byte IV is generated for each encryption operation.
  *
  * AES-GCM provides both confidentiality and authenticity - any tampering
  * with the ciphertext will cause decryption to fail.
  *
- * @param key - The AES-GCM key (from {@link deriveSharedKey})
- * @param data - The data to encrypt (will be JSON serialized)
+ * @param key - The AES-GCM key (from {@link deriveSessionKeys})
+ * @param data - The string data to encrypt (caller is responsible for serialization)
  * @returns The encrypted payload with IV and ciphertext
  *
  * @example
  * ```typescript
- * const encrypted = await encrypt(sharedKey, { action: 'transfer', amount: 100 });
+ * const encrypted = await encrypt(session.encryptionKey, JSON.stringify({ action: 'transfer', amount: 100 }));
  * // encrypted.iv and encrypted.ciphertext are base64 strings
  * ```
  */ export async function encrypt(key, data) {
     const iv = crypto.getRandomValues(new Uint8Array(12));
-    const encoded = new TextEncoder().encode(jsonStringify(data));
+    const encoded = new TextEncoder().encode(data);
     const ciphertext = await crypto.subtle.encrypt({
         name: 'AES-GCM',
         iv
@@ -171,7 +294,7 @@
  * The decrypted data is JSON parsed before returning.
  *
  * @typeParam T - The expected type of the decrypted data
- * @param key - The AES-GCM key (from {@link deriveSharedKey})
+ * @param key - The AES-GCM key (from {@link deriveSessionKeys})
  * @param payload - The encrypted payload from {@link encrypt}
  * @returns The decrypted and parsed data
  *
@@ -179,7 +302,7 @@
  *
  * @example
  * ```typescript
- * const decrypted = await decrypt<{ action: string; amount: number }>(sharedKey, encrypted);
+ * const decrypted = await decrypt<{ action: string; amount: number }>(session.encryptionKey, encrypted);
  * console.log(decrypted.action); // 'transfer'
  * ```
  */ export async function decrypt(key, payload) {
@@ -215,86 +338,57 @@
     return bytes.buffer;
 }
 /**
- * Emoji alphabet for visual verification of shared secrets.
- * 32 distinct, easily recognizable emojis for anti-spoofing verification.
+ * Converts base64url string to Uint8Array.
  * @internal
- */ const EMOJI_ALPHABET = [
-    '🔵',
-    '🟢',
-    '🔴',
-    '🟡',
-    '🟣',
-    '🟠',
-    '⚫',
-    '⚪',
-    '🌟',
-    '🌙',
-    '☀️',
-    '🌈',
-    '🔥',
-    '💧',
-    '🌸',
-    '🍀',
-    '🦋',
-    '🐬',
-    '🦊',
-    '🐼',
-    '🦁',
-    '🐯',
-    '🐸',
-    '🦉',
-    '🎵',
-    '🎨',
-    '🎯',
-    '🎲',
-    '🔔',
-    '💎',
-    '🔑',
-    '🏆'
-];
+ */ function base64UrlToBytes(base64url) {
+    // Convert base64url to base64
+    const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    // Add padding if needed
+    const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for(let i = 0; i < binary.length; i++){
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
 /**
- * Hashes a shared AES key to a hex string for verification.
- *
- * This extracts the raw key material and hashes it with SHA-256,
- * returning the first 16 bytes as a hex string.
- *
- * @param sharedKey - The AES-GCM shared key (must be extractable)
- * @returns A hex string representation of the hash
- *
- * @example
- * ```typescript
- * const hash = await hashSharedSecret(sharedKey);
- * const emoji = hashToEmoji(hash);
- * ```
- */ export async function hashSharedSecret(sharedKey) {
-    const rawKey = await crypto.subtle.exportKey('raw', sharedKey);
-    const hash = await crypto.subtle.digest('SHA-256', rawKey);
-    const bytes = new Uint8Array(hash.slice(0, 16));
+ * Converts ArrayBuffer to hex string.
+ * @internal
+ */ function arrayBufferToHex(buffer) {
+    const bytes = new Uint8Array(buffer);
     return Array.from(bytes).map((b)=>b.toString(16).padStart(2, '0')).join('');
 }
+/**
+ * Default grid size for emoji verification display.
+ * 3x3 grid = 9 emojis = 72 bits of security.
+ */ export const DEFAULT_EMOJI_GRID_SIZE = 9;
 /**
  * Converts a hex hash to an emoji sequence for visual verification.
  *
- * This is used for anti-MITM verification - both the dApp and wallet
- * independently compute the same emoji sequence from the shared secret.
+ * This is used for verification - both the dApp and wallet
+ * independently compute the same emoji sequence from the derived keys.
  * Users can visually compare the sequences to detect interception.
  *
- * Similar to SAS (Short Authentication String) in ZRTP/Signal.
+ * With a 256-emoji alphabet and 9 emojis (3x3 grid), this provides
+ * 72 bits of security (9 * 8 = 72 bits), making brute-force attacks
+ * computationally infeasible.
  *
- * @param hash - Hex string from {@link hashSharedSecret}
- * @param length - Number of emojis to generate (default: 4)
+ * @param hash - Hex string from verification hash (64 chars = 32 bytes)
+ * @param count - Number of emojis to generate (default: 9 for 3x3 grid)
  * @returns A string of emojis representing the hash
  *
  * @example
  * ```typescript
- * const hash = await hashSharedSecret(sharedKey);
- * const emoji = hashToEmoji(hash); // e.g., "🔵🦋🎯🐼"
- * // Display to user for verification
+ * const session = await deriveSessionKeys(...);
+ * const emoji = hashToEmoji(session.verificationHash); // e.g., "🔵🦋🎯🐼🌟🎲🦊🐸💎"
+ * // Display as 3x3 grid to user for verification
  * ```
- */ export function hashToEmoji(hash, length = 4) {
-    const bytes = [];
-    for(let i = 0; i < hash.length && bytes.length < length; i += 2){
-        bytes.push(parseInt(hash.slice(i, i + 2), 16));
+ */ export function hashToEmoji(hash, count = DEFAULT_EMOJI_GRID_SIZE) {
+    const emojis = [];
+    for(let i = 0; i < hash.length && emojis.length < count; i += 2){
+        const byteValue = parseInt(hash.slice(i, i + 2), 16);
+        emojis.push(EMOJI_ALPHABET[byteValue % EMOJI_ALPHABET_SIZE]);
     }
-    return bytes.map((b)=>EMOJI_ALPHABET[b % EMOJI_ALPHABET.length]).join('');
+    return emojis.join('');
 }