@openzeppelin/miden-multisig-client 0.14.5 → 0.14.6

package/src/lookupAuth.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// The Miden SDK is wasm-bound and is mocked across this test suite (matching
+// the pattern in transaction.test.ts, multisig.test.ts, etc.). We cannot run
+// real RPO256 here, but we CAN verify the lookup-digest function builds the
+// FeltArray sequence in the right order and chunking convention. Cross-language
+// parity against `crates/shared/tests/fixtures/lookup_auth_vectors.json` is
+// intentionally a separate runner — see `runRealSdkParity` below for the gated
+// hook.
+
+interface FakeFelt {
+  __felt: true;
+  value: bigint;
+}
+
+interface FakeWord {
+  __word: true;
+  felts: FakeFelt[];
+  toFelts: () => FakeFelt[];
+  toHex: () => string;
+}
+
+const hashCalls: { input: FakeFelt[] }[] = [];
+
+vi.mock('@miden-sdk/miden-sdk', () => {
+  const Felt = vi.fn().mockImplementation((value: bigint) => ({
+    __felt: true,
+    value,
+  }));
+
+  const FeltArray = vi.fn().mockImplementation((felts: FakeFelt[]) => felts);
+
+  const makeWord = (felts: FakeFelt[], hex = '0xMOCKED'): FakeWord => ({
+    __word: true,
+    felts,
+    toFelts: () => felts,
+    toHex: () => hex,
+  });
+
+  const Word = {
+    fromHex: vi.fn().mockImplementation((hex: string) => {
+      // Deterministic four-felt decomposition: split hex into 4 8-byte pieces.
+      // The values are not real Word semantics, but they let us assert the
+      // implementation passes them through in order.
+      const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+      const padded = stripped.padStart(64, '0');
+      const felts: FakeFelt[] = [];
+      for (let i = 0; i < 4; i += 1) {
+        const piece = padded.slice(i * 16, (i + 1) * 16);
+        felts.push({ __felt: true, value: BigInt('0x' + piece) });
+      }
+      return makeWord(felts, hex);
+    }),
+  };
+
+  const Rpo256 = {
+    hashElements: vi.fn().mockImplementation((felts: FakeFelt[]) => {
+      hashCalls.push({ input: [...felts] });
+      // Synthesize a fake digest: 4 felts derived from the input length and
+      // first felt's value, so each call's output is distinguishable.
+      const seed = felts.length === 0 ? 0n : felts[0].value;
+      return makeWord(
+        [
+          { __felt: true, value: seed ^ BigInt(felts.length) },
+          { __felt: true, value: seed + 1n },
+          { __felt: true, value: seed + 2n },
+          { __felt: true, value: seed + 3n },
+        ],
+        '0xfakehash',
+      );
+    }),
+  };
+
+  return { Felt, FeltArray, Rpo256, Word };
+});
+
+const DOMAIN_TAG_BYTES = new TextEncoder().encode('guardian.lookup.v1');
+
+function bytesToExpectedFelts(bytes: Uint8Array): bigint[] {
+  const out: bigint[] = [];
+  for (let offset = 0; offset < bytes.length; offset += 8) {
+    let value = 0n;
+    for (let i = 0; i < 8; i += 1) {
+      const byte = offset + i < bytes.length ? bytes[offset + i] : 0;
+      value |= BigInt(byte) << BigInt(8 * i);
+    }
+    out.push(value);
+  }
+  return out;
+}
+
+let lookupAuthDigest: typeof import('./lookupAuth.js').lookupAuthDigest;
+let _resetLookupDomainTagCacheForTesting: typeof import('./lookupAuth.js')._resetLookupDomainTagCacheForTesting;
+
+beforeEach(async () => {
+  hashCalls.length = 0;
+  // Re-import to pick up a fresh cached domain tag per test, in addition to
+  // the explicit reset, so test ordering does not change behavior.
+  const mod = await import('./lookupAuth.js');
+  lookupAuthDigest = mod.lookupAuthDigest;
+  _resetLookupDomainTagCacheForTesting = mod._resetLookupDomainTagCacheForTesting;
+  _resetLookupDomainTagCacheForTesting();
+});
+
+describe('lookupAuthDigest', () => {
+  it('hashes the domain-tag bytes via the same 8-byte LE chunking as Rust', () => {
+    const keyCommitmentHex = '0x' + 'aa'.repeat(32);
+    lookupAuthDigest(1_700_000_000_000, keyCommitmentHex);
+
+    // First Rpo256.hashElements call must be the domain-tag computation
+    // (3 felts for "guardian.lookup.v1" — 18 bytes → ceil(18/8) = 3 chunks).
+    expect(hashCalls.length).toBeGreaterThanOrEqual(2);
+    const tagCall = hashCalls[0];
+    const expected = bytesToExpectedFelts(DOMAIN_TAG_BYTES);
+    expect(tagCall.input).toHaveLength(expected.length);
+    expect(tagCall.input.length).toBe(3);
+    for (let i = 0; i < expected.length; i += 1) {
+      expect(tagCall.input[i].value).toBe(expected[i]);
+    }
+  });
+
+  it('caches the domain-tag computation across calls', () => {
+    const keyCommitmentHex = '0x' + 'bb'.repeat(32);
+    lookupAuthDigest(1_700_000_000_000, keyCommitmentHex);
+    const callsAfterFirst = hashCalls.length;
+    lookupAuthDigest(1_700_000_000_001, keyCommitmentHex);
+    const callsAfterSecond = hashCalls.length;
+
+    // Second invocation should perform exactly one Rpo256.hashElements call
+    // (the message hash); the domain-tag hash is cached.
+    expect(callsAfterSecond - callsAfterFirst).toBe(1);
+  });
+
+  it('passes 9 felts in [tag, timestamp, key_commitment] order to the message hash', () => {
+    const keyCommitmentHex = '0x' + '01'.repeat(32);
+    const timestamp = 1_700_000_000_000n;
+    lookupAuthDigest(timestamp, keyCommitmentHex);
+
+    const messageCall = hashCalls[hashCalls.length - 1];
+    expect(messageCall.input).toHaveLength(9);
+
+    // Felt 4 is the timestamp, reinterpreted as u64 (no change for positive).
+    expect(messageCall.input[4].value).toBe(timestamp);
+
+    // Felts 5..8 are the key-commitment felts, derived deterministically by
+    // the mocked Word.fromHex from the hex representation.
+    const expectedKcWord = '01'.repeat(32);
+    for (let i = 0; i < 4; i += 1) {
+      const piece = expectedKcWord.slice(i * 16, (i + 1) * 16);
+      expect(messageCall.input[5 + i].value).toBe(BigInt('0x' + piece));
+    }
+  });
+
+  it('reinterprets a negative timestamp via two-complement u64 cast', () => {
+    const keyCommitmentHex = '0x' + 'cc'.repeat(32);
+    lookupAuthDigest(-1, keyCommitmentHex);
+
+    const messageCall = hashCalls[hashCalls.length - 1];
+    // -1 cast to u64 is 0xFFFFFFFFFFFFFFFF.
+    expect(messageCall.input[4].value).toBe(0xFFFFFFFFFFFFFFFFn);
+  });
+
+  it('produces distinct digest inputs for distinct commitments', () => {
+    lookupAuthDigest(1_700_000_000_000, '0x' + '01'.repeat(32));
+    lookupAuthDigest(1_700_000_000_000, '0x' + '02'.repeat(32));
+
+    // Call 0 is the cached domain-tag hash. Calls 1 and 2 are the two message
+    // hashes; the second call hits the domain-tag cache so it does not produce
+    // an extra hash call.
+    const messageCallA = hashCalls[1];
+    const messageCallB = hashCalls[2];
+    expect(messageCallA.input[5].value).not.toBe(messageCallB.input[5].value);
+  });
+
+  it('produces distinct digest inputs for distinct timestamps', () => {
+    const keyCommitmentHex = '0x' + '01'.repeat(32);
+    lookupAuthDigest(1_700_000_000_000, keyCommitmentHex);
+    lookupAuthDigest(1_700_000_000_001, keyCommitmentHex);
+
+    const messageCallA = hashCalls[1];
+    const messageCallB = hashCalls[2];
+    expect(messageCallA.input[4].value).not.toBe(messageCallB.input[4].value);
+  });
+});

package/src/lookupAuth.ts

@@ -0,0 +1,93 @@
+import { Felt, FeltArray, Rpo256, Word } from '@miden-sdk/miden-sdk';
+
+/**
+ * Lookup-bound message format used to sign requests against the Guardian
+ * `/state/lookup` endpoint. MUST produce byte-identical digests to
+ * `crates/shared/src/lookup_auth_message.rs`; parity is verified against
+ * `crates/shared/tests/fixtures/lookup_auth_vectors.json`.
+ */
+
+const DOMAIN_TAG_BYTES = new TextEncoder().encode('guardian.lookup.v1');
+
+let cachedDomainTag: Word | null = null;
+
+/**
+ * Convert a byte array to a sequence of Goldilocks-field felts using the same
+ * 8-byte little-endian chunking convention as
+ * `guardian_shared::auth_request_payload::AuthRequestPayload::from_bytes`. The
+ * final chunk is zero-padded if `bytes.length` is not a multiple of 8.
+ */
+function bytesToFelts(bytes: Uint8Array): Felt[] {
+  const felts: Felt[] = [];
+  for (let offset = 0; offset < bytes.length; offset += 8) {
+    let value = 0n;
+    for (let i = 0; i < 8; i += 1) {
+      const byte = offset + i < bytes.length ? bytes[offset + i] : 0;
+      value |= BigInt(byte) << BigInt(8 * i);
+    }
+    felts.push(new Felt(value));
+  }
+  return felts;
+}
+
+/**
+ * The 4-felt RPO domain tag prepended to every lookup digest, computed once
+ * from `DOMAIN_TAG_BYTES`. Cached on first call.
+ */
+function lookupDomainTag(): Word {
+  if (cachedDomainTag === null) {
+    cachedDomainTag = Rpo256.hashElements(new FeltArray(bytesToFelts(DOMAIN_TAG_BYTES)));
+  }
+  return cachedDomainTag;
+}
+
+/**
+ * Compute the digest a lookup-bound signer signs.
+ *
+ * Layout (must mirror `LookupAuthMessage::to_word` in `crates/shared`):
+ *
+ * ```text
+ * RPO256_hash([
+ *   DOMAIN_TAG_W0, DOMAIN_TAG_W1, DOMAIN_TAG_W2, DOMAIN_TAG_W3,
+ *   timestamp_ms_felt,
+ *   key_commitment_W0, key_commitment_W1,
+ *   key_commitment_W2, key_commitment_W3,
+ * ])
+ * ```
+ *
+ * @param timestampMs Unix milliseconds. Reinterpreted as `u64` to match the
+ *                    Rust `as u64` cast (so negative inputs wrap into the
+ *                    high range, then are reduced mod the Goldilocks prime by
+ *                    the Felt constructor).
+ * @param keyCommitmentHex `0x`-prefixed 32-byte hex string for the queried
+ *                         commitment.
+ */
+export function lookupAuthDigest(timestampMs: number | bigint, keyCommitmentHex: string): Word {
+  const tag = lookupDomainTag().toFelts();
+  const kc = Word.fromHex(keyCommitmentHex).toFelts();
+  const tsBigInt = typeof timestampMs === 'bigint' ? timestampMs : BigInt(timestampMs);
+  const timestampU64 = BigInt.asUintN(64, tsBigInt);
+  const timestampFelt = new Felt(timestampU64);
+
+  const message = new FeltArray([
+    tag[0],
+    tag[1],
+    tag[2],
+    tag[3],
+    timestampFelt,
+    kc[0],
+    kc[1],
+    kc[2],
+    kc[3],
+  ]);
+
+  return Rpo256.hashElements(message);
+}
+
+/**
+ * Reset the cached domain tag. Tests use this to exercise the cache miss path;
+ * production callers should not need it.
+ */
+export function _resetLookupDomainTagCacheForTesting(): void {
+  cachedDomainTag = null;
+}

package/src/signers/ecdsa.ts

@@ -3,6 +3,7 @@ import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sd
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex, normalizeHexWord } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 
 export class EcdsaSigner implements Signer {
   readonly commitment: string;
@@ -39,6 +40,15 @@ export class EcdsaSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/falcon.ts

@@ -3,6 +3,7 @@ import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sd
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 
 export class FalconSigner implements Signer {
   readonly commitment: string;
@@ -40,6 +41,15 @@ export class FalconSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/miden-wallet.test.ts

@@ -153,6 +153,54 @@ describe('MidenWalletSigner', () => {
     });
   });
 
+  describe('signLookupMessage', () => {
+    it('delegates to localAuthSigner when present', async () => {
+      const localSigner: Signer = {
+        commitment: '0xlocal',
+        publicKey: '0xlocalpubkey',
+        scheme: 'ecdsa',
+        signAccountIdWithTimestamp: vi.fn(),
+        signCommitment: vi.fn(),
+        signLookupMessage: vi.fn().mockResolvedValue('0xlocallookupsig'),
+      };
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'ecdsa', localSigner);
+
+      const result = await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(result).toBe('0xlocallookupsig');
+      expect(localSigner.signLookupMessage).toHaveBeenCalledWith(
+        '0x' + 'cc'.repeat(32),
+        1700000000,
+      );
+      expect(mockWallet.signBytes).not.toHaveBeenCalled();
+    });
+
+    it('uses wallet signing over the LookupAuthMessage digest when no localAuthSigner', async () => {
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'falcon');
+
+      const result = await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(mockWallet.signBytes).toHaveBeenCalledTimes(1);
+      expect(mockWallet.signBytes).toHaveBeenCalledWith(expect.any(Uint8Array), 'word');
+      expect(result).toMatch(/^0x/);
+    });
+
+    it('falls back to wallet signing when localAuthSigner does not implement signLookupMessage', async () => {
+      const localSigner: Signer = {
+        commitment: '0xlocal',
+        publicKey: '0xlocalpubkey',
+        scheme: 'ecdsa',
+        signAccountIdWithTimestamp: vi.fn(),
+        signCommitment: vi.fn(),
+      };
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'ecdsa', localSigner);
+
+      await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(mockWallet.signBytes).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('signature byte stripping', () => {
     it('should strip the first byte from wallet signature response', async () => {
       (mockWallet.signBytes as ReturnType<typeof vi.fn>).mockResolvedValue(

package/src/signers/miden-wallet.ts

@@ -2,6 +2,7 @@ import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
 import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { bytesToHex } from '../utils/encoding.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 import { wordToBytes } from '../utils/word.js';
 
 export interface WalletSigningContext {
@@ -57,6 +58,18 @@ export class MidenWalletSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    if (this.localAuthSigner?.signLookupMessage) {
+      return this.localAuthSigner.signLookupMessage(keyCommitmentHex, timestampMs);
+    }
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   private async signWord(word: { toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const bytes = wordToBytes(word);
     const signatureBytes = await this.wallet.signBytes(bytes, 'word');

package/src/signers/para.test.ts

@@ -148,6 +148,32 @@ describe('ParaSigner', () => {
     });
   });
 
+  describe('signLookupMessage', () => {
+    it('hashes the LookupAuthMessage digest word bytes before signing', async () => {
+      const signer = new ParaSigner(mockPara, 'wallet-1', '0xcommitment', validCompressedKey);
+      await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      const expectedDigestBytes = keccak_256(
+        wordToBytes({
+          toFelts: () => [
+            { asInt: () => 10n },
+            { asInt: () => 20n },
+            { asInt: () => 30n },
+            { asInt: () => 40n },
+          ],
+        }),
+      );
+      const expectedBase64 = uint8ArrayToBase64(expectedDigestBytes);
+
+      expect(mockPara.signMessage).toHaveBeenCalledWith(
+        expect.objectContaining({
+          walletId: 'wallet-1',
+          messageBase64: expectedBase64,
+        }),
+      );
+    });
+  });
+
   describe('signing denial', () => {
     it('should throw when para returns no signature', async () => {
       (mockPara.signMessage as ReturnType<typeof vi.fn>).mockResolvedValue({ signature: undefined });

package/src/signers/para.ts

@@ -3,6 +3,7 @@ import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { EcdsaFormat } from '../utils/ecdsa.js';
 import { hexToBytes, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 import { wordToBytes } from '../utils/word.js';
 
 export interface ParaSigningContext {
@@ -59,6 +60,15 @@ export class ParaSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   private async signWord(word: { toHex: () => string; toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const messageBase64 = uint8ArrayToBase64(
       hexToBytes(EcdsaFormat.keccakDigestHex(wordToBytes(word))),