walletpair-sdk 1.0.0

package/src/ble/framing.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect } from 'vitest';
+import { frameMessage, Defragmenter, DEFAULT_FRAME_PAYLOAD, MIN_FRAME_PAYLOAD } from './framing.js';
+
+describe('frameMessage', () => {
+  it('frames empty string as single frame with both flags', () => {
+    const frames = frameMessage('');
+    expect(frames).toHaveLength(1);
+    expect(frames[0]![0]).toBe(0x03); // first + last
+    expect(frames[0]).toHaveLength(3); // header only
+  });
+
+  it('frames short message as single frame', () => {
+    const msg = '{"v":1,"t":"ping"}';
+    const frames = frameMessage(msg);
+    expect(frames).toHaveLength(1);
+    expect(frames[0]![0]).toBe(0x03); // first + last
+
+    // Verify total length in header
+    const payload = new TextEncoder().encode(msg);
+    const totalLen = (frames[0]![1]! << 8) | frames[0]![2]!;
+    expect(totalLen).toBe(payload.length);
+
+    // Verify payload
+    const extracted = frames[0]!.subarray(3);
+    expect(new TextDecoder().decode(extracted)).toBe(msg);
+  });
+
+  it('fragments message exceeding maxPayload', () => {
+    const longMsg = 'A'.repeat(100);
+    const frames = frameMessage(longMsg, 30);
+
+    expect(frames.length).toBeGreaterThan(1);
+
+    // First frame: flag=0x01 (first only)
+    expect(frames[0]![0]! & 0x01).toBe(0x01); // first bit set
+    expect(frames[0]![0]! & 0x02).toBe(0x00); // last bit not set
+
+    // Last frame: flag=0x02 (last only)
+    const lastFrame = frames[frames.length - 1]!;
+    expect(lastFrame[0]! & 0x01).toBe(0x00); // first bit not set
+    expect(lastFrame[0]! & 0x02).toBe(0x02); // last bit set
+
+    // Middle frames (if any): flag=0x00
+    for (let i = 1; i < frames.length - 1; i++) {
+      expect(frames[i]![0]).toBe(0x00);
+    }
+  });
+
+  it('first frame contains total length in header', () => {
+    const msg = 'X'.repeat(200);
+    const frames = frameMessage(msg, 50);
+    const totalLen = (frames[0]![1]! << 8) | frames[0]![2]!;
+    expect(totalLen).toBe(new TextEncoder().encode(msg).length);
+  });
+
+  it('respects MIN_FRAME_PAYLOAD even when maxPayload is smaller', () => {
+    const msg = 'A'.repeat(100);
+    const frames = frameMessage(msg, 5); // smaller than MIN_FRAME_PAYLOAD
+    // Each payload chunk should be at least MIN_FRAME_PAYLOAD
+    for (const frame of frames) {
+      const payloadSize = frame.length - 3;
+      if (payloadSize > 0) {
+        // Last frame might be shorter
+        if ((frame[0]! & 0x02) === 0) {
+          expect(payloadSize).toBeGreaterThanOrEqual(MIN_FRAME_PAYLOAD);
+        }
+      }
+    }
+  });
+
+  it('uses DEFAULT_FRAME_PAYLOAD when no maxPayload specified', () => {
+    const msg = 'B'.repeat(DEFAULT_FRAME_PAYLOAD + 100);
+    const frames = frameMessage(msg);
+    expect(frames.length).toBe(2); // slightly over one full frame
+  });
+});
+
+describe('Defragmenter', () => {
+  it('reassembles single-frame message', () => {
+    const defrag = new Defragmenter();
+    const msg = '{"hello":"world"}';
+    const frames = frameMessage(msg);
+
+    expect(frames).toHaveLength(1);
+    const result = defrag.push(frames[0]!);
+    expect(result).toBe(msg);
+  });
+
+  it('reassembles multi-frame message', () => {
+    const defrag = new Defragmenter();
+    const msg = 'A'.repeat(200);
+    const frames = frameMessage(msg, 50);
+
+    expect(frames.length).toBeGreaterThan(1);
+
+    for (let i = 0; i < frames.length - 1; i++) {
+      const result = defrag.push(frames[i]!);
+      expect(result).toBeNull(); // not complete yet
+    }
+
+    const result = defrag.push(frames[frames.length - 1]!);
+    expect(result).toBe(msg);
+  });
+
+  it('handles multiple messages in sequence', () => {
+    const defrag = new Defragmenter();
+
+    const msg1 = '{"first":true}';
+    const msg2 = '{"second":true}';
+
+    const frames1 = frameMessage(msg1);
+    const frames2 = frameMessage(msg2);
+
+    expect(defrag.push(frames1[0]!)).toBe(msg1);
+    expect(defrag.push(frames2[0]!)).toBe(msg2);
+  });
+
+  it('handles interleaved fragmented messages correctly via reset', () => {
+    const defrag = new Defragmenter();
+
+    // Start a message
+    const longMsg = 'X'.repeat(100);
+    const frames = frameMessage(longMsg, 30);
+    defrag.push(frames[0]!); // first fragment
+
+    // Reset and start new message
+    defrag.reset();
+    const shortMsg = '{"ok":true}';
+    const shortFrames = frameMessage(shortMsg);
+    expect(defrag.push(shortFrames[0]!)).toBe(shortMsg);
+  });
+
+  it('ignores frames shorter than 3 bytes', () => {
+    const defrag = new Defragmenter();
+    expect(defrag.push(new Uint8Array([0x03, 0x00]))).toBeNull();
+    expect(defrag.push(new Uint8Array([0x03]))).toBeNull();
+    expect(defrag.push(new Uint8Array([]))).toBeNull();
+  });
+
+  it('reassembles unicode content correctly', () => {
+    const defrag = new Defragmenter();
+    const msg = '{"text":"你好世界🌍"}';
+    const frames = frameMessage(msg, 20);
+
+    let result: string | null = null;
+    for (const frame of frames) {
+      result = defrag.push(frame);
+    }
+    expect(result).toBe(msg);
+  });
+
+  it('handles large messages (> 64KB total length)', () => {
+    const defrag = new Defragmenter();
+    // total_length field is 2 bytes, so max representable is 65535
+    // But the code handles growth beyond that via the safety check
+    const msg = 'Z'.repeat(1000);
+    const frames = frameMessage(msg, 100);
+
+    let result: string | null = null;
+    for (const frame of frames) {
+      result = defrag.push(frame);
+    }
+    expect(result).toBe(msg);
+  });
+
+  it('reset() clears internal state', () => {
+    const defrag = new Defragmenter();
+    const longMsg = 'Y'.repeat(100);
+    const frames = frameMessage(longMsg, 30);
+
+    // Push first frame
+    defrag.push(frames[0]!);
+    defrag.reset();
+
+    // After reset, pushing a complete single-frame message should work
+    const shortMsg = '{"reset":true}';
+    const shortFrames = frameMessage(shortMsg);
+    expect(defrag.push(shortFrames[0]!)).toBe(shortMsg);
+  });
+
+  it('frame/defrag round-trip preserves exact content for various sizes', () => {
+    const defrag = new Defragmenter();
+    for (const size of [0, 1, 19, 20, 21, 50, 100, 509, 510, 1000]) {
+      defrag.reset();
+      // Size 0 frame has no payload text, skip
+      if (size === 0) continue;
+      const msg = JSON.stringify({ data: 'x'.repeat(size) });
+      const frames = frameMessage(msg, 50);
+      let result: string | null = null;
+      for (const frame of frames) {
+        result = defrag.push(frame);
+      }
+      expect(result).toBe(msg);
+    }
+  });
+});

package/src/ble/framing.ts

@@ -0,0 +1,100 @@
+/**
+ * BLE message framing per WalletPair Protocol Section 19.5.
+ *
+ * Frame format: [1 byte flags] [2 bytes total_length BE] [payload fragment]
+ *
+ *   flags bit 0: first fragment
+ *   flags bit 1: last fragment
+ */
+
+const FLAG_FIRST = 0x01;
+const FLAG_LAST = 0x02;
+
+export const DEFAULT_FRAME_PAYLOAD = 509;
+export const MIN_FRAME_PAYLOAD = 20;
+
+export const BLE_SERVICE_UUID = 'e3a10001-7770-4270-8000-000077700001';
+export const BLE_WRITE_CHAR_UUID = 'e3a10002-7770-4270-8000-000077700001';
+export const BLE_NOTIFY_CHAR_UUID = 'e3a10003-7770-4270-8000-000077700001';
+
+/** Split a JSON string into BLE frames. */
+export function frameMessage(
+  jsonStr: string,
+  maxPayload = DEFAULT_FRAME_PAYLOAD,
+): Uint8Array[] {
+  const payload = new TextEncoder().encode(jsonStr);
+  const frames: Uint8Array[] = [];
+
+  if (payload.length === 0) {
+    const frame = new Uint8Array(3);
+    frame[0] = FLAG_FIRST | FLAG_LAST;
+    return [frame];
+  }
+
+  const chunkSize = Math.max(maxPayload, MIN_FRAME_PAYLOAD);
+
+  for (let offset = 0; offset < payload.length; offset += chunkSize) {
+    const isFirst = offset === 0;
+    const end = Math.min(offset + chunkSize, payload.length);
+    const isLast = end === payload.length;
+    const fragment = payload.subarray(offset, end);
+
+    const frame = new Uint8Array(3 + fragment.length);
+    frame[0] = (isFirst ? FLAG_FIRST : 0) | (isLast ? FLAG_LAST : 0);
+    if (isFirst) {
+      frame[1] = (payload.length >> 8) & 0xff;
+      frame[2] = payload.length & 0xff;
+    }
+    frame.set(fragment, 3);
+    frames.push(frame);
+  }
+
+  return frames;
+}
+
+/** Accumulates BLE frames and emits complete JSON strings. */
+export class Defragmenter {
+  private buffer: Uint8Array | null = null;
+  private offset = 0;
+
+  push(data: Uint8Array): string | null {
+    if (data.length < 3) return null;
+
+    const flags = data[0]!;
+    const isFirst = !!(flags & FLAG_FIRST);
+    const isLast = !!(flags & FLAG_LAST);
+    const fragment = data.subarray(3);
+
+    if (isFirst) {
+      const totalLength = (data[1]! << 8) | data[2]!;
+      this.buffer = new Uint8Array(totalLength || fragment.length);
+      this.offset = 0;
+    }
+
+    if (this.buffer) {
+      if (this.offset + fragment.length <= this.buffer.length) {
+        this.buffer.set(fragment, this.offset);
+      } else {
+        const grown = new Uint8Array(this.offset + fragment.length);
+        grown.set(this.buffer.subarray(0, this.offset));
+        grown.set(fragment, this.offset);
+        this.buffer = grown;
+      }
+      this.offset += fragment.length;
+    }
+
+    if (isLast && this.buffer) {
+      const result = new TextDecoder().decode(this.buffer.subarray(0, this.offset));
+      this.buffer = null;
+      this.offset = 0;
+      return result;
+    }
+
+    return null;
+  }
+
+  reset(): void {
+    this.buffer = null;
+    this.offset = 0;
+  }
+}

package/src/ble/index.ts

@@ -0,0 +1,18 @@
+/**
+ * BLE transport exports.
+ *
+ * Re-exports framing utilities and provides the Web Bluetooth Central transport.
+ * Safe to import on any platform — Web Bluetooth availability is checked at runtime.
+ */
+
+export {
+  frameMessage,
+  Defragmenter,
+  DEFAULT_FRAME_PAYLOAD,
+  MIN_FRAME_PAYLOAD,
+  BLE_SERVICE_UUID,
+  BLE_WRITE_CHAR_UUID,
+  BLE_NOTIFY_CHAR_UUID,
+} from './framing.js';
+
+export { WebBleCentralTransport, isWebBleSupported } from './web-ble-transport.js';

package/src/ble/web-ble-transport.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { WebBleCentralTransport, isWebBleSupported } from './web-ble-transport.js';
+
+// ── Mock Web Bluetooth API ──────────────────────────────────────────
+
+function createMockCharacteristic() {
+  const listeners = new Map<string, Function>();
+  return {
+    writeValueWithoutResponse: vi.fn().mockResolvedValue(undefined),
+    startNotifications: vi.fn().mockResolvedValue(undefined),
+    addEventListener: vi.fn((evt: string, fn: Function) => { listeners.set(evt, fn); }),
+    removeEventListener: vi.fn((evt: string) => { listeners.delete(evt); }),
+    _fire: (evt: string, data: any) => listeners.get(evt)?.(data),
+    value: null as DataView | null,
+  };
+}
+
+function createMockBleDevice() {
+  const listeners = new Map<string, Function>();
+  const writeChar = createMockCharacteristic();
+  const notifyChar = createMockCharacteristic();
+
+  const service = {
+    getCharacteristic: vi.fn((uuid: string) => {
+      // BLE_WRITE_CHAR_UUID = 'e3a10002-...'
+      if (uuid.includes('10002')) return Promise.resolve(writeChar);
+      if (uuid.includes('10003')) return Promise.resolve(notifyChar);
+      return Promise.reject(new Error('unknown characteristic'));
+    }),
+  };
+
+  const server = {
+    connect: vi.fn().mockResolvedValue(undefined),
+    getPrimaryService: vi.fn().mockResolvedValue(service),
+    connected: true,
+  };
+
+  // Make connect() return the server with getPrimaryService
+  server.connect.mockResolvedValue(server);
+
+  const device = {
+    gatt: {
+      connect: vi.fn().mockResolvedValue(server),
+      connected: true,
+      disconnect: vi.fn(),
+    },
+    addEventListener: vi.fn((evt: string, fn: Function) => { listeners.set(evt, fn); }),
+    removeEventListener: vi.fn((evt: string) => { listeners.delete(evt); }),
+    _fireDisconnect: () => listeners.get('gattserverdisconnected')?.({} as Event),
+  };
+
+  return { device, writeChar, notifyChar, server };
+}
+
+function mockNavigatorBluetooth(device: any) {
+  Object.defineProperty(globalThis, 'navigator', {
+    value: {
+      bluetooth: {
+        requestDevice: vi.fn().mockResolvedValue(device),
+      },
+    },
+    writable: true,
+    configurable: true,
+  });
+}
+
+function clearNavigatorBluetooth() {
+  Object.defineProperty(globalThis, 'navigator', {
+    value: undefined,
+    writable: true,
+    configurable: true,
+  });
+}
+
+// ── isWebBleSupported ───────────────────────────────────────────────
+
+describe('isWebBleSupported', () => {
+  it('returns false when navigator is undefined', () => {
+    clearNavigatorBluetooth();
+    expect(isWebBleSupported()).toBe(false);
+  });
+
+  it('returns false when navigator.bluetooth is missing', () => {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: {},
+      writable: true,
+      configurable: true,
+    });
+    expect(isWebBleSupported()).toBe(false);
+  });
+
+  it('returns true when navigator.bluetooth exists', () => {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { bluetooth: {} },
+      writable: true,
+      configurable: true,
+    });
+    expect(isWebBleSupported()).toBe(true);
+  });
+});
+
+// ── WebBleCentralTransport ──────────────────────────────────────────
+
+describe('WebBleCentralTransport', () => {
+  let transport: WebBleCentralTransport;
+
+  beforeEach(() => {
+    transport = new WebBleCentralTransport();
+    clearNavigatorBluetooth();
+  });
+
+  it('starts in disconnected state', () => {
+    expect(transport.state).toBe('disconnected');
+  });
+
+  it('connect() throws when Web Bluetooth is not supported', async () => {
+    await expect(transport.connect()).rejects.toThrow('Web Bluetooth is not supported');
+  });
+
+  it('connect() transitions through connecting to connected', async () => {
+    const { device } = createMockBleDevice();
+    mockNavigatorBluetooth(device);
+
+    const openHandler = vi.fn();
+    transport.onOpen(openHandler);
+
+    await transport.connect();
+
+    expect(transport.state).toBe('connected');
+    expect(openHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('connect() sets up GATT characteristics', async () => {
+    const { device, notifyChar } = createMockBleDevice();
+    mockNavigatorBluetooth(device);
+
+    await transport.connect();
+
+    expect(notifyChar.startNotifications).toHaveBeenCalled();
+    expect(notifyChar.addEventListener).toHaveBeenCalledWith(
+      'characteristicvaluechanged',
+      expect.any(Function),
+    );
+  });
+
+  it('disconnect() calls gatt.disconnect and cleans up', async () => {
+    const { device } = createMockBleDevice();
+    mockNavigatorBluetooth(device);
+
+    await transport.connect();
+    transport.disconnect();
+
+    expect(device.gatt.disconnect).toHaveBeenCalled();
+    expect(transport.state).toBe('disconnected');
+  });
+
+  it('disconnect() is safe to call when not connected', () => {
+    expect(() => transport.disconnect()).not.toThrow();
+    expect(transport.state).toBe('disconnected');
+  });
+
+  it('send() does nothing when not connected', () => {
+    transport.send({ v: 1, t: 'ping', ch: 'abc' } as any);
+    // Should not throw
+  });
+
+  it('onClose handler fires on GATT disconnect', async () => {
+    const { device } = createMockBleDevice();
+    mockNavigatorBluetooth(device);
+
+    const closeHandler = vi.fn();
+    transport.onClose(closeHandler);
+
+    await transport.connect();
+    device._fireDisconnect();
+
+    expect(closeHandler).toHaveBeenCalledTimes(1);
+    expect(transport.state).toBe('disconnected');
+  });
+
+  it('handler registration methods work', () => {
+    const msgHandler = vi.fn();
+    const closeHandler = vi.fn();
+    const openHandler = vi.fn();
+
+    transport.onMessage(msgHandler);
+    transport.onClose(closeHandler);
+    transport.onOpen(openHandler);
+
+    // No throws — handlers registered
+  });
+});

package/src/ble/web-ble-transport.ts

@@ -0,0 +1,116 @@
+/**
+ * Web Bluetooth Central transport for dApp side.
+ *
+ * The dApp acts as BLE Central and connects to the wallet's GATT Peripheral.
+ * Safe to import anywhere — checks Web Bluetooth availability at runtime.
+ */
+
+/// <reference path="./web-bluetooth.d.ts" />
+
+import type { Transport, TransportState, ProtocolMessage } from '../types.js';
+import {
+  BLE_SERVICE_UUID,
+  BLE_WRITE_CHAR_UUID,
+  BLE_NOTIFY_CHAR_UUID,
+  frameMessage,
+  Defragmenter,
+} from './framing.js';
+
+export function isWebBleSupported(): boolean {
+  return typeof navigator !== 'undefined' && !!navigator.bluetooth;
+}
+
+export class WebBleCentralTransport implements Transport {
+  state: TransportState = 'disconnected';
+
+  private device: BluetoothDevice | null = null;
+  private writeChar: BluetoothRemoteGATTCharacteristic | null = null;
+  private notifyChar: BluetoothRemoteGATTCharacteristic | null = null;
+  private defrag = new Defragmenter();
+  private mtuPayload = 509;
+
+  private messageHandler: ((msg: ProtocolMessage) => void) | null = null;
+  private closeHandler: (() => void) | null = null;
+  private openHandler: (() => void) | null = null;
+
+  onMessage(handler: (msg: ProtocolMessage) => void): void { this.messageHandler = handler; }
+  onClose(handler: () => void): void { this.closeHandler = handler; }
+  onOpen(handler: () => void): void { this.openHandler = handler; }
+
+  async connect(): Promise<void> {
+    if (!isWebBleSupported()) {
+      throw new Error('Web Bluetooth is not supported in this environment');
+    }
+
+    this.state = 'connecting';
+
+    const device = await navigator.bluetooth!.requestDevice({
+      filters: [
+        { namePrefix: 'WalletPair' },
+        { services: [BLE_SERVICE_UUID] },
+      ],
+      optionalServices: [BLE_SERVICE_UUID],
+    });
+
+    this.device = device;
+    device.addEventListener('gattserverdisconnected', this.onDisconnect);
+
+    const server = await device.gatt!.connect();
+    const service = await server.getPrimaryService(BLE_SERVICE_UUID);
+
+    this.writeChar = await service.getCharacteristic(BLE_WRITE_CHAR_UUID);
+    this.notifyChar = await service.getCharacteristic(BLE_NOTIFY_CHAR_UUID);
+
+    await this.notifyChar.startNotifications();
+    this.notifyChar.addEventListener('characteristicvaluechanged', this.onNotification);
+
+    this.state = 'connected';
+    this.openHandler?.();
+  }
+
+  send(msg: ProtocolMessage): void {
+    if (!this.writeChar || this.state !== 'connected') return;
+    const frames = frameMessage(JSON.stringify(msg), this.mtuPayload);
+    // Send frames sequentially
+    let chain = Promise.resolve();
+    for (const frame of frames) {
+      chain = chain.then(() => this.writeChar!.writeValueWithoutResponse(frame as unknown as ArrayBuffer));
+    }
+  }
+
+  disconnect(): void {
+    if (this.device?.gatt?.connected) {
+      this.device.gatt.disconnect();
+    }
+    this.cleanup();
+  }
+
+  private onNotification = (event: Event): void => {
+    const target = event.target as BluetoothRemoteGATTCharacteristic;
+    const dv = target.value!;
+    const data = new Uint8Array(dv.buffer, dv.byteOffset, dv.byteLength);
+    const json = this.defrag.push(data);
+    if (json && this.messageHandler) {
+      try { this.messageHandler(JSON.parse(json)); } catch { /* bad json */ }
+    }
+  };
+
+  private onDisconnect = (): void => {
+    this.cleanup();
+    this.closeHandler?.();
+  };
+
+  private cleanup(): void {
+    if (this.notifyChar) {
+      this.notifyChar.removeEventListener('characteristicvaluechanged', this.onNotification);
+    }
+    if (this.device) {
+      this.device.removeEventListener('gattserverdisconnected', this.onDisconnect);
+    }
+    this.device = null;
+    this.writeChar = null;
+    this.notifyChar = null;
+    this.defrag.reset();
+    this.state = 'disconnected';
+  }
+}

package/src/ble/web-bluetooth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Ambient type declarations for the Web Bluetooth API.
+ * Avoids requiring @types/web-bluetooth as a dependency.
+ */
+
+interface BluetoothDevice extends EventTarget {
+  readonly id: string;
+  readonly name?: string | undefined;
+  readonly gatt?: BluetoothRemoteGATTServer | undefined;
+}
+
+interface BluetoothRemoteGATTServer {
+  readonly device: BluetoothDevice;
+  readonly connected: boolean;
+  connect(): Promise<BluetoothRemoteGATTServer>;
+  disconnect(): void;
+  getPrimaryService(service: string): Promise<BluetoothRemoteGATTService>;
+}
+
+interface BluetoothRemoteGATTService {
+  getCharacteristic(characteristic: string): Promise<BluetoothRemoteGATTCharacteristic>;
+}
+
+interface BluetoothRemoteGATTCharacteristic extends EventTarget {
+  readonly value: DataView | null;
+  startNotifications(): Promise<BluetoothRemoteGATTCharacteristic>;
+  stopNotifications(): Promise<BluetoothRemoteGATTCharacteristic>;
+  writeValueWithoutResponse(value: BufferSource): Promise<void>;
+}
+
+interface BluetoothRequestDeviceFilter {
+  namePrefix?: string;
+  services?: string[];
+}
+
+interface RequestDeviceOptions {
+  filters?: BluetoothRequestDeviceFilter[];
+  optionalServices?: string[];
+}
+
+interface Bluetooth {
+  requestDevice(options: RequestDeviceOptions): Promise<BluetoothDevice>;
+}
+
+interface Navigator {
+  bluetooth?: Bluetooth | undefined;
+}