walletpair-sdk 1.0.0

package/src/test-helpers.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared test helpers — mock transport for unit testing sessions.
+ */
+
+import type { Capabilities, Transport, TransportState, ProtocolMessage, WalletMeta } from './types.js';
+import {
+  b64urlDecode,
+  computeSharedSecret,
+  deriveJoinEncryptionKey,
+  deriveSessionKey,
+  sealJoin,
+} from './crypto.js';
+import type { X25519KeyPair } from './crypto.js';
+
+export const DEFAULT_TEST_CAPABILITIES: Capabilities = {
+  methods: ['wallet_getAccounts', 'wallet_signMessage'],
+  events: ['accountsChanged', 'chainChanged'],
+  chains: ['eip155:1'],
+};
+
+/** Extract the JSON payload from a signed or unsigned snapshot string. */
+export function parseSnapshot(signed: string): Record<string, unknown> {
+  // Signed format: "<64-hex-mac>.<json>"
+  if (signed.length > 65 && signed[64] === '.') {
+    return JSON.parse(signed.slice(65));
+  }
+  return JSON.parse(signed);
+}
+
+export const DEFAULT_TEST_WALLET_META: WalletMeta = {
+  name: 'Test Wallet',
+  description: 'Test wallet',
+  url: 'https://wallet.test',
+  icon: 'https://wallet.test/icon.png',
+};
+
+export function makeSealedJoin(
+  channelId: string,
+  dappPubKeyB64: string,
+  walletKp: X25519KeyPair,
+  capabilities: Capabilities = DEFAULT_TEST_CAPABILITIES,
+  meta: WalletMeta = DEFAULT_TEST_WALLET_META,
+): string {
+  const dappPub = b64urlDecode(dappPubKeyB64);
+  const shared = computeSharedSecret(walletKp.privateKey, dappPub);
+  const rootKey = deriveSessionKey(shared, channelId);
+  const joinKey = deriveJoinEncryptionKey(rootKey, channelId);
+  const sealed = sealJoin(joinKey, channelId, capabilities, meta);
+  shared.fill(0);
+  rootKey.fill(0);
+  joinKey.fill(0);
+  return sealed;
+}
+
+export function makeJoinBody(
+  channelId: string,
+  dappPubKeyB64: string,
+  walletKp: X25519KeyPair,
+  capabilities: Capabilities = DEFAULT_TEST_CAPABILITIES,
+  meta: WalletMeta = DEFAULT_TEST_WALLET_META,
+): { sealed_join: string } {
+  return {
+    sealed_join: makeSealedJoin(channelId, dappPubKeyB64, walletKp, capabilities, meta),
+  };
+}
+
+/**
+ * In-memory transport for testing. Two MockTransports can be linked
+ * to simulate a relay (messages sent on one arrive on the other).
+ */
+export class MockTransport implements Transport {
+  state: TransportState = 'disconnected';
+  sent: ProtocolMessage[] = [];
+
+  private messageHandler: ((msg: ProtocolMessage) => void) | null = null;
+  private closeHandler: (() => void) | null = null;
+  private openHandler: (() => void) | null = null;
+
+  /** Link to the peer's transport. */
+  peer: MockTransport | 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> {
+    this.state = 'connected';
+    this.openHandler?.();
+  }
+
+  send(msg: ProtocolMessage): void {
+    this.sent.push(msg);
+    // Deliver to peer asynchronously (simulates relay)
+    if (this.peer) {
+      const peer = this.peer;
+      queueMicrotask(() => peer.receive(msg));
+    }
+  }
+
+  disconnect(): void {
+    this.state = 'disconnected';
+  }
+
+  /** Simulate receiving a message from the relay. */
+  receive(msg: ProtocolMessage): void {
+    this.messageHandler?.(msg);
+  }
+
+  /** Simulate transport close (disconnect from relay). */
+  simulateClose(): void {
+    this.state = 'disconnected';
+    this.closeHandler?.();
+  }
+}
+
+/**
+ * Create a pair of linked mock transports.
+ * Messages sent on dapp arrive on wallet and vice versa.
+ */
+export function createLinkedTransports(): { dapp: MockTransport; wallet: MockTransport } {
+  const dapp = new MockTransport();
+  const wallet = new MockTransport();
+  dapp.peer = wallet;
+  wallet.peer = dapp;
+  return { dapp, wallet };
+}
+
+/**
+ * Simulate the relay's role: when dApp sends "create", respond with "ready.waiting".
+ * When wallet sends "join", forward to dApp and respond with "ready.waiting".
+ * When dApp sends "accept", respond with "ready.connected" to both.
+ */
+export class MockRelay {
+  private dappTransport: MockTransport;
+  private walletTransport: MockTransport;
+
+  constructor(dapp: MockTransport, wallet: MockTransport) {
+    this.dappTransport = dapp;
+    this.walletTransport = wallet;
+
+    // Intercept sends and inject relay behavior
+    const origDappSend = dapp.send.bind(dapp);
+    dapp.send = (msg: ProtocolMessage) => {
+      origDappSend(msg);
+      this.handleDappMessage(msg);
+    };
+
+    const origWalletSend = wallet.send.bind(wallet);
+    wallet.send = (msg: ProtocolMessage) => {
+      origWalletSend(msg);
+      this.handleWalletMessage(msg);
+    };
+
+    // Don't forward to peer directly — relay controls message flow
+    dapp.peer = null;
+    wallet.peer = null;
+  }
+
+  private handleDappMessage(msg: ProtocolMessage): void {
+    if (msg.t === 'create') {
+      queueMicrotask(() => {
+        this.dappTransport.receive({
+          v: 1, t: 'ready', ch: msg.ch,
+          ts: Date.now(), from: '_adapter',
+          body: { state: 'waiting', reconnect: false, remote: null },
+        } as ProtocolMessage);
+      });
+    } else if (msg.t === 'accept') {
+      queueMicrotask(() => {
+        const target = (msg.body as any).target;
+        this.dappTransport.receive({
+          v: 1, t: 'ready', ch: msg.ch,
+          ts: Date.now(), from: '_adapter',
+          body: { state: 'connected', reconnect: false, remote: target },
+        } as ProtocolMessage);
+        this.walletTransport.receive({
+          v: 1, t: 'ready', ch: msg.ch,
+          ts: Date.now(), from: '_adapter',
+          body: { state: 'connected', reconnect: false, remote: msg.from },
+        } as ProtocolMessage);
+      });
+    } else if (msg.t === 'req') {
+      // Forward to wallet
+      queueMicrotask(() => this.walletTransport.receive(msg));
+    } else if (msg.t === 'ping') {
+      // Forward to wallet
+      queueMicrotask(() => this.walletTransport.receive(msg));
+    } else if (msg.t === 'close') {
+      queueMicrotask(() => this.walletTransport.receive(msg));
+    }
+  }
+
+  private handleWalletMessage(msg: ProtocolMessage): void {
+    if (msg.t === 'join') {
+      queueMicrotask(() => {
+        // Relay sends ready.waiting to wallet
+        this.walletTransport.receive({
+          v: 1, t: 'ready', ch: msg.ch,
+          ts: Date.now(), from: '_adapter',
+          body: { state: 'waiting', reconnect: false, remote: null },
+        } as ProtocolMessage);
+        // Relay forwards join to dApp
+        this.dappTransport.receive(msg);
+      });
+    } else if (msg.t === 'res') {
+      // Forward to dApp
+      queueMicrotask(() => this.dappTransport.receive(msg));
+    } else if (msg.t === 'evt') {
+      queueMicrotask(() => this.dappTransport.receive(msg));
+    } else if (msg.t === 'pong') {
+      queueMicrotask(() => this.dappTransport.receive(msg));
+    } else if (msg.t === 'close') {
+      queueMicrotask(() => this.dappTransport.receive(msg));
+    }
+  }
+}

package/src/types.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseChainId,
+  formatChainId,
+  evmChainId,
+  evmNumericChainId,
+} from './types.js';
+
+describe('parseChainId', () => {
+  it('parses eip155:1', () => {
+    const { namespace, reference } = parseChainId('eip155:1');
+    expect(namespace).toBe('eip155');
+    expect(reference).toBe('1');
+  });
+
+  it('parses solana:mainnet', () => {
+    const { namespace, reference } = parseChainId('solana:mainnet');
+    expect(namespace).toBe('solana');
+    expect(reference).toBe('mainnet');
+  });
+
+  it('parses cosmos:cosmoshub-4', () => {
+    const { namespace, reference } = parseChainId('cosmos:cosmoshub-4');
+    expect(namespace).toBe('cosmos');
+    expect(reference).toBe('cosmoshub-4');
+  });
+
+  it('throws on missing reference', () => {
+    expect(() => parseChainId('eip155')).toThrow('Invalid CAIP-2');
+  });
+
+  it('throws on empty string', () => {
+    expect(() => parseChainId('')).toThrow('Invalid CAIP-2');
+  });
+
+  it('throws on just a colon', () => {
+    expect(() => parseChainId(':')).toThrow('Invalid CAIP-2');
+  });
+});
+
+describe('formatChainId', () => {
+  it('formats eip155 + 1', () => {
+    expect(formatChainId('eip155', '1')).toBe('eip155:1');
+  });
+
+  it('formats solana + mainnet', () => {
+    expect(formatChainId('solana', 'mainnet')).toBe('solana:mainnet');
+  });
+
+  it('round-trips with parseChainId', () => {
+    const caip2 = 'eip155:137';
+    const { namespace, reference } = parseChainId(caip2);
+    expect(formatChainId(namespace, reference)).toBe(caip2);
+  });
+});
+
+describe('evmChainId', () => {
+  it('converts numeric chain ID to CAIP-2', () => {
+    expect(evmChainId(1)).toBe('eip155:1');
+    expect(evmChainId(137)).toBe('eip155:137');
+    expect(evmChainId(42161)).toBe('eip155:42161');
+  });
+});
+
+describe('evmNumericChainId', () => {
+  it('extracts numeric ID from eip155: prefix', () => {
+    expect(evmNumericChainId('eip155:1')).toBe(1);
+    expect(evmNumericChainId('eip155:137')).toBe(137);
+    expect(evmNumericChainId('eip155:42161')).toBe(42161);
+  });
+
+  it('returns null for non-eip155 chains', () => {
+    expect(evmNumericChainId('solana:mainnet')).toBeNull();
+    expect(evmNumericChainId('cosmos:cosmoshub-4')).toBeNull();
+  });
+
+  it('round-trips with evmChainId', () => {
+    for (const id of [1, 5, 10, 56, 137, 42161]) {
+      expect(evmNumericChainId(evmChainId(id))).toBe(id);
+    }
+  });
+});

package/src/types.ts

@@ -0,0 +1,305 @@
+/**
+ * WalletPair SDK — shared types and interfaces.
+ *
+ * Multi-chain ready: uses CAIP-2 chain IDs throughout (e.g. "eip155:1").
+ */
+
+// ---------------------------------------------------------------------------
+// Transport
+// ---------------------------------------------------------------------------
+
+export type TransportState = 'disconnected' | 'connecting' | 'connected'
+
+export interface Transport {
+  readonly state: TransportState
+  send(msg: ProtocolMessage): void
+  connect(): Promise<void>
+  disconnect(): void
+  onMessage(handler: (msg: ProtocolMessage) => void): void
+  onClose(handler: () => void): void
+  onOpen(handler: () => void): void
+}
+
+// ---------------------------------------------------------------------------
+// Protocol messages (wire format)
+// ---------------------------------------------------------------------------
+
+export interface ProtocolMessageBase {
+  v: 1
+  t: string
+  ch: string
+  ts: number
+  from: string
+  body: Record<string, unknown>
+}
+
+export interface CreateMessage extends ProtocolMessageBase {
+  t: 'create'
+  body: { meta: DAppMeta }
+}
+
+export interface JoinMessage extends ProtocolMessageBase {
+  t: 'join'
+  body: { sealed_join: string | null }
+}
+
+export interface AcceptMessage extends ProtocolMessageBase {
+  t: 'accept'
+  body: { target: string }
+}
+
+export interface ReadyMessage extends ProtocolMessageBase {
+  t: 'ready'
+  body: {
+    state: 'waiting' | 'connected'
+    role: 'dapp' | 'wallet'
+    self: string
+    remote: string | null
+    reconnect: boolean
+  }
+}
+
+export interface RequestMessage extends ProtocolMessageBase {
+  t: 'req'
+  body: { id: string; sealed: string }
+}
+
+export interface ResponseMessage extends ProtocolMessageBase {
+  t: 'res'
+  body: { id: string; sealed: string }
+}
+
+export interface EventMessage extends ProtocolMessageBase {
+  t: 'evt'
+  body: { id: string; sealed: string }
+}
+
+export interface PingMessage extends ProtocolMessageBase {
+  t: 'ping'
+  body: Record<string, never>
+}
+
+export interface PongMessage extends ProtocolMessageBase {
+  t: 'pong'
+  body: Record<string, never>
+}
+
+export interface CloseMessage extends ProtocolMessageBase {
+  t: 'close'
+  body: { reason: CloseReason }
+}
+
+export interface TerminateMessage extends ProtocolMessageBase {
+  t: 'terminate'
+  from: '_adapter'
+  body: { reason: CloseReason }
+}
+
+export type ProtocolMessage =
+  | CreateMessage
+  | JoinMessage
+  | AcceptMessage
+  | ReadyMessage
+  | RequestMessage
+  | ResponseMessage
+  | EventMessage
+  | PingMessage
+  | PongMessage
+  | CloseMessage
+  | TerminateMessage
+
+export type CloseReason =
+  | 'normal'
+  | 'user_rejected'
+  | 'unsupported_capability'
+  | 'channel_not_found'
+  | 'channel_exists'
+  | 'already_connected'
+  | 'invalid_state'
+  | 'invalid_role'
+  | 'timeout'
+  | 'rate_limited'
+  | 'payload_too_large'
+  | 'protocol_error'
+  | 'unsupported_version'
+  | 'decryption_failed'
+
+// ---------------------------------------------------------------------------
+// Capabilities & metadata (multi-chain via CAIP-2)
+// ---------------------------------------------------------------------------
+
+export interface Capabilities {
+  /** Supported RPC methods (e.g. "wallet_getAccounts", "wallet_signMessage"). */
+  methods: string[]
+  /** Supported events (e.g. "accountsChanged", "chainChanged"). */
+  events: string[]
+  /** CAIP-2 chain IDs (e.g. "eip155:1", "solana:mainnet"). */
+  chains: string[]
+  /** Sub-protocol version map (e.g. { evm: 1 }). §8 */
+  version?: Record<string, number> | undefined
+}
+
+export interface DAppMeta {
+  name: string
+  description: string
+  url: string
+  icon: string
+}
+
+export interface WalletMeta {
+  name: string
+  description: string
+  url: string
+  icon: string
+  [key: string]: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Session phases
+// ---------------------------------------------------------------------------
+
+export type DAppPhase =
+  | 'idle'
+  | 'waiting'
+  | 'pending_accept'
+  | 'connected'
+  | 'disconnected'
+  | 'closed'
+
+export type WalletPhase =
+  | 'idle'
+  | 'waiting'
+  | 'waiting_accept'
+  | 'connected'
+  | 'disconnected'
+  | 'closed'
+
+// ---------------------------------------------------------------------------
+// Session events
+// ---------------------------------------------------------------------------
+
+export interface DAppSessionEvents {
+  [key: string]: unknown
+  phase: DAppPhase
+  pairingUri: string
+  sessionFingerprint: string
+  walletJoined: { capabilities?: Capabilities | undefined; meta?: WalletMeta | undefined }
+  response: { id: string; ok: boolean; result: unknown }
+  event: { event: string; data: unknown }
+  error: Error
+}
+
+export interface WalletSessionEvents {
+  [key: string]: unknown
+  phase: WalletPhase
+  sessionFingerprint: string
+  request: { id: string; method: string; params: unknown }
+  error: Error
+}
+
+// ---------------------------------------------------------------------------
+// Pairing URI
+// ---------------------------------------------------------------------------
+
+export interface PairingParams {
+  ch: string
+  pubkey: string
+  /** Relay URL. Undefined when using direct transport (BLE). */
+  relay?: string | undefined
+  name: string
+  /** DApp website URL. */
+  url: string
+  /** DApp icon URL. */
+  icon: string
+  /** Methods the dApp intends to call (§9.1). */
+  methods?: string[] | undefined
+  /** CAIP-2 chains the dApp intends to use (§9.1). */
+  chains?: string[] | undefined
+}
+
+// ---------------------------------------------------------------------------
+// Request/response helpers
+// ---------------------------------------------------------------------------
+
+export interface PendingRequest {
+  id: string
+  method: string
+  resolve: (result: unknown) => void
+  reject: (error: Error) => void
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export interface SessionPersistence {
+  /**
+   * Persist a complete serialized session snapshot. Implementations used for
+   * reconnect MUST make this durable before resolving; the SDK calls this
+   * before sending each encrypted message after advancing `sendSeq`.
+   */
+  save(snapshot: string): void | Promise<void>
+  /** Load the most recent durable snapshot. */
+  load?(): string | null | Promise<string | null>
+  /** Remove the durable snapshot when the channel closes. */
+  clear?(): void | Promise<void>
+}
+
+// ---------------------------------------------------------------------------
+// Session options
+// ---------------------------------------------------------------------------
+
+export interface DAppSessionOptions {
+  transport: Transport
+  /** DApp metadata (name, description, url, icon). Included in pairing URI and create message. */
+  meta: DAppMeta
+  /** Methods the dApp intends to call (included in pairing URI §9.1). */
+  methods?: string[] | undefined
+  /** CAIP-2 chains the dApp intends to use (included in pairing URI §9.1). */
+  chains?: string[] | undefined
+  /** Request timeout in ms (default 120_000). */
+  requestTimeout?: number | undefined
+  /** Session lifetime in ms (default 86_400_000 = 24h). §16 rule 16. */
+  sessionTtl?: number | undefined
+  /** Auto-accept known wallets on rejoin (default true). */
+  autoAccept?: boolean | undefined
+  /** Durable snapshot persistence for reconnect and write-ahead counters. */
+  persistence?: SessionPersistence | undefined
+}
+
+export interface WalletSessionOptions {
+  transport: Transport
+  /** Wallet capabilities to advertise. */
+  capabilities: Capabilities
+  /** Wallet metadata (name, description, url, icon). */
+  meta: WalletMeta
+  /** Session lifetime in ms (default 86_400_000 = 24h). §16 rule 16. */
+  sessionTtl?: number | undefined
+  /** Durable snapshot persistence for reconnect and write-ahead counters. */
+  persistence?: SessionPersistence | undefined
+}
+
+// ---------------------------------------------------------------------------
+// Chain namespace helpers (for future multi-chain)
+// ---------------------------------------------------------------------------
+
+/** Parse CAIP-2 chain ID into namespace and reference. */
+export function parseChainId(caip2: string): { namespace: string; reference: string } {
+  const [namespace, reference] = caip2.split(':')
+  if (!namespace || !reference) throw new Error(`Invalid CAIP-2 chain ID: ${caip2}`)
+  return { namespace, reference }
+}
+
+/** Build CAIP-2 chain ID from namespace and reference. */
+export function formatChainId(namespace: string, reference: string): string {
+  return `${namespace}:${reference}`
+}
+
+/** Convert EVM numeric chain ID to CAIP-2. */
+export function evmChainId(id: number): string {
+  return `eip155:${id}`
+}
+
+/** Extract EVM numeric chain ID from CAIP-2. Returns null if not eip155. */
+export function evmNumericChainId(caip2: string): number | null {
+  const { namespace, reference } = parseChainId(caip2)
+  if (namespace !== 'eip155') return null
+  return Number.parseInt(reference, 10)
+}