walletpair-sdk 1.0.0

package/src/__tests__/spec-compliance/sequence-numbers.test.ts

@@ -0,0 +1,300 @@
+/**
+ * WalletPair Protocol v1 — Section 6.6.1 sequence number rules.
+ *
+ * Verifies sequence number validation logic independent of the session
+ * classes, using pure functions that any implementation can replicate.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  b64urlDecode,
+  bytesToHex,
+  hexToBytes,
+  sealPayload,
+  unsealPayload,
+  generateChannelId,
+} from '../../crypto.js';
+
+// ---------------------------------------------------------------------------
+// Sequence number validator (pure model per Section 6.6.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks the highest accepted receive sequence number.
+ * Per spec: initial value is -1 (no messages accepted yet).
+ * A message MUST be rejected if its seq is not strictly greater than lastAccepted.
+ */
+class SequenceValidator {
+  /** Highest accepted sequence number. -1 means none accepted yet. */
+  private lastAccepted = -1;
+
+  /**
+   * Attempt to accept a sequence number.
+   * Returns true if accepted, false if rejected (replay/non-increasing).
+   */
+  accept(seq: number): boolean {
+    if (seq <= this.lastAccepted) return false;
+    this.lastAccepted = seq;
+    return true;
+  }
+
+  /** Current high watermark. */
+  get highWatermark(): number {
+    return this.lastAccepted;
+  }
+}
+
+/**
+ * Tracks the send sequence counter.
+ * Per spec: starts at 0, increments by 1 per sealed message.
+ * Limit at 2^31.
+ */
+class SendSequence {
+  private seq = 0;
+
+  /** Get the next sequence number for sending, or null if limit reached. */
+  next(): number | null {
+    if (this.seq >= 2 ** 31) return null;
+    return this.seq++;
+  }
+
+  /** Current value (next seq that will be used). */
+  get current(): number {
+    return this.seq;
+  }
+
+  /** Set the counter to a specific value (for testing). */
+  setTo(n: number): void {
+    this.seq = n;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Section 6.6.1 — Basic sequence number rules
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6.1 — Sequence number starts at 0', () => {
+  it('first send sequence is 0', () => {
+    const send = new SendSequence();
+    expect(send.next()).toBe(0);
+  });
+
+  it('first accepted receive sequence can be 0', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(0)).toBe(true);
+    expect(recv.highWatermark).toBe(0);
+  });
+});
+
+describe('Section 6.6.1 — Increments by 1', () => {
+  it('send counter increments by 1 per message', () => {
+    const send = new SendSequence();
+    expect(send.next()).toBe(0);
+    expect(send.next()).toBe(1);
+    expect(send.next()).toBe(2);
+    expect(send.next()).toBe(3);
+  });
+
+  it('receive validator accepts strictly increasing sequence', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(0)).toBe(true);
+    expect(recv.accept(1)).toBe(true);
+    expect(recv.accept(2)).toBe(true);
+    expect(recv.accept(3)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Replay rejection (non-increasing)
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6.1 — Reject non-increasing (replay)', () => {
+  it('rejects the same sequence number twice', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(0)).toBe(true);
+    expect(recv.accept(0)).toBe(false); // replay
+  });
+
+  it('rejects a lower sequence number after a higher one', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(5)).toBe(true);
+    expect(recv.accept(3)).toBe(false); // lower than watermark
+    expect(recv.accept(4)).toBe(false); // still lower
+    expect(recv.accept(5)).toBe(false); // equal to watermark
+  });
+
+  it('rejects seq=0 replay after initial acceptance', () => {
+    const recv = new SequenceValidator();
+    recv.accept(0);
+    recv.accept(1);
+    expect(recv.accept(0)).toBe(false);
+  });
+
+  it('multiple replays are all rejected', () => {
+    const recv = new SequenceValidator();
+    recv.accept(0);
+    for (let i = 0; i < 10; i++) {
+      expect(recv.accept(0)).toBe(false);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gaps are valid (after reconnect)
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6.1 — Gaps valid (expected after reconnect)', () => {
+  it('accepts seq=0 then seq=5 (gap of 4)', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(0)).toBe(true);
+    expect(recv.accept(5)).toBe(true);
+    expect(recv.highWatermark).toBe(5);
+  });
+
+  it('accepts large gaps', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(0)).toBe(true);
+    expect(recv.accept(1000)).toBe(true);
+    expect(recv.accept(500000)).toBe(true);
+  });
+
+  it('rejects values within a gap after the gap is established', () => {
+    const recv = new SequenceValidator();
+    recv.accept(0);
+    recv.accept(10);
+    // All values 0-10 are now below the watermark
+    for (let i = 0; i <= 10; i++) {
+      expect(recv.accept(i)).toBe(false);
+    }
+    // 11 and above are accepted
+    expect(recv.accept(11)).toBe(true);
+  });
+
+  it('gap from initial state (first message is not 0)', () => {
+    const recv = new SequenceValidator();
+    // After reconnect, the first message might not be seq=0
+    expect(recv.accept(42)).toBe(true);
+    expect(recv.highWatermark).toBe(42);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Limit at 2^31
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6.1 — Limit at 2^31', () => {
+  const LIMIT = 2 ** 31; // 2,147,483,648
+
+  it('send counter allows 2^31 - 1 as the last valid sequence', () => {
+    const send = new SendSequence();
+    send.setTo(LIMIT - 1);
+    expect(send.next()).toBe(LIMIT - 1);
+  });
+
+  it('send counter returns null (overflow) at 2^31', () => {
+    const send = new SendSequence();
+    send.setTo(LIMIT);
+    expect(send.next()).toBeNull();
+  });
+
+  it('receive validator accepts up to 2^31 - 1', () => {
+    const recv = new SequenceValidator();
+    expect(recv.accept(LIMIT - 1)).toBe(true);
+  });
+
+  it('send counter reaches limit after 2^31 messages', () => {
+    // Verify the math: starting at 0, after LIMIT sends, next() returns null
+    const send = new SendSequence();
+    send.setTo(LIMIT - 1);
+    const lastValid = send.next();
+    expect(lastValid).toBe(LIMIT - 1);
+    expect(send.next()).toBeNull(); // overflow
+  });
+
+  it('the limit is 2^31 not 2^32-1 (signed integer safety)', () => {
+    // Section 6.6.1: "The limit is 2^31 rather than 2^32 - 1 to avoid
+    // signed integer overflow in languages where 32-bit integers are signed."
+    expect(LIMIT).toBe(2147483648);
+    expect(LIMIT).toBeLessThan(2 ** 32 - 1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Sequence persistence across reconnects
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6.1 — Counters persist across reconnects', () => {
+  it('simulated reconnect preserves send counter', () => {
+    const send = new SendSequence();
+    send.next(); // 0
+    send.next(); // 1
+    send.next(); // 2
+    const savedSeq = send.current; // 3
+
+    // Simulate reconnect: new SendSequence initialized from persisted state
+    const restored = new SendSequence();
+    restored.setTo(savedSeq);
+    expect(restored.next()).toBe(3); // continues from where we left off
+    expect(restored.next()).toBe(4);
+  });
+
+  it('simulated reconnect preserves receive watermark', () => {
+    const recv = new SequenceValidator();
+    recv.accept(0);
+    recv.accept(1);
+    recv.accept(2);
+    const savedWatermark = recv.highWatermark; // 2
+
+    // Simulate reconnect: new SequenceValidator initialized from persisted state
+    const restored = new SequenceValidator();
+    // Set watermark by accepting the saved value
+    restored.accept(savedWatermark);
+    // Old sequences are rejected
+    expect(restored.accept(0)).toBe(false);
+    expect(restored.accept(1)).toBe(false);
+    expect(restored.accept(2)).toBe(false);
+    // New sequences are accepted
+    expect(restored.accept(3)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// seq_bytes encoding in sealed messages
+// ---------------------------------------------------------------------------
+
+describe('Section 6.6 — seq_bytes is 4-byte big-endian in sealed messages', () => {
+  const key = new Uint8Array(32).fill(0xaa);
+  const ch = 'bb'.repeat(32);
+
+  it('seq=0 encodes as 00000000', () => {
+    const sealed = sealPayload(key, ch, 0, { test: true });
+    const bytes = b64urlDecode(sealed);
+    expect(bytesToHex(bytes.slice(0, 4))).toBe('00000000');
+  });
+
+  it('seq=1 encodes as 00000001', () => {
+    const sealed = sealPayload(key, ch, 1, { test: true });
+    const bytes = b64urlDecode(sealed);
+    expect(bytesToHex(bytes.slice(0, 4))).toBe('00000001');
+  });
+
+  it('seq=256 encodes as 00000100', () => {
+    const sealed = sealPayload(key, ch, 256, { test: true });
+    const bytes = b64urlDecode(sealed);
+    expect(bytesToHex(bytes.slice(0, 4))).toBe('00000100');
+  });
+
+  it('seq=2^31-1 encodes as 7fffffff', () => {
+    const sealed = sealPayload(key, ch, 2 ** 31 - 1, { test: true });
+    const bytes = b64urlDecode(sealed);
+    expect(bytesToHex(bytes.slice(0, 4))).toBe('7fffffff');
+  });
+
+  it('round-trip: seq is correctly extracted from sealed payload', () => {
+    for (const seq of [0, 1, 42, 1000, 65535, 2 ** 31 - 1]) {
+      const sealed = sealPayload(key, ch, seq, { n: seq });
+      const result = unsealPayload(key, ch, sealed);
+      expect(result.seq).toBe(seq);
+    }
+  });
+});

package/src/__tests__/spec-compliance/state-machine.test.ts

@@ -0,0 +1,364 @@
+/**
+ * WalletPair Protocol v1 — Section 14 state machine transitions.
+ *
+ * Verifies that the dApp and wallet state machines accept valid
+ * transitions, reject invalid ones, and handle reconnect and race
+ * conditions correctly per the specification.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// State machine model (pure functions, no SDK dependency)
+// ---------------------------------------------------------------------------
+
+type DAppState = 'idle' | 'waiting' | 'pending_accept' | 'connected' | 'disconnected' | 'closed';
+type WalletState = 'idle' | 'waiting_accept' | 'connected' | 'disconnected' | 'closed';
+
+type DAppEvent =
+  | 'send_create'
+  | 'receive_join'
+  | 'sealed_join_verified_send_accept'
+  | 'user_rejects_send_close'
+  | 'receive_ready_connected'
+  | 'receive_close'
+  | 'receive_terminate'
+  | 'timeout'
+  | 'transport_disconnected'
+  | 'send_create_reconnect'
+  | 'receive_channel_exists'
+  | 'session_expired'
+  | 'give_up';
+
+type WalletEvent =
+  | 'send_join'
+  | 'receive_ready_connected'
+  | 'receive_close'
+  | 'receive_terminate'
+  | 'timeout'
+  | 'transport_disconnected'
+  | 'send_join_reconnect'
+  | 'receive_channel_not_found'
+  | 'session_expired'
+  | 'give_up';
+
+/** DApp state machine per Section 14. */
+function dappTransition(state: DAppState, event: DAppEvent): DAppState | null {
+  switch (state) {
+    case 'idle':
+      if (event === 'send_create') return 'waiting';
+      return null;
+    case 'waiting':
+      if (event === 'receive_join') return 'pending_accept';
+      if (event === 'receive_close' || event === 'receive_terminate') return 'closed';
+      if (event === 'timeout') return 'closed';
+      return null;
+    case 'pending_accept':
+      if (event === 'sealed_join_verified_send_accept') return 'connected';
+      if (event === 'user_rejects_send_close') return 'closed';
+      if (event === 'receive_terminate') return 'closed';
+      if (event === 'timeout') return 'closed';
+      return null;
+    case 'connected':
+      if (event === 'receive_close' || event === 'receive_terminate') return 'closed';
+      if (event === 'transport_disconnected') return 'disconnected';
+      if (event === 'session_expired') return 'closed';
+      return null;
+    case 'disconnected':
+      if (event === 'send_create_reconnect') return 'waiting';
+      if (event === 'receive_channel_exists') return 'disconnected';
+      if (event === 'session_expired') return 'closed';
+      if (event === 'give_up') return 'closed';
+      return null;
+    case 'closed':
+      return null; // terminal state
+  }
+}
+
+/** Wallet state machine per Section 14. */
+function walletTransition(state: WalletState, event: WalletEvent): WalletState | null {
+  switch (state) {
+    case 'idle':
+      if (event === 'send_join') return 'waiting_accept';
+      return null;
+    case 'waiting_accept':
+      if (event === 'receive_ready_connected') return 'connected';
+      if (event === 'receive_close' || event === 'receive_terminate') return 'closed';
+      if (event === 'timeout') return 'closed';
+      return null;
+    case 'connected':
+      if (event === 'receive_close' || event === 'receive_terminate') return 'closed';
+      if (event === 'transport_disconnected') return 'disconnected';
+      if (event === 'session_expired') return 'closed';
+      return null;
+    case 'disconnected':
+      if (event === 'send_join_reconnect') return 'waiting_accept';
+      if (event === 'receive_channel_not_found') return 'disconnected';
+      if (event === 'session_expired') return 'closed';
+      if (event === 'give_up') return 'closed';
+      return null;
+    case 'closed':
+      return null; // terminal state
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DApp state machine tests
+// ---------------------------------------------------------------------------
+
+describe('Section 14 — DApp state machine', () => {
+  describe('valid transitions: idle -> waiting -> pending_accept -> connected -> closed', () => {
+    it('full happy path', () => {
+      let state: DAppState = 'idle';
+      state = dappTransition(state, 'send_create')!;
+      expect(state).toBe('waiting');
+      state = dappTransition(state, 'receive_join')!;
+      expect(state).toBe('pending_accept');
+      state = dappTransition(state, 'sealed_join_verified_send_accept')!;
+      expect(state).toBe('connected');
+    });
+
+    it('close from connected', () => {
+      expect(dappTransition('connected', 'receive_close')).toBe('closed');
+    });
+
+    it('terminate from connected', () => {
+      expect(dappTransition('connected', 'receive_terminate')).toBe('closed');
+    });
+
+    it('session expiry from connected', () => {
+      expect(dappTransition('connected', 'session_expired')).toBe('closed');
+    });
+  });
+
+  describe('invalid transitions are rejected', () => {
+    it('cannot receive join in idle', () => {
+      expect(dappTransition('idle', 'receive_join')).toBeNull();
+    });
+
+    it('cannot send create in waiting', () => {
+      expect(dappTransition('waiting', 'send_create')).toBeNull();
+    });
+
+    it('cannot send create in pending_accept', () => {
+      expect(dappTransition('pending_accept', 'send_create')).toBeNull();
+    });
+
+    it('cannot receive join in pending_accept', () => {
+      expect(dappTransition('pending_accept', 'receive_join')).toBeNull();
+    });
+
+    it('cannot send create in connected', () => {
+      expect(dappTransition('connected', 'send_create')).toBeNull();
+    });
+
+    it('closed is terminal — all events rejected', () => {
+      const events: DAppEvent[] = [
+        'send_create', 'receive_join', 'sealed_join_verified_send_accept',
+        'receive_close', 'receive_terminate', 'timeout',
+        'transport_disconnected', 'send_create_reconnect',
+      ];
+      for (const event of events) {
+        expect(dappTransition('closed', event)).toBeNull();
+      }
+    });
+  });
+
+  describe('close and timeout paths', () => {
+    it('waiting -> close on receive_close', () => {
+      expect(dappTransition('waiting', 'receive_close')).toBe('closed');
+    });
+
+    it('waiting -> closed on timeout', () => {
+      expect(dappTransition('waiting', 'timeout')).toBe('closed');
+    });
+
+    it('pending_accept -> closed on user_rejects_send_close', () => {
+      expect(dappTransition('pending_accept', 'user_rejects_send_close')).toBe('closed');
+    });
+
+    it('pending_accept -> closed on timeout', () => {
+      expect(dappTransition('pending_accept', 'timeout')).toBe('closed');
+    });
+  });
+
+  describe('reconnect: disconnected -> waiting with same ch', () => {
+    it('transport disconnect moves to disconnected', () => {
+      expect(dappTransition('connected', 'transport_disconnected')).toBe('disconnected');
+    });
+
+    it('send_create_reconnect from disconnected goes to waiting', () => {
+      expect(dappTransition('disconnected', 'send_create_reconnect')).toBe('waiting');
+    });
+
+    it('session expiry from disconnected goes to closed', () => {
+      expect(dappTransition('disconnected', 'session_expired')).toBe('closed');
+    });
+
+    it('give up from disconnected goes to closed', () => {
+      expect(dappTransition('disconnected', 'give_up')).toBe('closed');
+    });
+  });
+
+  describe('race condition: channel_exists handling', () => {
+    it('receive_channel_exists stays in disconnected (transient failure)', () => {
+      expect(dappTransition('disconnected', 'receive_channel_exists')).toBe('disconnected');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Wallet state machine tests
+// ---------------------------------------------------------------------------
+
+describe('Section 14 — Wallet state machine', () => {
+  describe('valid transitions: idle -> waiting_accept -> connected -> closed', () => {
+    it('full happy path', () => {
+      let state: WalletState = 'idle';
+      state = walletTransition(state, 'send_join')!;
+      expect(state).toBe('waiting_accept');
+      state = walletTransition(state, 'receive_ready_connected')!;
+      expect(state).toBe('connected');
+    });
+
+    it('close from connected', () => {
+      expect(walletTransition('connected', 'receive_close')).toBe('closed');
+    });
+
+    it('terminate from connected', () => {
+      expect(walletTransition('connected', 'receive_terminate')).toBe('closed');
+    });
+  });
+
+  describe('invalid transitions are rejected', () => {
+    it('cannot receive_ready_connected in idle', () => {
+      expect(walletTransition('idle', 'receive_ready_connected')).toBeNull();
+    });
+
+    it('cannot send_join in waiting_accept', () => {
+      expect(walletTransition('waiting_accept', 'send_join')).toBeNull();
+    });
+
+    it('cannot send_join in connected', () => {
+      expect(walletTransition('connected', 'send_join')).toBeNull();
+    });
+
+    it('closed is terminal — all events rejected', () => {
+      const events: WalletEvent[] = [
+        'send_join', 'receive_ready_connected', 'receive_close',
+        'receive_terminate', 'timeout', 'transport_disconnected',
+        'send_join_reconnect',
+      ];
+      for (const event of events) {
+        expect(walletTransition('closed', event)).toBeNull();
+      }
+    });
+  });
+
+  describe('close and timeout paths', () => {
+    it('waiting_accept -> closed on receive_close', () => {
+      expect(walletTransition('waiting_accept', 'receive_close')).toBe('closed');
+    });
+
+    it('waiting_accept -> closed on timeout', () => {
+      expect(walletTransition('waiting_accept', 'timeout')).toBe('closed');
+    });
+  });
+
+  describe('reconnect: disconnected -> waiting_accept with same ch', () => {
+    it('transport disconnect moves to disconnected', () => {
+      expect(walletTransition('connected', 'transport_disconnected')).toBe('disconnected');
+    });
+
+    it('send_join_reconnect from disconnected goes to waiting_accept', () => {
+      expect(walletTransition('disconnected', 'send_join_reconnect')).toBe('waiting_accept');
+    });
+
+    it('session expiry from disconnected goes to closed', () => {
+      expect(walletTransition('disconnected', 'session_expired')).toBe('closed');
+    });
+
+    it('give up from disconnected goes to closed', () => {
+      expect(walletTransition('disconnected', 'give_up')).toBe('closed');
+    });
+  });
+
+  describe('race condition: channel_not_found handling', () => {
+    it('receive_channel_not_found stays in disconnected (transient failure)', () => {
+      expect(walletTransition('disconnected', 'receive_channel_not_found')).toBe('disconnected');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Cross-cutting state machine properties
+// ---------------------------------------------------------------------------
+
+describe('Section 14 — Cross-cutting properties', () => {
+  it('closed is terminal for dApp — no outgoing transitions', () => {
+    const allDappEvents: DAppEvent[] = [
+      'send_create', 'receive_join', 'sealed_join_verified_send_accept',
+      'user_rejects_send_close', 'receive_ready_connected', 'receive_close',
+      'receive_terminate', 'timeout', 'transport_disconnected',
+      'send_create_reconnect', 'receive_channel_exists', 'session_expired',
+      'give_up',
+    ];
+    for (const event of allDappEvents) {
+      expect(dappTransition('closed', event)).toBeNull();
+    }
+  });
+
+  it('closed is terminal for wallet — no outgoing transitions', () => {
+    const allWalletEvents: WalletEvent[] = [
+      'send_join', 'receive_ready_connected', 'receive_close',
+      'receive_terminate', 'timeout', 'transport_disconnected',
+      'send_join_reconnect', 'receive_channel_not_found', 'session_expired',
+      'give_up',
+    ];
+    for (const event of allWalletEvents) {
+      expect(walletTransition('closed', event)).toBeNull();
+    }
+  });
+
+  it('reconnect path reuses the full handshake flow (create/join/accept)', () => {
+    // DApp: disconnected -> waiting (via create) -> pending_accept (via join) -> connected
+    let dapp: DAppState = 'disconnected';
+    dapp = dappTransition(dapp, 'send_create_reconnect')!;
+    expect(dapp).toBe('waiting');
+    dapp = dappTransition(dapp, 'receive_join')!;
+    expect(dapp).toBe('pending_accept');
+    dapp = dappTransition(dapp, 'sealed_join_verified_send_accept')!;
+    expect(dapp).toBe('connected');
+
+    // Wallet: disconnected -> waiting_accept (via join) -> connected
+    let wallet: WalletState = 'disconnected';
+    wallet = walletTransition(wallet, 'send_join_reconnect')!;
+    expect(wallet).toBe('waiting_accept');
+    wallet = walletTransition(wallet, 'receive_ready_connected')!;
+    expect(wallet).toBe('connected');
+  });
+
+  it('race condition recovery: multiple channel_exists before successful reconnect', () => {
+    let state: DAppState = 'disconnected';
+    // Multiple transient failures
+    state = dappTransition(state, 'receive_channel_exists')!;
+    expect(state).toBe('disconnected');
+    state = dappTransition(state, 'receive_channel_exists')!;
+    expect(state).toBe('disconnected');
+    // Eventually succeeds
+    state = dappTransition(state, 'send_create_reconnect')!;
+    expect(state).toBe('waiting');
+  });
+
+  it('race condition recovery: multiple channel_not_found before wallet reconnects', () => {
+    let state: WalletState = 'disconnected';
+    // Multiple transient failures
+    state = walletTransition(state, 'receive_channel_not_found')!;
+    expect(state).toBe('disconnected');
+    state = walletTransition(state, 'receive_channel_not_found')!;
+    expect(state).toBe('disconnected');
+    // Eventually succeeds
+    state = walletTransition(state, 'send_join_reconnect')!;
+    expect(state).toBe('waiting_accept');
+  });
+});