@relay-federation/bridge 0.1.2 → 0.3.0

package/lib/config.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile, mkdir, access } from 'node:fs/promises'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { randomBytes } from 'node:crypto'
 import { PrivateKey } from '@bsv/sdk'
 
 const DEFAULT_DIR = join(homedir(), '.relay-bridge')
@@ -23,17 +24,31 @@ export function defaultConfigDir () {
 export async function initConfig (dir = DEFAULT_DIR) {
   const privKey = PrivateKey.fromRandom()
 
+  const address = privKey.toPublicKey().toAddress()
+
   const config = {
     wif: privKey.toWif(),
     pubkeyHex: privKey.toPublicKey().toString(),
+    address,
     endpoint: 'wss://your-bridge.example.com:8333',
-    meshId: 'indelible',
+    meshId: '70016',
     capabilities: ['tx_relay', 'header_sync', 'broadcast', 'address_history'],
     spvEndpoint: 'https://relay.indelible.one',
     apiKey: '',
     port: 8333,
     statusPort: 9333,
-    maxPeers: 20
+    statusSecret: randomBytes(32).toString('hex'),
+    maxPeers: 20,
+    dataDir: join(dir, 'data'),
+    seedPeers: [],
+    // apps: [
+    //   {
+    //     name: 'My App',
+    //     url: 'https://myapp.example.com',
+    //     healthUrl: 'http://127.0.0.1:3000',  // optional — local URL for health checks (avoids DNS/TLS loopback timeout)
+    //     bridgeDomain: 'bridge.myapp.example.com'
+    //   }
+    // ]
   }
 
   await mkdir(dir, { recursive: true })

package/lib/data-validator.js

@@ -188,6 +188,12 @@ export class DataValidator extends EventEmitter {
   }
 
   _validateHeaderAnnounce (pubkeyHex, msg) {
+    // height: -1 means "no headers yet" — valid, skip hash check
+    if (msg.height === -1) {
+      this.scorer.recordGoodData(pubkeyHex)
+      return
+    }
+
     if (typeof msg.height !== 'number' || msg.height < 0) {
       this.scorer.recordBadData(pubkeyHex)
       this.emit('validation:fail', { pubkeyHex, type: 'header_announce', reason: 'invalid_height' })

package/lib/endpoint-probe.js

@@ -0,0 +1,45 @@
+import WebSocket from 'ws'
+
+/**
+ * Probe a WebSocket endpoint for reachability.
+ *
+ * Opens a WebSocket connection, waits for the 'open' event,
+ * then immediately closes. Returns true if reachable, false
+ * if the connection fails or times out.
+ *
+ * @param {string} endpoint — WebSocket URL (ws:// or wss://)
+ * @param {number} [timeoutMs=5000] — Probe timeout in milliseconds
+ * @returns {Promise<boolean>} true if endpoint is reachable
+ */
+export async function probeEndpoint (endpoint, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    let settled = false
+
+    const ws = new WebSocket(endpoint, {
+      handshakeTimeout: timeoutMs
+    })
+
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { ws.close() } catch {}
+      resolve(false)
+    }, timeoutMs)
+
+    ws.on('open', () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { ws.close() } catch {}
+      resolve(true)
+    })
+
+    ws.on('error', () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { ws.close() } catch {}
+      resolve(false)
+    })
+  })
+}

package/lib/gossip.js

@@ -0,0 +1,266 @@
+import { EventEmitter } from 'node:events'
+import { signHash, verifyHash } from '@relay-federation/common/crypto'
+
+/**
+ * GossipManager — peer discovery via WebSocket gossip protocol.
+ *
+ * Replaces HTTP-based registry scanning with pure P2P peer discovery.
+ * Three message types:
+ *
+ *   getpeers   — "tell me who you know"
+ *   peers      — response with list of known peers
+ *   announce   — "I'm alive" (signed, propagated to all peers)
+ *
+ * Announcements are signed with the bridge's private key to prevent
+ * impersonation. Each announcement includes a timestamp — stale
+ * announcements (older than maxAge) are discarded.
+ *
+ * Events:
+ *   'peer:discovered'  — { pubkeyHex, endpoint, meshId }
+ *   'peers:response'   — { peers: Array }
+ */
+export class GossipManager extends EventEmitter {
+  /**
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {object} opts
+   * @param {import('@bsv/sdk').PrivateKey} opts.privKey — Bridge private key for signing
+   * @param {string} opts.pubkeyHex — Our compressed pubkey hex
+   * @param {string} opts.endpoint — Our advertised WSS endpoint
+   * @param {string} [opts.meshId='70016'] — Mesh identifier
+   * @param {number} [opts.announceIntervalMs=60000] — Re-announce interval
+   * @param {number} [opts.maxAge=300000] — Max age for announcements (5 min)
+   * @param {number} [opts.maxPeersResponse=50] — Max peers in a response
+   */
+  constructor (peerManager, opts) {
+    super()
+    this.peerManager = peerManager
+    this._privKey = opts.privKey
+    this._pubkeyHex = opts.pubkeyHex
+    this._endpoint = opts.endpoint
+    this._meshId = opts.meshId || '70016'
+    this._announceIntervalMs = opts.announceIntervalMs || 60000
+    this._maxAge = opts.maxAge || 300000
+    this._maxPeersResponse = opts.maxPeersResponse || 50
+
+    /** @type {Map<string, { pubkeyHex: string, endpoint: string, meshId: string, lastSeen: number }>} */
+    this._directory = new Map()
+
+    /** @type {Set<string>} recently seen announce hashes (dedup) */
+    this._seenAnnounces = new Set()
+
+    this._announceTimer = null
+
+    this.peerManager.on('peer:message', ({ pubkeyHex, message }) => {
+      this._handleMessage(pubkeyHex, message)
+    })
+  }
+
+  /**
+   * Start periodic announcements.
+   */
+  start () {
+    // Announce immediately
+    this._broadcastAnnounce()
+    // Then on interval
+    this._announceTimer = setInterval(() => {
+      this._broadcastAnnounce()
+    }, this._announceIntervalMs)
+    if (this._announceTimer.unref) this._announceTimer.unref()
+  }
+
+  /**
+   * Stop periodic announcements.
+   */
+  stop () {
+    if (this._announceTimer) {
+      clearInterval(this._announceTimer)
+      this._announceTimer = null
+    }
+  }
+
+  /**
+   * Request peer list from a specific peer.
+   * @param {string} pubkeyHex — peer to ask
+   */
+  requestPeers (pubkeyHex) {
+    const conn = this.peerManager.peers.get(pubkeyHex)
+    if (conn) {
+      conn.send({ type: 'getpeers' })
+    }
+  }
+
+  /**
+   * Request peer lists from all connected peers.
+   */
+  requestPeersFromAll () {
+    this.peerManager.broadcast({ type: 'getpeers' })
+  }
+
+  /**
+   * Get the current peer directory.
+   * @returns {Array<{ pubkeyHex: string, endpoint: string, meshId: string, lastSeen: number }>}
+   */
+  getDirectory () {
+    const now = Date.now()
+    const result = []
+    for (const [, entry] of this._directory) {
+      if (now - entry.lastSeen < this._maxAge) {
+        result.push({ ...entry })
+      }
+    }
+    return result
+  }
+
+  /**
+   * Get directory size (excluding stale entries).
+   * @returns {number}
+   */
+  directorySize () {
+    return this.getDirectory().length
+  }
+
+  /**
+   * Manually add a peer to the directory (e.g., seed peers from config).
+   * @param {{ pubkeyHex: string, endpoint: string, meshId?: string }} peer
+   */
+  addSeed (peer) {
+    this._directory.set(peer.pubkeyHex, {
+      pubkeyHex: peer.pubkeyHex,
+      endpoint: peer.endpoint,
+      meshId: peer.meshId || this._meshId,
+      lastSeen: Date.now()
+    })
+  }
+
+  /** @private */
+  _handleMessage (pubkeyHex, message) {
+    switch (message.type) {
+      case 'getpeers':
+        this._onGetPeers(pubkeyHex)
+        break
+      case 'peers':
+        this._onPeers(pubkeyHex, message)
+        break
+      case 'announce':
+        this._onAnnounce(pubkeyHex, message)
+        break
+    }
+  }
+
+  /** @private */
+  _onGetPeers (pubkeyHex) {
+    const peers = this.getDirectory()
+      .filter(p => p.pubkeyHex !== pubkeyHex) // don't send them back to themselves
+      .slice(0, this._maxPeersResponse)
+
+    const conn = this.peerManager.peers.get(pubkeyHex)
+    if (conn) {
+      conn.send({ type: 'peers', peers })
+    }
+  }
+
+  /** @private */
+  _onPeers (pubkeyHex, message) {
+    if (!Array.isArray(message.peers)) return
+
+    for (const peer of message.peers) {
+      if (!peer.pubkeyHex || !peer.endpoint) continue
+      if (peer.pubkeyHex === this._pubkeyHex) continue // skip self
+
+      const isNew = !this._directory.has(peer.pubkeyHex)
+
+      this._directory.set(peer.pubkeyHex, {
+        pubkeyHex: peer.pubkeyHex,
+        endpoint: peer.endpoint,
+        meshId: peer.meshId || 'unknown',
+        lastSeen: Date.now()
+      })
+
+      if (isNew) {
+        this.emit('peer:discovered', {
+          pubkeyHex: peer.pubkeyHex,
+          endpoint: peer.endpoint,
+          meshId: peer.meshId || 'unknown'
+        })
+      }
+    }
+
+    this.emit('peers:response', { peers: message.peers, from: pubkeyHex })
+  }
+
+  /** @private */
+  _onAnnounce (sourcePubkey, message) {
+    if (!message.pubkeyHex || !message.endpoint || !message.timestamp || !message.signature) return
+
+    // Dedup — don't process the same announcement twice
+    const announceId = `${message.pubkeyHex}:${message.timestamp}`
+    if (this._seenAnnounces.has(announceId)) return
+    this._seenAnnounces.add(announceId)
+
+    // Trim dedup set if it gets too large
+    if (this._seenAnnounces.size > 10000) {
+      const arr = [...this._seenAnnounces]
+      this._seenAnnounces = new Set(arr.slice(arr.length - 5000))
+    }
+
+    // Check age
+    const age = Date.now() - message.timestamp
+    if (age > this._maxAge || age < -30000) return // too old or too far in the future
+
+    // Verify signature
+    const payload = `${message.pubkeyHex}:${message.endpoint}:${message.meshId || ''}:${message.timestamp}`
+    const dataHex = Buffer.from(payload, 'utf8').toString('hex')
+
+    try {
+      const valid = verifyHash(dataHex, message.signature, message.pubkeyHex)
+      if (!valid) return
+    } catch {
+      return // invalid signature format
+    }
+
+    // Skip self
+    if (message.pubkeyHex === this._pubkeyHex) return
+
+    const isNew = !this._directory.has(message.pubkeyHex)
+
+    this._directory.set(message.pubkeyHex, {
+      pubkeyHex: message.pubkeyHex,
+      endpoint: message.endpoint,
+      meshId: message.meshId || 'unknown',
+      lastSeen: Date.now()
+    })
+
+    if (isNew) {
+      this.emit('peer:discovered', {
+        pubkeyHex: message.pubkeyHex,
+        endpoint: message.endpoint,
+        meshId: message.meshId || 'unknown'
+      })
+    }
+
+    // Re-broadcast to all peers except source
+    this.peerManager.broadcast(message, sourcePubkey)
+  }
+
+  /** @private */
+  _broadcastAnnounce () {
+    const timestamp = Date.now()
+    const payload = `${this._pubkeyHex}:${this._endpoint}:${this._meshId}:${timestamp}`
+    const dataHex = Buffer.from(payload, 'utf8').toString('hex')
+    const signature = signHash(dataHex, this._privKey)
+
+    const message = {
+      type: 'announce',
+      pubkeyHex: this._pubkeyHex,
+      endpoint: this._endpoint,
+      meshId: this._meshId,
+      timestamp,
+      signature
+    }
+
+    // Add to our own dedup set
+    this._seenAnnounces.add(`${this._pubkeyHex}:${timestamp}`)
+
+    this.peerManager.broadcast(message)
+  }
+}

package/lib/header-relay.js

@@ -171,8 +171,13 @@ export class HeaderRelay extends EventEmitter {
       this.emit('header:sync', {
         pubkeyHex,
         added,
-        bestHeight: this.bestHeight
+        bestHeight: this.bestHeight,
+        headers: msg.headers
       })
+      // If we got a full batch, tell the source our new height so they send more
+      if (msg.headers.length >= this._maxBatch) {
+        this._announceToPeer(pubkeyHex)
+      }
       // Re-announce to all peers except the source
       this.peerManager.broadcast({
         type: 'header_announce',

package/lib/ip-diversity.js

@@ -0,0 +1,88 @@
+/**
+ * IP Diversity — enforces minimum /16 subnet diversity among peers.
+ *
+ * Prevents all connections from clustering in the same datacenter
+ * by tracking the /16 prefix (first two octets) of each peer's IP.
+ *
+ * Rules:
+ *   - Once we have 3+ peers, at least 3 different /16 subnets must be present
+ *   - A new connection is rejected if it would reduce subnet count below the minimum
+ *   - Non-IP hostnames are always allowed (can't determine subnet)
+ */
+
+/**
+ * Extract the /16 subnet prefix from a WebSocket endpoint URL.
+ *
+ * @param {string} endpoint — ws:// or wss:// URL
+ * @returns {string|null} First two octets (e.g. '144.202') or null if not an IP
+ */
+export function extractSubnet (endpoint) {
+  try {
+    const url = new URL(endpoint)
+    const host = url.hostname
+
+    // Check if host is an IPv4 address
+    const parts = host.split('.')
+    if (parts.length !== 4) return null
+    if (!parts.every(p => /^\d{1,3}$/.test(p) && Number(p) <= 255)) return null
+
+    return `${parts[0]}.${parts[1]}`
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Count unique /16 subnets in a set of endpoints.
+ *
+ * @param {string[]} endpoints — array of ws:// or wss:// URLs
+ * @returns {Set<string>} Set of unique /16 subnet prefixes
+ */
+export function getSubnets (endpoints) {
+  const subnets = new Set()
+  for (const ep of endpoints) {
+    const subnet = extractSubnet(ep)
+    if (subnet) subnets.add(subnet)
+  }
+  return subnets
+}
+
+/**
+ * Check if connecting to a candidate endpoint would maintain IP diversity.
+ *
+ * @param {string[]} connectedEndpoints — endpoints of currently connected peers
+ * @param {string} candidateEndpoint — endpoint of peer we want to connect to
+ * @param {number} [minSubnets=3] — minimum number of unique /16 subnets required
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+export function checkIpDiversity (connectedEndpoints, candidateEndpoint, minSubnets = 3) {
+  const candidateSubnet = extractSubnet(candidateEndpoint)
+
+  // Non-IP endpoints are always allowed (hostname-based — can't determine subnet)
+  if (!candidateSubnet) {
+    return { allowed: true }
+  }
+
+  // If we don't have enough peers yet, always allow
+  if (connectedEndpoints.length < minSubnets) {
+    return { allowed: true }
+  }
+
+  // Get current subnet distribution
+  const currentSubnets = getSubnets(connectedEndpoints)
+
+  // If candidate is in a subnet we already have, check if we'd still meet minimum
+  if (currentSubnets.has(candidateSubnet)) {
+    // Already have this subnet — only block if we're at exactly minSubnets
+    // and too many peers are in this subnet (>50% of connections)
+    const sameSubnetCount = connectedEndpoints.filter(ep => extractSubnet(ep) === candidateSubnet).length
+    const totalAfter = connectedEndpoints.length + 1
+    if (sameSubnetCount + 1 > Math.floor(totalAfter / 2) && currentSubnets.size <= minSubnets) {
+      return { allowed: false, reason: `subnet ${candidateSubnet}.x.x already has ${sameSubnetCount}/${connectedEndpoints.length} peers` }
+    }
+    return { allowed: true }
+  }
+
+  // New subnet — always good for diversity
+  return { allowed: true }
+}