@meshwhisper/sdk 0.1.0

package/src/transport/negotiator/index.ts

@@ -0,0 +1,397 @@
+// ============================================================
+// MeshWhisper SDK — Bearer Negotiator
+// Bearer-agnostic transport layer that selects the best
+// available channel automatically with hybrid fragmentation.
+// ============================================================
+
+import type {
+  Transport,
+  Packet,
+  DeviceCapability,
+  BearerType,
+  BatteryState,
+  RelayWillingness,
+} from '../../types.js';
+import { PacketFlags } from '../../types.js';
+
+// --- Constants ---
+
+const MAX_PAYLOAD_SIZE = 65535;
+const FRAGMENT_HEADER_SIZE = 8; // fragmentId(4) + fragmentIndex(2) + totalFragments(2)
+const MAX_FRAGMENT_PAYLOAD = MAX_PAYLOAD_SIZE - FRAGMENT_HEADER_SIZE;
+
+/** Priority map — lower number = higher priority. */
+const BEARER_PRIORITY: Record<BearerType, number> = {
+  platform_p2p: 0,
+  local_net: 1,
+  internet: 2,
+};
+
+// --- Fragment helpers ---
+
+export interface FragmentHeader {
+  fragmentId: number;
+  fragmentIndex: number;
+  totalFragments: number;
+}
+
+function encodeFragmentHeader(header: FragmentHeader): Uint8Array {
+  const buf = new Uint8Array(FRAGMENT_HEADER_SIZE);
+  const view = new DataView(buf.buffer);
+  view.setUint32(0, header.fragmentId, false);
+  view.setUint16(4, header.fragmentIndex, false);
+  view.setUint16(6, header.totalFragments, false);
+  return buf;
+}
+
+function decodeFragmentHeader(data: Uint8Array): FragmentHeader {
+  if (data.byteLength < FRAGMENT_HEADER_SIZE) {
+    throw new Error('Fragment header too short');
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return {
+    fragmentId: view.getUint32(0, false),
+    fragmentIndex: view.getUint16(4, false),
+    totalFragments: view.getUint16(6, false),
+  };
+}
+
+// --- Receive callback type ---
+
+export type NegotiatorReceiveCallback = (
+  packet: Packet,
+  source: string,
+  bearer: BearerType,
+) => void;
+
+// --- BearerNegotiator ---
+
+export class BearerNegotiator {
+  private readonly transports: Map<BearerType, Transport> = new Map();
+  private receiveCallback: NegotiatorReceiveCallback | null = null;
+  private fragmentIdCounter = 0;
+
+  constructor(transports: Transport[] = []) {
+    for (const t of transports) {
+      this.registerTransport(t);
+    }
+  }
+
+  // ---- Transport registration & probing ----
+
+  /**
+   * Register a transport and wire its onReceive into the aggregated handler.
+   * If a transport with the same bearer type was already registered it is replaced.
+   */
+  registerTransport(transport: Transport): void {
+    this.transports.set(transport.type, transport);
+
+    // Wire up receive aggregation — capture the bearer type at registration time.
+    const bearerType = transport.type;
+    transport.onReceive((packet: Packet, source: string) => {
+      this.receiveCallback?.(packet, source, bearerType);
+    });
+  }
+
+  /**
+   * Probe every registered transport for availability and build a capability
+   * advertisement that can be shared with peers.
+   */
+  async probeAvailability(): Promise<DeviceCapability> {
+    const results = await Promise.allSettled(
+      Array.from(this.transports.entries()).map(async ([type, transport]) => ({
+        type,
+        available: await transport.isAvailable(),
+      })),
+    );
+
+    const availability: Record<BearerType, boolean> = {
+      platform_p2p: false,
+      local_net: false,
+      internet: false,
+    };
+
+    for (const result of results) {
+      if (result.status === 'fulfilled') {
+        availability[result.value.type] = result.value.available;
+      }
+    }
+
+    // Battery state and relay willingness are computed externally — defaults
+    // here represent a reasonable "unknown" baseline.
+    return {
+      bearerPlatformP2P: availability.platform_p2p,
+      bearerLocalNet: availability.local_net,
+      bearerInternet: availability.internet,
+      inboundConnectable: availability.internet || availability.local_net,
+      batteryState: 'high',
+      relayWillingness: 'willing',
+    };
+  }
+
+  /**
+   * Return all registered transports sorted by priority (highest first).
+   * Only includes transports whose isAvailable() resolved to true.
+   */
+  getAvailableTransports(): Transport[] {
+    return Array.from(this.transports.values()).sort(
+      (a, b) => BEARER_PRIORITY[a.type] - BEARER_PRIORITY[b.type],
+    );
+  }
+
+  // ---- Best-path selection ----
+
+  /**
+   * Select the highest-priority transport that is currently available and can
+   * reach `destination`. Falls back through all registered transports.
+   */
+  async selectTransport(destination: string): Promise<Transport | null> {
+    const sorted = this.getAvailableTransports();
+
+    for (const transport of sorted) {
+      try {
+        const available = await transport.isAvailable();
+        if (available) {
+          return transport;
+        }
+      } catch {
+        // Transport probe failed — skip to next.
+      }
+    }
+
+    return null;
+  }
+
+  // ---- Smart sending ----
+
+  /**
+   * Send a packet via the best available transport for the given destination.
+   * Throws if no transport is available.
+   */
+  async send(packet: Packet, destination: string): Promise<void> {
+    const transport = await this.selectTransport(destination);
+    if (!transport) {
+      throw new Error(
+        `No available transport for destination: ${destination}`,
+      );
+    }
+    await transport.send(packet, destination);
+  }
+
+  /**
+   * Broadcast a packet across **all** available transports concurrently.
+   * Errors on individual transports are suppressed so a single failure
+   * does not prevent delivery on other bearers.
+   */
+  async broadcast(packet: Packet): Promise<void> {
+    const transports = this.getAvailableTransports();
+
+    const results = await Promise.allSettled(
+      transports.map(async (t) => {
+        const available = await t.isAvailable();
+        if (available) {
+          // Broadcast destination is empty string — the transport layer
+          // is expected to fan out to all known peers.
+          await t.send(packet, '');
+        }
+      }),
+    );
+
+    // If every transport failed, surface an error.
+    const allFailed = results.every((r) => r.status === 'rejected');
+    if (allFailed && results.length > 0) {
+      throw new Error('Broadcast failed on all available transports');
+    }
+  }
+
+  // ---- Hybrid fragmentation ----
+
+  /**
+   * Fragment a large payload across available bearers. Each fragment is
+   * wrapped in its own Packet with a fragment header prepended to the
+   * encrypted payload field.
+   */
+  async sendLargePayload(
+    destHash: Uint8Array,
+    senderEphId: Uint8Array,
+    payload: Uint8Array,
+    destination: string,
+  ): Promise<void> {
+    const totalFragments = Math.ceil(payload.byteLength / MAX_FRAGMENT_PAYLOAD);
+    if (totalFragments > 0xffff) {
+      throw new Error('Payload too large: exceeds maximum fragment count');
+    }
+
+    const fragmentId = this.nextFragmentId();
+    const transports = this.getAvailableTransports();
+    const availableTransports: Transport[] = [];
+
+    for (const t of transports) {
+      try {
+        if (await t.isAvailable()) {
+          availableTransports.push(t);
+        }
+      } catch {
+        // skip
+      }
+    }
+
+    if (availableTransports.length === 0) {
+      throw new Error('No available transport for large payload delivery');
+    }
+
+    const sendPromises: Promise<void>[] = [];
+
+    for (let i = 0; i < totalFragments; i++) {
+      const start = i * MAX_FRAGMENT_PAYLOAD;
+      const end = Math.min(start + MAX_FRAGMENT_PAYLOAD, payload.byteLength);
+      const chunk = payload.slice(start, end);
+
+      const header = encodeFragmentHeader({
+        fragmentId,
+        fragmentIndex: i,
+        totalFragments,
+      });
+
+      // Prepend fragment header to payload chunk.
+      const fragmentPayload = new Uint8Array(header.byteLength + chunk.byteLength);
+      fragmentPayload.set(header, 0);
+      fragmentPayload.set(chunk, header.byteLength);
+
+      const packet: Packet = {
+        version: 1,
+        flags: PacketFlags.DATA,
+        destHash,
+        senderEphemeralId: senderEphId,
+        ttl: 7,
+        payloadLength: fragmentPayload.byteLength,
+        encryptedPayload: fragmentPayload,
+      };
+
+      // Round-robin fragments across available bearers for hybrid delivery.
+      const transport = availableTransports[i % availableTransports.length]!;
+      sendPromises.push(transport.send(packet, destination));
+    }
+
+    await Promise.all(sendPromises);
+  }
+
+  /**
+   * Reassemble fragments into the original payload.
+   * Returns `null` if any fragment is missing.
+   */
+  reassembleFragments(
+    fragments: Map<number, Uint8Array>,
+    totalFragments: number,
+  ): Uint8Array | null {
+    if (fragments.size !== totalFragments) {
+      return null;
+    }
+
+    // Validate all indices are present.
+    for (let i = 0; i < totalFragments; i++) {
+      if (!fragments.has(i)) {
+        return null;
+      }
+    }
+
+    // Compute total length.
+    let totalLength = 0;
+    for (let i = 0; i < totalFragments; i++) {
+      totalLength += fragments.get(i)!.byteLength;
+    }
+
+    // Concatenate in order.
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (let i = 0; i < totalFragments; i++) {
+      const chunk = fragments.get(i)!;
+      result.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+
+    return result;
+  }
+
+  // ---- Relay willingness computation ----
+
+  /**
+   * Compute how willing this device should be to act as a relay node based
+   * on battery state, current bearer, and reciprocity with the requesting peer.
+   */
+  computeRelayWillingness(
+    batteryState: BatteryState,
+    currentBearer: BearerType,
+    reciprocityScore: number,
+  ): RelayWillingness {
+    // Reciprocity gate: if the peer is a free-rider, refuse regardless.
+    if (reciprocityScore < 0.1) {
+      return 'unavailable';
+    }
+
+    // Battery critically low — never relay.
+    if (batteryState === 'low' || batteryState === 'critical') {
+      return 'unavailable';
+    }
+
+    const onWifi = currentBearer === 'local_net' || currentBearer === 'platform_p2p';
+
+    // Charging + wifi-class bearer → eager.
+    if (batteryState === 'charging' && onWifi) {
+      return 'eager';
+    }
+
+    // High battery + wifi-class bearer → willing.
+    if (batteryState === 'high' && onWifi) {
+      return 'willing';
+    }
+
+    // Medium battery OR cellular bearer → reluctant.
+    if (batteryState === 'medium' || currentBearer === 'internet') {
+      return 'reluctant';
+    }
+
+    // Charging but on cellular.
+    if (batteryState === 'charging') {
+      return 'reluctant';
+    }
+
+    // Fallback: willing (high battery, non-wifi, non-internet — shouldn't
+    // normally occur but safe default).
+    return 'willing';
+  }
+
+  // ---- Event aggregation ----
+
+  /**
+   * Register a single callback that receives packets from **all** registered
+   * transports, tagged with the bearer type they arrived on.
+   *
+   * Only one callback is active at a time — calling this again replaces the
+   * previous handler.
+   */
+  onReceive(callback: NegotiatorReceiveCallback): void {
+    this.receiveCallback = callback;
+  }
+
+  // ---- Internal helpers ----
+
+  private nextFragmentId(): number {
+    // Wrap at 32-bit unsigned max to stay within the 4-byte header field.
+    this.fragmentIdCounter = (this.fragmentIdCounter + 1) & 0xffffffff;
+    return this.fragmentIdCounter;
+  }
+}
+
+// --- Re-exports for consumer convenience ---
+
+export {
+  MAX_PAYLOAD_SIZE,
+  MAX_FRAGMENT_PAYLOAD,
+  FRAGMENT_HEADER_SIZE,
+  BEARER_PRIORITY,
+  encodeFragmentHeader,
+  decodeFragmentHeader,
+};
+
+export type { FragmentHeader as FragmentHeaderType };

package/src/transport/node/index.ts

@@ -0,0 +1,234 @@
+// ============================================================
+// MeshWhisper SDK — Node Transport
+// Connects the SDK to a MeshWhisper Node (relay + directory).
+// All traffic flows through the Node WebSocket endpoint; the
+// Node routes packets by destination hash and buffers blobs
+// for offline recipients.
+// ============================================================
+
+import { WebSocket, type RawData } from 'ws';
+import type { Transport, Packet, PushConfig } from '../../types.js';
+import {
+  serializePacket,
+  deserializePacket,
+  HEADER_SIZE,
+} from '../websocket/serialize.js';
+
+// ---- Constants ----
+
+/** Foundation-hosted relay nodes. Used when node config is "mesh". */
+export const FOUNDATION_RELAY_NODES = [
+  'wss://relay.meshwhisper.io', // TODO: deploy actual Foundation nodes
+];
+
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+
+// ---- NodeTransport ----
+
+/**
+ * Transport that connects to a MeshWhisper Node for relay and
+ * store-and-forward delivery.
+ *
+ * Sends a `hello` control message on connect to register the device's
+ * current destination hashes. The Node then routes incoming packets
+ * to the registered hashes and delivers any queued blobs.
+ *
+ * All outbound packets are forwarded to the Node regardless of the
+ * `destination` argument — the packet's destHash header field is what
+ * the Node uses for routing.
+ */
+export class NodeTransport implements Transport {
+  readonly type = 'internet' as const;
+
+  private ws: WebSocket | null = null;
+  private receiveCallbacks: Array<(packet: Packet, source: string) => void> = [];
+  private running = false;
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * @param nodeUrl - The WebSocket URL of the Node, or "mesh" for Foundation nodes.
+   * @param getDestHashes - Callback returning the device's current dest hashes
+   *   as hex strings. Called on every (re)connect so the Node always has
+   *   up-to-date hashes.
+   * @param pushConfig - Optional push token to register with the Node so it can
+   *   wake the device via APNs/FCM when a message arrives while offline.
+   */
+  constructor(
+    private readonly nodeUrl: string,
+    private readonly getDestHashes: () => string[],
+    private pushConfig?: PushConfig,
+  ) {}
+
+  // ---- Transport interface ----
+
+  async start(): Promise<void> {
+    this.running = true;
+    await this.connect();
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close(1000, 'shutdown');
+      this.ws = null;
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  async send(packet: Packet, _destination: string): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error('NodeTransport: not connected to Node');
+    }
+    const binary = serializePacket(packet);
+    return new Promise<void>((resolve, reject) => {
+      this.ws!.send(binary, { binary: true }, (err) => {
+        if (err) reject(new Error(`NodeTransport send failed: ${err.message}`));
+        else resolve();
+      });
+    });
+  }
+
+  onReceive(callback: (packet: Packet, source: string) => void): void {
+    this.receiveCallbacks.push(callback);
+  }
+
+  // ---- Connection management ----
+
+  private resolveUrl(): string {
+    if (this.nodeUrl === 'mesh') {
+      return FOUNDATION_RELAY_NODES[0];
+    }
+    return this.nodeUrl;
+  }
+
+  private connect(): Promise<void> {
+    const url = this.resolveUrl();
+
+    return new Promise<void>((resolve, reject) => {
+      let resolved = false;
+
+      const ws = new WebSocket(url);
+      ws.binaryType = 'arraybuffer';
+
+      ws.on('open', () => {
+        this.ws = ws;
+        this.reconnectAttempt = 0;
+        resolved = true;
+
+        // Register dest hashes (and optional push token) with the Node
+        ws.send(JSON.stringify(this.buildHello()));
+
+        resolve();
+      });
+
+      ws.on('message', (raw: RawData) => {
+        this.handleMessage(raw);
+      });
+
+      ws.on('close', () => {
+        this.ws = null;
+        if (this.running) this.scheduleReconnect();
+      });
+
+      ws.on('error', (err: Error) => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(`NodeTransport: failed to connect to ${url}: ${err.message}`));
+        }
+      });
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.running) return;
+    const delay = Math.min(
+      RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempt),
+      RECONNECT_MAX_MS,
+    );
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(async () => {
+      if (!this.running) return;
+      try {
+        await this.connect();
+      } catch {
+        this.scheduleReconnect();
+      }
+    }, delay);
+  }
+
+  // ---- Message handling ----
+
+  private handleMessage(raw: RawData): void {
+    // Binary messages are relay packets
+    if (raw instanceof ArrayBuffer && raw.byteLength >= HEADER_SIZE) {
+      try {
+        const packet = deserializePacket(new Uint8Array(raw));
+        const source = this.resolveUrl();
+        for (const cb of this.receiveCallbacks) {
+          try { cb(packet, source); } catch { /* swallow */ }
+        }
+      } catch {
+        // Malformed packet — discard
+      }
+      return;
+    }
+
+    // JSON messages from the Node (informational; no action needed in v1)
+    if (typeof raw === 'string' || raw instanceof Buffer) {
+      try {
+        JSON.parse(raw.toString());
+        // Reserved for future Node→client control messages
+      } catch { /* not JSON */ }
+    }
+  }
+
+  // ---- Dest hash refresh ----
+
+  /**
+   * Re-registers the device's destination hashes with the Node.
+   * Call this when the epoch hour rolls over and hashes rotate.
+   */
+  refreshDestHashes(): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.ws.send(JSON.stringify(this.buildHello()));
+  }
+
+  /**
+   * Update the push token (e.g. after APNs/FCM issues a new token).
+   * Re-registers with the Node immediately if connected.
+   */
+  setPushConfig(pushConfig: PushConfig | undefined): void {
+    this.pushConfig = pushConfig;
+    this.refreshDestHashes();
+  }
+
+  // ---- Private helpers ----
+
+  private buildHello(): object {
+    const msg: Record<string, unknown> = {
+      type: 'hello',
+      destHashes: this.getDestHashes(),
+    };
+    if (this.pushConfig) {
+      msg['pushPlatform'] = this.pushConfig.platform;
+      if (this.pushConfig.platform === 'webpush') {
+        msg['pushSubscription'] = JSON.stringify(this.pushConfig.subscription);
+      } else {
+        msg['pushToken'] = this.pushConfig.token;
+        if (this.pushConfig.platform === 'apns' && this.pushConfig.topic) {
+          msg['pushTopic'] = this.pushConfig.topic;
+        }
+      }
+    }
+    return msg;
+  }
+}

package/src/transport/noop/index.ts

@@ -0,0 +1,22 @@
+// ============================================================
+// MeshWhisper SDK — No-Op Transport
+// Satisfies the Transport interface but does nothing.
+// Used as a placeholder for transports that are unavailable
+// in the current environment (e.g. LocalTransport in a browser).
+// ============================================================
+
+import type { Transport, Packet, BearerType } from '../../types.js';
+
+export class NoOpTransport implements Transport {
+  constructor(readonly type: BearerType) {}
+
+  async start(): Promise<void> {}
+  async stop(): Promise<void> {}
+  async isAvailable(): Promise<boolean> { return false; }
+
+  async send(_packet: Packet, _destination: string): Promise<void> {
+    throw new Error(`NoOpTransport(${this.type}): not available in this environment`);
+  }
+
+  onReceive(_callback: (packet: Packet, source: string) => void): void {}
+}