@johnhenry/browsermesh-transport 0.0.0

package/src/wisp.mjs

@@ -0,0 +1,348 @@
+/**
+ * clawser-wisp-transport.mjs -- WISP Transport Adapter for WSH.
+ *
+ * Adapts a WispClient as a mesh transport that can carry WSH protocol
+ * messages through a WISP relay tunnel. WSH commands are serialized
+ * and sent over a dedicated control stream; additional streams can be
+ * opened for data transfer, RPC, or mesh relay connections.
+ *
+ * Implements the same interface as WebSocketTransport from
+ * clawser-mesh-websocket.js so it can be used interchangeably.
+ *
+ * Standalone uses beyond WSH:
+ *   - Exposing RPC mode over a tunneled port
+ *   - Mesh relay connections through restrictive networks
+ *   - Future v86 guest networking
+ *
+ * Run tests:
+ *   node --import ./web/test/_setup-globals.mjs --test web/test/clawser-wisp-transport.test.mjs
+ */
+
+import { WispClient, WispStream, WISP_DATA } from './wisp-client.mjs'
+import { silentCatch } from './silent-catch.mjs'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default control stream port (WSH protocol) */
+const WSH_CONTROL_PORT = 9083
+
+/** Valid events */
+const EVENTS = Object.freeze(['open', 'message', 'close', 'error', 'reconnect', 'stream'])
+
+// ---------------------------------------------------------------------------
+// WispTransport
+// ---------------------------------------------------------------------------
+
+/**
+ * WISP-backed mesh transport.
+ *
+ * Wraps a WispClient to present the same interface as WebSocketTransport.
+ * A control stream carries WSH messages; additional streams can be opened
+ * for side-channel data (file transfers, RPC tunnels, etc.).
+ *
+ * @example
+ *   const transport = new WispTransport({
+ *     url: 'wss://wisp-relay.example.com/',
+ *     targetHost: 'my-server.local',
+ *     targetPort: 9083,
+ *   })
+ *   await transport.connect()
+ *   transport.send(wshMessage)
+ *   transport.on('message', (data) => handleWshMessage(data))
+ *
+ * @example
+ *   // Open additional streams for data transfer
+ *   const dataStream = transport.openStream('data-host.local', 8080)
+ *   dataStream.write(payload)
+ */
+export class WispTransport {
+  /** @type {string} */
+  #url
+
+  /** @type {string} */
+  #targetHost
+
+  /** @type {number} */
+  #targetPort
+
+  /** @type {WispClient|null} */
+  #client = null
+
+  /** @type {WispStream|null} */
+  #controlStream = null
+
+  /** @type {string} */
+  #state = 'disconnected'
+
+  /** @type {boolean} */
+  #reconnect
+
+  /** @type {number} */
+  #maxReconnectAttempts
+
+  /** @type {number} */
+  #reconnectDelayMs
+
+  /** @type {Function} */
+  #WebSocketCtor
+
+  /** @type {{ open: Function[], message: Function[], close: Function[], error: Function[], reconnect: Function[], stream: Function[] }} */
+  #callbacks = { open: [], message: [], close: [], error: [], reconnect: [], stream: [] }
+
+  /** @type {{ messagesSent: number, messagesReceived: number, bytesIn: number, bytesOut: number, reconnects: number }} */
+  #stats = { messagesSent: 0, messagesReceived: 0, bytesIn: 0, bytesOut: 0, reconnects: 0 }
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.url - WISP relay WebSocket URL
+   * @param {string} [opts.targetHost='localhost'] - Target host for the WSH control stream
+   * @param {number} [opts.targetPort=9083] - Target port for the WSH control stream
+   * @param {boolean} [opts.reconnect=true] - Enable auto-reconnect
+   * @param {number} [opts.maxReconnectAttempts=5] - Max reconnection attempts
+   * @param {number} [opts.reconnectDelayMs=1000] - Base delay between reconnects
+   * @param {Function} [opts._WebSocket] - Injectable WebSocket constructor (for testing)
+   * @param {Function} [opts._WispClient] - Injectable WispClient constructor (for testing)
+   */
+  constructor(opts = {}) {
+    if (!opts.url) throw new Error('url is required')
+    this.#url = opts.url
+    this.#targetHost = opts.targetHost || 'localhost'
+    this.#targetPort = opts.targetPort || WSH_CONTROL_PORT
+    this.#reconnect = opts.reconnect !== undefined ? opts.reconnect : true
+    this.#maxReconnectAttempts = opts.maxReconnectAttempts ?? 5
+    this.#reconnectDelayMs = opts.reconnectDelayMs ?? 1000
+    this.#WebSocketCtor = opts._WebSocket || globalThis.WebSocket
+
+    // Allow injecting a custom WispClient for testing
+    if (opts._WispClient) {
+      /** @type {Function} */
+      this._WispClientCtor = opts._WispClient
+    }
+  }
+
+  // -- Getters ---------------------------------------------------------------
+
+  /** Transport type identifier. */
+  get type() { return 'wisp' }
+
+  /** Current connection state. */
+  get state() { return this.#state }
+
+  /** True when transport is connected. */
+  get connected() { return this.#state === 'connected' }
+
+  /** WISP relay URL. */
+  get url() { return this.#url }
+
+  /** Target host for the control stream. */
+  get targetHost() { return this.#targetHost }
+
+  /** Target port for the control stream. */
+  get targetPort() { return this.#targetPort }
+
+  /** The underlying WispClient instance. */
+  get client() { return this.#client }
+
+  /** Whether auto-reconnect is enabled. */
+  get reconnectEnabled() { return this.#reconnect }
+
+  // -- Public API ------------------------------------------------------------
+
+  /**
+   * Connect to the WISP relay and open the control stream.
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    if (this.#state === 'connected' || this.#state === 'connecting') {
+      throw new Error('Already connected or connecting')
+    }
+    this.#state = 'connecting'
+
+    try {
+      const ClientCtor = this._WispClientCtor || WispClient
+      this.#client = new ClientCtor({
+        url: this.#url,
+        reconnect: false, // we handle reconnection at this layer
+        _WebSocket: this.#WebSocketCtor,
+      })
+
+      this.#client.on('error', (err) => this._fireEvent('error', err))
+      this.#client.on('close', () => this.#handleClientClose())
+
+      await this.#client.connect()
+
+      // open the WSH control stream
+      this.#controlStream = this.#client.open(this.#targetHost, this.#targetPort)
+      this.#controlStream.onData((data) => {
+        this.#stats.messagesReceived++
+        this.#stats.bytesIn += data.byteLength
+        this._fireEvent('message', data)
+      })
+      this.#controlStream.onClose((reason) => {
+        // control stream closed — treat as transport close
+        if (this.#state === 'connected') {
+          this.#handleClientClose()
+        }
+      })
+      this.#controlStream.onError((err) => this._fireEvent('error', err))
+
+      this.#state = 'connected'
+      this._fireEvent('open')
+    } catch (err) {
+      this.#state = 'disconnected'
+      this._fireEvent('error', err)
+      throw err
+    }
+  }
+
+  /**
+   * Send data over the WSH control stream.
+   *
+   * @param {Uint8Array|ArrayBuffer|string} data
+   */
+  send(data) {
+    if (!this.connected) throw new Error('Not connected')
+    if (!this.#controlStream || this.#controlStream.closed) {
+      throw new Error('Control stream is closed')
+    }
+    let bytes
+    if (typeof data === 'string') {
+      bytes = new TextEncoder().encode(data)
+    } else if (data instanceof ArrayBuffer) {
+      bytes = new Uint8Array(data)
+    } else {
+      bytes = data
+    }
+    this.#controlStream.write(bytes)
+    this.#stats.messagesSent++
+    this.#stats.bytesOut += bytes.byteLength
+  }
+
+  /**
+   * Open an additional stream through the WISP relay.
+   * Useful for side-channel data: file transfers, RPC tunnels, etc.
+   *
+   * @example
+   *   const rpcStream = transport.openStream('rpc-server.local', 5000)
+   *
+   * @param {string} host - Target host
+   * @param {number} port - Target port
+   * @returns {WispStream}
+   */
+  openStream(host, port) {
+    if (!this.connected || !this.#client) throw new Error('Not connected')
+    const stream = this.#client.open(host, port)
+    this._fireEvent('stream', stream)
+    return stream
+  }
+
+  /**
+   * Close the transport and underlying WISP client.
+   * @param {number} [code]
+   * @param {string} [reason]
+   * @returns {Promise<void>}
+   */
+  async close(code, reason) {
+    if (this.#state === 'closed' || this.#state === 'disconnected') return
+    this.#state = 'closing'
+
+    if (this.#client) {
+      await this.#client.close()
+    }
+    this.#controlStream = null
+    this.#state = 'closed'
+    this._fireEvent('close')
+  }
+
+  /**
+   * Register an event listener.
+   * @param {string} event - One of: 'open', 'message', 'close', 'error', 'reconnect', 'stream'
+   * @param {Function} cb
+   */
+  on(event, cb) {
+    if (!EVENTS.includes(event)) throw new Error(`Unknown event: ${event}`)
+    this.#callbacks[event].push(cb)
+  }
+
+  /**
+   * Get transport statistics.
+   * @returns {object}
+   */
+  getStats() {
+    return { ...this.#stats }
+  }
+
+  /**
+   * Serialize to a JSON-safe object.
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      type: this.type,
+      state: this.#state,
+      url: this.#url,
+      targetHost: this.#targetHost,
+      targetPort: this.#targetPort,
+      stats: this.getStats(),
+      clientInfo: this.#client ? this.#client.toJSON() : null,
+    }
+  }
+
+  // -- Internal methods ------------------------------------------------------
+
+  /**
+   * Handle underlying client disconnect.
+   */
+  #handleClientClose() {
+    if (this.#state === 'closing' || this.#state === 'closed') return
+
+    this.#controlStream = null
+    this.#state = 'disconnected'
+    this._fireEvent('close')
+
+    if (this.#reconnect) {
+      this.#attemptReconnect()
+    }
+  }
+
+  /** @type {number} */
+  #reconnectAttempts = 0
+
+  /**
+   * Attempt reconnection with exponential backoff.
+   */
+  async #attemptReconnect() {
+    if (this.#reconnectAttempts >= this.#maxReconnectAttempts) return
+
+    this.#reconnectAttempts++
+    this.#stats.reconnects++
+    this._fireEvent('reconnect', { attempt: this.#reconnectAttempts })
+
+    const delay = this.#reconnectDelayMs * Math.pow(2, this.#reconnectAttempts - 1)
+    await new Promise(r => setTimeout(r, delay))
+
+    if (this.#state === 'closing' || this.#state === 'closed') return
+
+    try {
+      await this.connect()
+      this.#reconnectAttempts = 0
+    } catch {
+      if (this.#reconnect && this.#reconnectAttempts < this.#maxReconnectAttempts) {
+        this.#attemptReconnect()
+      }
+    }
+  }
+
+  /**
+   * Fire all callbacks for a given event.
+   * @param {string} event
+   * @param {*} [data]
+   */
+  _fireEvent(event, data) {
+    for (const cb of this.#callbacks[event] || []) {
+      try { cb(data) } catch (e) { silentCatch('clawser-wisp-transport', 'swallow-listener-errors', e) }
+    }
+  }
+}

package/src/wsh-bridge.mjs

@@ -0,0 +1,242 @@
+/**
+// STATUS: implemented + unit-tested (clawser-mesh-wsh-bridge.test.mjs), but
+// never instantiated in app code — `import { MeshWshBridge }` in
+// clawser-pod.js has no matching `new MeshWshBridge(...)` call site anywhere.
+// Not a functional replacement for clawser-kernel-wsh-bridge.js despite the
+// similar name and shared mention in docs/data/networking.yaml's "WSH Bridge
+// Deprecation" entry — this bridges identity key *formats*, not wsh session
+// tenant/capability routing.
+ * clawser-mesh-wsh-bridge.js -- Bridge between WshKeyStore and MeshIdentityManager.
+ *
+ * WshKeyStore uses hex-encoded SHA-256 fingerprints.
+ * MeshIdentityManager uses base64url-encoded SHA-256 pod IDs.
+ * Both hash the same raw Ed25519 public key bytes with SHA-256.
+ *
+ * This bridge converts between the two formats and syncs keys.
+ *
+ * Run tests:
+ *   node --import ./web/test/_setup-globals.mjs --test web/test/clawser-mesh-wsh-bridge.test.mjs
+ */
+
+import {
+  derivePodId,
+  encodeBase64url,
+  decodeBase64url,
+} from '@johnhenry/browsermesh-primitives';
+
+// ---------------------------------------------------------------------------
+// Hex <-> Base64url conversion helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert hex string to Uint8Array.
+ * @param {string} hex
+ * @returns {Uint8Array}
+ */
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert Uint8Array to hex string.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function bytesToHex(bytes) {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+// ---------------------------------------------------------------------------
+// MeshWshBridge
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridges WshKeyStore (hex fingerprints) with MeshIdentityManager (base64url pod IDs).
+ *
+ * Both systems use SHA-256 of the raw Ed25519 public key as their identifier,
+ * but encode it differently: WshKeyStore uses lowercase hex, MeshIdentityManager
+ * uses base64url (no padding).
+ */
+export class MeshWshBridge {
+  /** @type {import('./packages/wsh/src/keystore.mjs').WshKeyStore} */
+  #wshKeyStore;
+
+  /** @type {import('./clawser-mesh-identity.js').MeshIdentityManager} */
+  #meshIdentityManager;
+
+  /**
+   * @param {*} wshKeyStore
+   * @param {*} meshIdentityManager
+   */
+  constructor(wshKeyStore, meshIdentityManager) {
+    if (!wshKeyStore) throw new Error('wshKeyStore is required');
+    if (!meshIdentityManager) throw new Error('meshIdentityManager is required');
+    this.#wshKeyStore = wshKeyStore;
+    this.#meshIdentityManager = meshIdentityManager;
+  }
+
+  /**
+   * Convert a hex fingerprint to a base64url pod ID.
+   * Both are SHA-256 of the same raw public key, just different encodings.
+   * @param {string} hex - Hex-encoded SHA-256 fingerprint
+   * @returns {string} Base64url-encoded pod ID
+   */
+  fingerprint2podId(hex) {
+    const bytes = hexToBytes(hex);
+    return encodeBase64url(bytes);
+  }
+
+  /**
+   * Convert a base64url pod ID to a hex fingerprint.
+   * @param {string} b64url - Base64url-encoded pod ID
+   * @returns {string} Hex-encoded fingerprint
+   */
+  podId2fingerprint(b64url) {
+    const bytes = decodeBase64url(b64url);
+    return bytesToHex(bytes);
+  }
+
+  /**
+   * Import a key from WshKeyStore into MeshIdentityManager.
+   * @param {string} fingerprint - Hex fingerprint from WshKeyStore
+   * @returns {Promise<string>} The pod ID of the imported identity
+   */
+  async importFromWsh(fingerprint) {
+    // Check if already imported
+    const podId = this.fingerprint2podId(fingerprint);
+    if (this.#meshIdentityManager.has(podId)) {
+      return podId;
+    }
+
+    // Find the key in WshKeyStore by listing and matching fingerprint
+    const keys = await this.#wshKeyStore.listKeys();
+    const entry = keys.find(k => k.fingerprint === fingerprint);
+    if (!entry) {
+      throw new Error(`Key with fingerprint ${fingerprint} not found in WshKeyStore`);
+    }
+
+    // Get the full key pair
+    const keyPair = await this.#wshKeyStore.getKeyPair(entry.name);
+
+    // Export private key as JWK for mesh import
+    const jwk = await crypto.subtle.exportKey('jwk', keyPair.privateKey);
+
+    const summary = await this.#meshIdentityManager.import(jwk, `wsh:${entry.name}`, {
+      metadata: { source: 'wsh', wshName: entry.name, wshFingerprint: fingerprint },
+    });
+
+    return summary.podId;
+  }
+
+  /**
+   * Export an identity from MeshIdentityManager to WshKeyStore.
+   * @param {string} podId - Base64url pod ID
+   * @returns {Promise<string>} The hex fingerprint in WshKeyStore
+   */
+  async exportToWsh(podId) {
+    const fp = this.podId2fingerprint(podId);
+
+    // Check if already in WshKeyStore
+    const keys = await this.#wshKeyStore.listKeys();
+    const existing = keys.find(k => k.fingerprint === fp);
+    if (existing) {
+      return fp;
+    }
+
+    // Export from mesh as JWK
+    const jwk = await this.#meshIdentityManager.export(podId);
+
+    // Import into WshKeyStore
+    // WshKeyStore expects raw key import, but we have JWK
+    // We'll import via crypto.subtle first, then use WshKeyStore's generateKey pattern
+    const summary = this.#meshIdentityManager.get(podId);
+    const name = `mesh:${summary?.label || podId.slice(0, 8)}`;
+
+    // Import the private key as extractable
+    const privateKey = await crypto.subtle.importKey(
+      'jwk',
+      jwk,
+      { name: 'Ed25519' },
+      true,
+      ['sign']
+    );
+
+    // Derive public key
+    const pubJwk = { ...jwk };
+    delete pubJwk.d;
+    pubJwk.key_ops = ['verify'];
+    const publicKey = await crypto.subtle.importKey(
+      'jwk',
+      pubJwk,
+      { name: 'Ed25519' },
+      true,
+      ['verify']
+    );
+
+    // Store directly in WshKeyStore's internal DB
+    // We need to use the _put method or store via the keystore's approach
+    // Since WshKeyStore doesn't have a direct import method, we'll use its internal _put
+    if (typeof this.#wshKeyStore._put === 'function') {
+      await this.#wshKeyStore._ensureDb();
+      await this.#wshKeyStore._put({
+        name,
+        publicKey,
+        privateKey,
+        createdAt: Date.now(),
+        fingerprint: fp,
+      });
+    } else {
+      throw new Error('WshKeyStore does not support direct key import');
+    }
+
+    return fp;
+  }
+
+  /**
+   * Sync all keys between both stores.
+   * Imports from WshKeyStore into Mesh that don't exist in Mesh,
+   * and exports from Mesh to WshKeyStore that don't exist in Wsh.
+   * @returns {Promise<{imported: number, exported: number}>}
+   */
+  async syncAll() {
+    let imported = 0;
+    let exported = 0;
+
+    // Import from Wsh -> Mesh
+    const wshKeys = await this.#wshKeyStore.listKeys();
+    for (const key of wshKeys) {
+      const podId = this.fingerprint2podId(key.fingerprint);
+      if (!this.#meshIdentityManager.has(podId)) {
+        try {
+          await this.importFromWsh(key.fingerprint);
+          imported++;
+        } catch {
+          // Skip keys that fail to import (e.g., non-extractable)
+        }
+      }
+    }
+
+    // Export from Mesh -> Wsh
+    const meshIds = this.#meshIdentityManager.list();
+    for (const id of meshIds) {
+      const fp = this.podId2fingerprint(id.podId);
+      const existing = wshKeys.find(k => k.fingerprint === fp);
+      if (!existing) {
+        try {
+          await this.exportToWsh(id.podId);
+          exported++;
+        } catch {
+          // Skip keys that fail to export
+        }
+      }
+    }
+
+    return { imported, exported };
+  }
+}
+
+export { hexToBytes, bytesToHex };