walletpair-sdk 1.0.0

package/src/__tests__/adversarial/malicious-wallet.test.ts

@@ -0,0 +1,467 @@
+/**
+ * Adversarial tests: Malicious Wallet
+ *
+ * Simulates a malicious wallet attempting to abuse the dApp through
+ * protocol violations: wrong response IDs, role violations, sequence
+ * manipulation, and out-of-state messages.
+ *
+ * These tests verify that the DAppSession enforces protocol rules
+ * correctly, protecting the dApp from a compromised or malicious wallet.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { DAppSession } from '../../dapp-session.js';
+import { MockTransport, makeJoinBody } from '../../test-helpers.js';
+import {
+  generateX25519KeyPair,
+  sealPayload,
+  b64urlEncode,
+} from '../../crypto.js';
+import type { ProtocolMessage } from '../../types.js';
+
+function wait(ms = 50): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function setupDAppManual() {
+  const transport = new MockTransport();
+  const session = new DAppSession({
+    transport,
+    meta: { name: 'Test', description: 'Test dApp', url: 'https://test.com', icon: 'https://test.com/icon.png' },
+  });
+  const walletKp = generateX25519KeyPair();
+  return { transport, session, walletKp };
+}
+
+async function connectDAppManual(ctx: ReturnType<typeof setupDAppManual>) {
+  const { transport, session, walletKp } = ctx;
+  await session.createPairing();
+
+  transport.receive({
+    v: 1, t: 'join', ch: session.channelId,
+    ts: Date.now(), from: walletKp.publicKeyB64,
+    body: makeJoinBody(session.channelId, transport.sent[0]!.from!, walletKp),
+  } as ProtocolMessage);
+
+  transport.receive({
+    v: 1, t: 'ready', ch: session.channelId,
+    ts: Date.now(), from: '_adapter',
+    body: { state: 'connected', reconnect: false, remote: walletKp.publicKeyB64 },
+  } as ProtocolMessage);
+
+  const recvKey = (session as any).recvKey as Uint8Array;
+  const dappPubB64 = transport.sent[0]!.from!;
+  return { recvKey, dappPubB64 };
+}
+
+// ---------------------------------------------------------------------------
+// Attack 1: Wallet sends res with wrong req.id
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Wrong response ID', () => {
+  it('response with unknown req.id is ignored by dApp', async () => {
+    // ATTACK: A malicious wallet sends a response with an ID that does
+    // not match any pending request. This could be an attempt to inject
+    // fake results or confuse request/response matching.
+    //
+    // PREVENTS: Response injection for non-existent requests.
+    // The dApp should silently ignore responses with unknown IDs.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    const responseHandler = vi.fn();
+    session.on('response', responseHandler);
+
+    // Wallet sends a response with a fabricated request ID
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: 'fabricated-req-id',
+        sealed: sealPayload(
+          recvKey, session.channelId, 0,
+          { _ok: true, _result: 'injected-data' },
+          { type: 'res', from: walletKp.publicKeyB64, id: 'fabricated-req-id' },
+        ),
+      },
+    } as ProtocolMessage);
+
+    await wait();
+
+    // Response handler should NOT have been called (no matching pending request)
+    expect(responseHandler).not.toHaveBeenCalled();
+    // Session should remain healthy
+    expect(session.phase).toBe('connected');
+  });
+
+  it('response to wrong req.id does not resolve a different pending request', async () => {
+    // ATTACK: Wallet sends a response with a different request's ID,
+    // trying to resolve the wrong request with attacker-chosen data.
+    //
+    // PREVENTS: Cross-request response substitution.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    // Send two requests
+    const p1 = session.request('wallet_getAccounts');
+    const p2 = session.request('wallet_signMessage', { message: 'test' });
+    await wait(20);
+
+    const reqs = transport.sent.filter(m => m.t === 'req') as any[];
+    const req1Id = reqs[0]!.body.id;
+    const req2Id = reqs[1]!.body.id;
+
+    // Wallet responds to req2 with req1's ID (cross-wired)
+    // The AAD includes the id field, so if the id doesn't match,
+    // AEAD decryption will fail (or the wrong request will be resolved
+    // with potentially confusing data).
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: req1Id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 0,
+          { _ok: true, _result: 'correct-for-req1' },
+          { type: 'res', from: walletKp.publicKeyB64, id: req1Id },
+        ),
+      },
+    } as ProtocolMessage);
+
+    // req1 should resolve correctly
+    expect(await p1).toBe('correct-for-req1');
+
+    // Now respond to req2 normally
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: req2Id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 1,
+          { _ok: true, _result: 'correct-for-req2' },
+          { type: 'res', from: walletKp.publicKeyB64, id: req2Id },
+        ),
+      },
+    } as ProtocolMessage);
+
+    expect(await p2).toBe('correct-for-req2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attack 2: Wallet sends req (role violation)
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Sends req (role violation)', () => {
+  it('dApp ignores req from wallet because only dApp sends req', async () => {
+    // ATTACK: Wallet sends a req message to the dApp. Per Section 5,
+    // only the dApp sends req. The wallet should never do this.
+    // The dApp should either ignore it or treat it as a protocol error.
+    //
+    // PREVENTS: Role reversal attack where wallet tries to command the dApp.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    const errorHandler = vi.fn();
+    session.on('error', errorHandler);
+
+    // Wallet sends a req (which it should never do)
+    transport.receive({
+      v: 1, t: 'req', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: 'evil-req-1',
+        sealed: sealPayload(
+          recvKey, session.channelId, 0,
+          { _method: 'dapp_executeTransaction' },
+          { type: 'req', from: walletKp.publicKeyB64, id: 'evil-req-1' },
+        ),
+      },
+    } as ProtocolMessage);
+
+    await wait();
+
+    // DApp does not have a request handler (it only sends requests).
+    // The message should be silently ignored or cause no state change.
+    // Key insight: DAppSession.handleMessage() has no case for 'req'
+    // messages from the wallet, so it falls through to the default
+    // case (no-op).
+    expect(session.phase).toBe('connected');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attack 3: Wallet manipulates sequence numbers
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Sequence number manipulation', () => {
+  it('skipped sequence numbers are accepted (gaps are valid per spec)', async () => {
+    // Per Section 6.6.1: "Gaps are valid (expected after reconnect)."
+    // This is NOT an attack — verifying correct behavior.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    const p = session.request('wallet_getAccounts');
+    await wait(20);
+    const req = transport.sent.find(m => m.t === 'req') as any;
+    const reqId = req.body.id;
+
+    // Wallet responds with seq=5 (skipping 0-4) — should be accepted
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: reqId,
+        sealed: sealPayload(
+          recvKey, session.channelId, 5,
+          { _ok: true, _result: 'gap-ok' },
+          { type: 'res', from: walletKp.publicKeyB64, id: reqId },
+        ),
+      },
+    } as ProtocolMessage);
+
+    expect(await p).toBe('gap-ok');
+  });
+
+  it('reset sequence to 0 after receiving higher seq is rejected', async () => {
+    // ATTACK: Wallet sends seq=10, then tries to reset to seq=0.
+    // This is a replay/reset attack. Section 6.6.1: "A message MUST
+    // be rejected if its sequence number is not strictly greater than
+    // the last accepted value."
+    //
+    // PREVENTS: Sequence counter reset allowing message replay.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    // First response at seq=10 (accepted)
+    const p0 = session.request('wallet_getAccounts');
+    await wait(20);
+    const req0 = transport.sent.find(m => m.t === 'req') as any;
+    const r0id = req0.body.id;
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: r0id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 10,
+          { _ok: true, _result: 'first' },
+          { type: 'res', from: walletKp.publicKeyB64, id: r0id },
+        ),
+      },
+    } as ProtocolMessage);
+    expect(await p0).toBe('first');
+
+    // Second response at seq=0 (reset attempt — MUST be rejected)
+    const p1 = session.request('wallet_getAccounts');
+    await wait(20);
+    const req1 = transport.sent.filter(m => m.t === 'req')[1] as any;
+    const r1id = req1.body.id;
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: r1id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 0, // reset to 0!
+          { _ok: true, _result: 'replayed' },
+          { type: 'res', from: walletKp.publicKeyB64, id: r1id },
+        ),
+      },
+    } as ProtocolMessage);
+    await expect(p1).rejects.toThrow('Replay detected');
+  });
+
+  it('reused sequence number is rejected', async () => {
+    // ATTACK: Wallet sends the same sequence number twice.
+    //
+    // PREVENTS: Nonce reuse in AEAD encryption.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    // First at seq=3 (accepted)
+    const p0 = session.request('wallet_getAccounts');
+    await wait(20);
+    const req0 = transport.sent.find(m => m.t === 'req') as any;
+    const r0id = req0.body.id;
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: r0id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 3,
+          { _ok: true, _result: 'ok' },
+          { type: 'res', from: walletKp.publicKeyB64, id: r0id },
+        ),
+      },
+    } as ProtocolMessage);
+    expect(await p0).toBe('ok');
+
+    // Second at seq=3 (reuse — MUST be rejected)
+    const p1 = session.request('wallet_getAccounts');
+    await wait(20);
+    const req1 = transport.sent.filter(m => m.t === 'req')[1] as any;
+    const r1id = req1.body.id;
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: {
+        id: r1id,
+        sealed: sealPayload(
+          recvKey, session.channelId, 3, // same seq!
+          { _ok: true, _result: 'reused' },
+          { type: 'res', from: walletKp.publicKeyB64, id: r1id },
+        ),
+      },
+    } as ProtocolMessage);
+    await expect(p1).rejects.toThrow('Replay detected');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attack 4: Wallet sends evt before ready.connected
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Event before connected', () => {
+  it('dApp ignores evt received before ready.connected', async () => {
+    // ATTACK: Wallet sends an event before the channel reaches
+    // connected state. The dApp should not process events until
+    // ready.connected is received (Section 15 rule 7).
+    //
+    // PREVENTS: Pre-connection event injection.
+
+    const transport = new MockTransport();
+    const session = new DAppSession({
+      transport,
+      meta: { name: 'T', description: 'T', url: 'https://t.test', icon: 'https://t.test/i.png' },
+      autoAccept: false, // manual accept to control timing
+    });
+
+    const eventHandler = vi.fn();
+    session.on('event', eventHandler);
+
+    await session.createPairing();
+    const dappPubB64 = transport.sent[0]!.from!;
+
+    const walletKp = generateX25519KeyPair();
+
+    // Wallet joins
+    transport.receive({
+      v: 1, t: 'join', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: makeJoinBody(session.channelId, dappPubB64, walletKp),
+    } as ProtocolMessage);
+
+    await wait();
+    // Session is now in pending_accept, NOT connected
+
+    // Wallet tries to send an event before connected
+    transport.receive({
+      v: 1, t: 'evt', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: { id: 'premature-evt', sealed: 'fake-sealed' },
+    } as ProtocolMessage);
+
+    await wait();
+
+    // Event should NOT have been processed (recvKey exists but
+    // the sealed data is invalid, or the event is silently dropped
+    // due to decryption failure)
+    expect(eventHandler).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attack 5: Wallet sends response from a different key
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Response from wrong peer', () => {
+  it('dApp ignores response from a key that does not match paired wallet', async () => {
+    // ATTACK: A different entity (or the relay itself) sends a response
+    // with a different "from" key. The dApp checks that from matches
+    // the paired wallet's public key.
+    //
+    // PREVENTS: Third-party response injection.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    const { recvKey } = await connectDAppManual(ctx);
+
+    const p = session.request('wallet_getAccounts');
+    await wait(20);
+    const req = transport.sent.find(m => m.t === 'req') as any;
+    const reqId = req.body.id;
+
+    // Impersonator uses a different key
+    const impersonatorKp = generateX25519KeyPair();
+    transport.receive({
+      v: 1, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: impersonatorKp.publicKeyB64, // wrong key!
+      body: {
+        id: reqId,
+        sealed: sealPayload(
+          recvKey, session.channelId, 0,
+          { _ok: true, _result: 'evil' },
+          { type: 'res', from: impersonatorKp.publicKeyB64, id: reqId },
+        ),
+      },
+    } as ProtocolMessage);
+
+    await wait(20);
+
+    // The response should have been silently dropped (from mismatch)
+    // The request should still be pending (not resolved)
+    // Clean up by closing
+    session.close();
+    await expect(p).rejects.toThrow('Session closed');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attack 6: Wallet sends unsupported protocol version
+// ---------------------------------------------------------------------------
+
+describe('Malicious Wallet: Unsupported protocol version', () => {
+  it('dApp closes with unsupported_version on receiving v!=1', async () => {
+    // ATTACK: Wallet sends messages with a different protocol version
+    // to confuse parsing or exploit version-specific vulnerabilities.
+    //
+    // PREVENTS: Version confusion attacks. Section 15 rule 12.
+
+    const ctx = setupDAppManual();
+    const { transport, session, walletKp } = ctx;
+    await connectDAppManual(ctx);
+
+    transport.receive({
+      v: 99 as any, t: 'res', ch: session.channelId,
+      ts: Date.now(), from: walletKp.publicKeyB64,
+      body: { id: 'req-1', sealed: 'whatever' },
+    } as ProtocolMessage);
+
+    await wait();
+
+    // DApp should close with unsupported_version
+    expect(session.phase).toBe('closed');
+    const closeMsg = transport.sent.find(m => m.t === 'close') as any;
+    expect(closeMsg).toBeTruthy();
+    expect(closeMsg.body.reason).toBe('unsupported_version');
+  });
+});

package/src/__tests__/spec-compliance/canonical-json.test.ts

@@ -0,0 +1,227 @@
+/**
+ * WalletPair Protocol v1 — Section 6.3 canonical JSON test vectors.
+ *
+ * Verifies that the SDK's canonicalJson implementation matches every
+ * test vector in the specification, including SHA-256 hashes, and
+ * handles all documented edge cases.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { canonicalJson, sha256Hex } from '../../crypto.js';
+
+function hash(s: string): string {
+  return sha256Hex(new TextEncoder().encode(s));
+}
+
+// ---------------------------------------------------------------------------
+// Section 6.3 — Normative test vectors
+// ---------------------------------------------------------------------------
+
+describe('Section 6.3 — Vector 1: capabilities (key sorting, nested objects)', () => {
+  const input = {
+    methods: ['wallet_signTransaction', 'wallet_signMessage'],
+    events: ['accountsChanged', 'chainChanged'],
+    chains: ['eip155:1', 'eip155:137'],
+  };
+  const expected =
+    '{"chains":["eip155:1","eip155:137"],"events":["accountsChanged","chainChanged"],"methods":["wallet_signTransaction","wallet_signMessage"]}';
+  const expectedHash = '4da366e2aae26b47b3d90fff52410752348733350ce2525dce7d64510f571333';
+
+  it('produces the correct canonical output', () => {
+    expect(canonicalJson(input)).toBe(expected);
+  });
+
+  it('SHA-256 of output matches the spec', () => {
+    expect(hash(canonicalJson(input))).toBe(expectedHash);
+  });
+});
+
+describe('Section 6.3 — Vector 2: join plaintext (nested + meta)', () => {
+  const input = {
+    capabilities: {
+      methods: ['wallet_signTransaction', 'wallet_signMessage'],
+      events: ['accountsChanged', 'chainChanged'],
+      chains: ['eip155:1', 'eip155:137'],
+    },
+    meta: {
+      name: 'MyWallet',
+      description: 'A multi-chain wallet',
+      url: 'https://mywallet.app',
+      icon: 'https://mywallet.app/icon.png',
+    },
+  };
+  const expected =
+    '{"capabilities":{"chains":["eip155:1","eip155:137"],"events":["accountsChanged","chainChanged"],"methods":["wallet_signTransaction","wallet_signMessage"]},"meta":{"description":"A multi-chain wallet","icon":"https://mywallet.app/icon.png","name":"MyWallet","url":"https://mywallet.app"}}';
+  const expectedHash = '9f4f3b71b0db39ba8b86173b8c78182799d0a745c68b6e89e5d8f0d3def52594';
+
+  it('produces the correct canonical output', () => {
+    expect(canonicalJson(input)).toBe(expected);
+  });
+
+  it('SHA-256 of output matches the spec', () => {
+    expect(hash(canonicalJson(input))).toBe(expectedHash);
+  });
+});
+
+describe('Section 6.3 — Vector 3: primitives', () => {
+  it('null -> "null"', () => {
+    const output = canonicalJson(null);
+    expect(output).toBe('null');
+    expect(hash(output)).toBe('74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b');
+  });
+
+  it('true -> "true"', () => {
+    const output = canonicalJson(true);
+    expect(output).toBe('true');
+    expect(hash(output)).toBe('b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b');
+  });
+
+  it('42 -> "42"', () => {
+    const output = canonicalJson(42);
+    expect(output).toBe('42');
+    expect(hash(output)).toBe('73475cb40a568e8da8a045ced110137e159f890ac4da883b6b17dc651b3a8049');
+  });
+
+  it('"hello" -> \'"hello"\'', () => {
+    const output = canonicalJson('hello');
+    expect(output).toBe('"hello"');
+    expect(hash(output)).toBe('5aa762ae383fbb727af3c7a36d4940a5b8c40a989452d2304fc958ff3f354e7a');
+  });
+});
+
+describe('Section 6.3 — Vector 4: empty containers', () => {
+  it('{} -> "{}"', () => {
+    const output = canonicalJson({});
+    expect(output).toBe('{}');
+    expect(hash(output)).toBe('44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a');
+  });
+
+  it('[] -> "[]"', () => {
+    const output = canonicalJson([]);
+    expect(output).toBe('[]');
+    expect(hash(output)).toBe('4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945');
+  });
+});
+
+describe('Section 6.3 — Vector 5: negative zero', () => {
+  it('-0 -> "0"', () => {
+    const output = canonicalJson(-0);
+    expect(output).toBe('0');
+    expect(hash(output)).toBe('5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9');
+  });
+});
+
+describe('Section 6.3 — Vector 6: escaped control character', () => {
+  it('U+0001 -> "\\u0001" (lowercase hex)', () => {
+    const output = canonicalJson('\u0001');
+    expect(output).toBe('"\\u0001"');
+    expect(hash(output)).toBe('b81cfb0a6715e53b373345b49e8ad94eb55fd777519dc539373d0634973c186e');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases from Section 6.3 rules
+// ---------------------------------------------------------------------------
+
+describe('Section 6.3 — Edge cases', () => {
+  it('negative zero inside an object serializes as 0', () => {
+    expect(canonicalJson({ value: -0 })).toBe('{"value":0}');
+  });
+
+  it('negative zero inside an array serializes as 0', () => {
+    expect(canonicalJson([-0])).toBe('[0]');
+  });
+
+  it('NaN is rejected', () => {
+    expect(() => canonicalJson(NaN)).toThrow();
+  });
+
+  it('Infinity is rejected', () => {
+    expect(() => canonicalJson(Infinity)).toThrow();
+    expect(() => canonicalJson(-Infinity)).toThrow();
+  });
+
+  it('forward slash is NOT escaped', () => {
+    const output = canonicalJson('/');
+    expect(output).toBe('"/"');
+  });
+
+  it('non-ASCII Unicode is output as literal UTF-8', () => {
+    expect(canonicalJson('中文')).toBe('"中文"');
+  });
+
+  it('control characters U+0000-U+001F use correct escape forms', () => {
+    // Short forms
+    expect(canonicalJson('\b')).toBe('"\\b"');
+    expect(canonicalJson('\t')).toBe('"\\t"');
+    expect(canonicalJson('\n')).toBe('"\\n"');
+    expect(canonicalJson('\f')).toBe('"\\f"');
+    expect(canonicalJson('\r')).toBe('"\\r"');
+
+    // All other C0 controls use lowercase \\uXXXX
+    expect(canonicalJson('\x00')).toBe('"\\u0000"');
+    expect(canonicalJson('\x01')).toBe('"\\u0001"');
+    expect(canonicalJson('\x1f')).toBe('"\\u001f"');
+  });
+
+  it('\\uXXXX escapes use lowercase hex digits only', () => {
+    for (let cp = 0; cp <= 0x1f; cp++) {
+      const result = canonicalJson(String.fromCharCode(cp));
+      // Verify no uppercase hex digits in any \u escape
+      const matches = result.match(/\\u[0-9a-fA-F]{4}/g);
+      if (matches) {
+        for (const m of matches) {
+          expect(m).toBe(m.toLowerCase());
+        }
+      }
+    }
+  });
+
+  it('no whitespace in structural output', () => {
+    const complex = {
+      z: [3, 1, 2],
+      a: { y: 'value', x: true },
+      m: null,
+    };
+    const output = canonicalJson(complex);
+    // Remove string content, then check structural chars only
+    const structural = output.replace(/"[^"]*"/g, '""');
+    expect(structural).not.toMatch(/\s/);
+  });
+
+  it('array order is preserved (NOT sorted)', () => {
+    expect(canonicalJson([3, 1, 2])).toBe('[3,1,2]');
+  });
+
+  it('object keys are sorted alphabetically at every nesting level', () => {
+    const input = { z: { b: 2, a: 1 }, a: 0 };
+    expect(canonicalJson(input)).toBe('{"a":0,"z":{"a":1,"b":2}}');
+  });
+
+  it('no trailing .0 on whole-number floats', () => {
+    expect(canonicalJson(100.0)).toBe('100');
+  });
+
+  it('numbers have no leading zeroes or + prefix', () => {
+    expect(canonicalJson(42)).toBe('42');
+    expect(canonicalJson(0)).toBe('0');
+    expect(canonicalJson(-1)).toBe('-1');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Idempotency
+// ---------------------------------------------------------------------------
+
+describe('Section 6.3 — Idempotency', () => {
+  it('parsing the canonical output and re-canonicalizing produces identical bytes', () => {
+    const input = {
+      methods: ['wallet_signTransaction', 'wallet_signMessage'],
+      events: ['accountsChanged', 'chainChanged'],
+      chains: ['eip155:1', 'eip155:137'],
+    };
+    const first = canonicalJson(input);
+    const reparsed = JSON.parse(first);
+    expect(canonicalJson(reparsed)).toBe(first);
+  });
+});