enigma-memory 0.1.17 → 0.1.22

package/packages/mesh/src/router.js

@@ -0,0 +1,279 @@
+// Enigma Encrypted Mesh Protocol ("GhostMesh") — Packet Router & Distance-Vector Engine.
+// Maintains on-demand hop-by-hop routing tables, packet deduplication caches,
+// and store-and-forward queues for multi-hop mesh propagation.
+import { PACKET_TYPES, decodePacket, deriveDestination, encodePacket, getPacketReplayIdentity } from './protocol.js';
+import { verifyPacketSignature } from './crypto.js';
+
+export const ROUTE_TTL_MS = 600_000; // 10 minutes route expiry
+export const DEDUP_CACHE_TTL_MS = 120_000; // 2 minutes deduplication cache
+export const MAX_STORE_FORWARD_ITEMS = 1000;
+export const MAX_DEDUP_CACHE_ITEMS = 10_000;
+export const MAX_KNOWN_PEERS = 1_024;
+
+export class PacketRouter {
+  /**
+   * @param {Object} options
+   * @param {Buffer} options.nodeIdentity - This node's Ed25519 identity keypair
+   * @param {string} [options.nodeId] - Optional readable label
+   */
+  constructor(options = {}) {
+    this.identity = options.nodeIdentity;
+    this.nodeId = options.nodeId || this.identity?.destinationHex?.slice(0, 12) || 'mesh-node';
+    this.authenticatePacket = options.verifyPacketSignature ?? verifyPacketSignature;
+
+    // Destination routing table: destinationHex -> { peerId, hopCount, transportId, updatedAt, expiresAt }
+    this.routes = new Map();
+
+    // Known peer identities: peerId -> { pubkey, destinationHex, transportId, lastSeen }
+    this.peers = new Map();
+
+    // Packet deduplication cache: packetHashHex -> timestamp
+    this.seenPackets = new Map();
+
+    // Store-and-Forward queue for offline / delayed hops: id -> { packet, destinationHex, queuedAt, attempts }
+    this.storeForwardQueue = new Map();
+
+    // Event listeners
+    this.handlers = {
+      packet: new Set(),
+      delivered: new Set(),
+      routed: new Set(),
+      announce: new Set(),
+    };
+  }
+
+  /**
+   * Registers a transport interface or direct peer connection.
+   */
+  registerPeer(peerId, peerInfo) {
+    if (!this.peers.has(peerId) && this.peers.size >= MAX_KNOWN_PEERS) return false;
+    this.peers.set(peerId, {
+      ...this.peers.get(peerId),
+      ...peerInfo,
+      lastSeen: Date.now(),
+    });
+    return true;
+  }
+
+  unregisterPeer(peerId) {
+    this.peers.delete(peerId);
+    for (const [dest, route] of this.routes.entries()) {
+      if (route.peerId === peerId) {
+        this.routes.delete(dest);
+      }
+    }
+  }
+
+  /**
+   * Processes an incoming raw packet buffer from a peer/transport.
+   * @param {Buffer} rawPacket
+   * @param {string} fromPeerId
+   * @param {string} transportId
+   * @returns {Promise<{action: 'DELIVERED'|'ROUTED'|'DROPPED'|'QUEUED'|'ANNOUNCED', packet?: Object, reason?: string}>}
+   */
+  async handleIncomingPacket(rawPacket, fromPeerId, transportId) {
+    // Decode the bounded frame once before deriving its stable replay identity.
+    // Authenticated cache hits may skip Ed25519 work, but unauthenticated frames
+    // are never inserted and therefore cannot poison the replay cache.
+    let decoded;
+    let packetHash;
+    try {
+      decoded = decodePacket(rawPacket);
+      packetHash = getPacketReplayIdentity(decoded.rawBytes);
+    } catch (err) {
+      return { action: 'DROPPED', reason: `decode_error: ${err.message}` };
+    }
+
+    const now = Date.now();
+    this.pruneDedupCache(now);
+    if (this.seenPackets.has(packetHash)) {
+      return { action: 'DROPPED', reason: 'duplicate_packet' };
+    }
+
+    const registeredPeer = this.peers.get(fromPeerId);
+    if (
+      registeredPeer?.publicKey
+      && !Buffer.from(registeredPeer.publicKey).equals(decoded.senderPubkey)
+    ) {
+      return { action: 'DROPPED', reason: 'peer_identity_mismatch' };
+    }
+    if (!this.authenticatePacket(rawPacket)) {
+      return { action: 'DROPPED', reason: 'invalid_signature' };
+    }
+
+    let announceMetadata = null;
+    if (decoded.type === PACKET_TYPES.ANNOUNCE) {
+      try {
+        announceMetadata = JSON.parse(decoded.payload.toString('utf8'));
+        const scope = announceMetadata?.scope;
+        const encryptionKeyHex = announceMetadata?.encryptionPublicKeyHex;
+        if (
+          !announceMetadata
+          || typeof announceMetadata !== 'object'
+          || Array.isArray(announceMetadata)
+          || typeof scope !== 'string'
+          || scope.length === 0
+          || typeof encryptionKeyHex !== 'string'
+          || !/^[a-f0-9]{64}$/i.test(encryptionKeyHex)
+        ) {
+          throw new Error('announce metadata must contain a scope and 32-byte X25519 key');
+        }
+        const expectedDestination = deriveDestination(
+          decoded.senderPubkey,
+          Buffer.from(encryptionKeyHex, 'hex'),
+          scope,
+        );
+        if (!expectedDestination.equals(decoded.destination)) {
+          throw new Error('announce destination does not match its signing key, encryption key, and scope');
+        }
+      } catch (error) {
+        return { action: 'DROPPED', reason: `invalid_announce_binding: ${error.message}` };
+      }
+    }
+
+    if (this.seenPackets.size >= MAX_DEDUP_CACHE_ITEMS) {
+      this.seenPackets.delete(this.seenPackets.keys().next().value);
+    }
+    this.seenPackets.set(packetHash, now);
+
+    // 4. Update route if packet is an ANNOUNCE
+    if (decoded.type === PACKET_TYPES.ANNOUNCE) {
+      this.updateRoute(decoded.destinationHex, fromPeerId, decoded.hopTtl, transportId, now);
+      this.emit('announce', { packet: decoded, metadata: announceMetadata, fromPeerId });
+    }
+
+    // 5. Check if packet is addressed to THIS node or is a broadcast packet
+    const isBroadcast = Buffer.from(decoded.destination).every((b) => b === 0xff) ||
+      decoded.type === PACKET_TYPES.SEALED_SALE_OFFER ||
+      decoded.type === PACKET_TYPES.ZK_PROOF_GOSSIP;
+
+    const isForMe = (this.identity && Buffer.from(decoded.destination).equals(this.identity.destination)) || isBroadcast;
+
+    if (isForMe) {
+      this.emit('delivered', { packet: decoded, fromPeerId });
+      if (!isBroadcast) {
+        return { action: 'DELIVERED', packet: decoded };
+      }
+    }
+    // 6. Multi-hop Forwarding / Routing
+    if (decoded.hopTtl <= 1) {
+      return { action: 'DROPPED', reason: 'ttl_expired' };
+    }
+
+    // Decrement TTL for the next hop
+    const nextHopTtl = decoded.hopTtl - 1;
+    const forwardBuffer = encodePacket({
+      ...decoded,
+      hopTtl: nextHopTtl,
+      signature: decoded.signature,
+    });
+
+    const route = this.getBestRoute(decoded.destinationHex);
+    if (route && route.peerId !== fromPeerId) {
+      this.emit('routed', { packet: decoded, nextHopPeerId: route.peerId, transportId: route.transportId, forwardBuffer });
+      return { action: 'ROUTED', packet: decoded, nextHopPeerId: route.peerId, transportId: route.transportId, forwardBuffer };
+    }
+
+    // 7. Store-and-forward queue if route is currently unreachable
+    this.queueStoreForward(packetHash, forwardBuffer, decoded.destinationHex, now);
+    return { action: 'QUEUED', packet: decoded, reason: 'route_unreachable_stored_for_relay' };
+  }
+
+  /**
+   * Updates the routing table with distance-vector next-hop data.
+   */
+  updateRoute(destinationHex, peerId, hopCount, transportId, now = Date.now()) {
+    const existing = this.routes.get(destinationHex);
+    // Lower hop count or fresher update takes precedence
+    if (!existing || hopCount < existing.hopCount || (hopCount === existing.hopCount && now > existing.updatedAt)) {
+      this.routes.set(destinationHex, {
+        peerId,
+        hopCount,
+        transportId,
+        updatedAt: now,
+        expiresAt: now + ROUTE_TTL_MS,
+      });
+    }
+  }
+
+  getBestRoute(destinationHex) {
+    const route = this.routes.get(destinationHex);
+    if (!route) return null;
+    if (Date.now() > route.expiresAt) {
+      this.routes.delete(destinationHex);
+      return null;
+    }
+    return route;
+  }
+
+  queueStoreForward(id, packetBuffer, destinationHex, now = Date.now()) {
+    if (this.storeForwardQueue.size >= MAX_STORE_FORWARD_ITEMS) {
+      const oldestKey = this.storeForwardQueue.keys().next().value;
+      this.storeForwardQueue.delete(oldestKey);
+    }
+    this.storeForwardQueue.set(id, {
+      packet: packetBuffer,
+      destinationHex,
+      queuedAt: now,
+      attempts: 0,
+    });
+  }
+
+  /**
+   * Flushes store-and-forward packets when a new peer/route becomes available.
+   * @param {Function} forwardCallback - async (packetBuffer, peerId, transportId) => boolean
+   */
+  async flushStoreForward(forwardCallback) {
+    let flushed = 0;
+    for (const [id, item] of Array.from(this.storeForwardQueue.entries())) {
+      const route = this.getBestRoute(item.destinationHex);
+      if (route) {
+        try {
+          const success = await forwardCallback(item.packet, route.peerId, route.transportId);
+          if (success) {
+            this.storeForwardQueue.delete(id);
+            flushed++;
+          }
+        } catch {
+          item.attempts++;
+        }
+      }
+    }
+    return flushed;
+  }
+
+  pruneDedupCache(now = Date.now()) {
+    for (const [hash, time] of this.seenPackets.entries()) {
+      if (now - time > DEDUP_CACHE_TTL_MS) {
+        this.seenPackets.delete(hash);
+      }
+    }
+  }
+
+  on(event, handler) {
+    if (this.handlers[event]) this.handlers[event].add(handler);
+  }
+
+  off(event, handler) {
+    if (this.handlers[event]) this.handlers[event].delete(handler);
+  }
+
+  emit(event, data) {
+    if (this.handlers[event]) {
+      for (const h of this.handlers[event]) {
+        try { h(data); } catch {}
+      }
+    }
+  }
+
+  getRoutingStats() {
+    return {
+      nodeId: this.nodeId,
+      destinationHex: this.identity?.destinationHex || null,
+      activePeers: this.peers.size,
+      knownRoutes: this.routes.size,
+      storeForwardQueueSize: this.storeForwardQueue.size,
+      seenPacketsCacheSize: this.seenPackets.size,
+    };
+  }
+}

package/packages/mesh/src/transport.js

@@ -0,0 +1,306 @@
+// Enigma Encrypted Mesh Protocol ("GhostMesh") — Multi-Transport Layer.
+// Provides AbstractTransport, InMemoryTransport (for multi-node simulation),
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import WebSocket, { WebSocketServer } from 'ws';
+import { generateMeshIdentity, importRawEd25519PrivateKey, importRawEd25519PublicKey } from './crypto.js';
+import { MAX_PACKET_SIZE } from './protocol.js';
+function receivedBinaryFrame(data, isBinary) {
+  if (typeof isBinary === 'boolean') return isBinary;
+  return Buffer.isBuffer(data) || ArrayBuffer.isView(data) || data instanceof ArrayBuffer;
+}
+
+export class AbstractTransport extends EventEmitter {
+  constructor(id) {
+    super();
+    this.id = id || 'transport-' + Math.random().toString(16).slice(2, 8);
+    this.running = false;
+  }
+
+  async start() { this.running = true; }
+  async stop() { this.running = false; }
+  async send(rawPacketBuffer, peerId) { throw new Error('Not implemented'); }
+  async broadcast(rawPacketBuffer) { throw new Error('Not implemented'); }
+}
+
+/**
+ * In-Memory Transport Bus for multi-node testing and simulation.
+ * Allows multiple MeshNode instances to communicate over a shared memory bus with configurable packet drops/delays.
+ */
+export class InMemoryBus {
+  constructor() {
+    this.nodes = new Map(); // nodeId -> InMemoryTransport
+  }
+
+  register(nodeId, transport) {
+    this.nodes.set(nodeId, transport);
+  }
+
+  unregister(nodeId) {
+    this.nodes.delete(nodeId);
+  }
+
+  deliver(fromNodeId, toNodeId, packetBuffer) {
+    const target = this.nodes.get(toNodeId);
+    if (target && target.running) {
+      target.emit('packet', { packetBuffer, fromPeerId: fromNodeId, transportId: target.id });
+    }
+  }
+
+  broadcast(fromNodeId, packetBuffer) {
+    for (const [nodeId, transport] of this.nodes.entries()) {
+      if (nodeId !== fromNodeId && transport.running) {
+        transport.emit('packet', { packetBuffer, fromPeerId: fromNodeId, transportId: transport.id });
+      }
+    }
+  }
+}
+
+export class InMemoryTransport extends AbstractTransport {
+  constructor(nodeId, bus, id) {
+    super(id || `inmem-${nodeId}`);
+    this.nodeId = nodeId;
+    this.bus = bus;
+    this.bus.register(nodeId, this);
+  }
+
+  async send(rawPacketBuffer, peerId) {
+    if (!this.running) return false;
+    this.bus.deliver(this.nodeId, peerId, rawPacketBuffer);
+    return true;
+  }
+
+  async broadcast(rawPacketBuffer) {
+    if (!this.running) return false;
+    this.bus.broadcast(this.nodeId, rawPacketBuffer);
+    return true;
+  }
+
+  async stop() {
+    await super.stop();
+    this.bus.unregister(this.nodeId);
+  }
+}
+
+/**
+ * WebSocket Peer-to-Peer Transport for LAN and WAN Mesh Peering.
+ */
+export class WebSocketTransport extends AbstractTransport {
+  constructor(options = {}) {
+    super(options.id || 'ws-transport');
+    this.port = options.port ?? 0;
+    this.host = options.host || '127.0.0.1';
+    this.server = null;
+    this.actualPort = null;
+    this.sockets = new Map();
+    this.pendingSockets = new Set();
+    this.peerAddresses = new Set(options.peers || []);
+    this.identity = options.identity || generateMeshIdentity(options.scope || 'enigma.transport');
+    this.allowedPeerPublicKeys = new Set(
+      (options.allowedPeerPublicKeys || []).map((key) => (
+        Buffer.isBuffer(key) || key instanceof Uint8Array
+          ? Buffer.from(key).toString('hex')
+          : String(key).toLowerCase()
+      )),
+    );
+    this.allowUnlistedPeers = options.allowUnlistedPeers
+      ?? (this.host === '127.0.0.1' || this.host === 'localhost' || this.host === '::1');
+    this.maxConnections = Number.isSafeInteger(options.maxConnections) && options.maxConnections > 0
+      ? options.maxConnections
+      : 64;
+    this.handshakeTimeoutMs = Number.isSafeInteger(options.handshakeTimeoutMs) && options.handshakeTimeoutMs > 0
+      ? options.handshakeTimeoutMs
+      : 5_000;
+  }
+
+  async start() {
+    if (!this.allowUnlistedPeers && this.allowedPeerPublicKeys.size === 0) {
+      throw new Error('externally reachable WebSocket transport requires an allowedPeerPublicKeys allowlist');
+    }
+    await super.start();
+    if (this.port !== null && this.port !== undefined) {
+      await new Promise((resolve, reject) => {
+        this.server = new WebSocketServer({
+          port: this.port,
+          host: this.host,
+          maxPayload: MAX_PACKET_SIZE,
+        }, () => {
+          this.actualPort = this.server.address().port;
+          resolve();
+        });
+        this.server.on('error', reject);
+        this.server.on('connection', (ws, req) => {
+          if (this.sockets.size + this.pendingSockets.size >= this.maxConnections) {
+            ws.close(1013, 'connection capacity reached');
+            return;
+          }
+          this.setupSocket(ws, `${req.socket.remoteAddress}:${req.socket.remotePort}`);
+        });
+      });
+    }
+    for (const addr of this.peerAddresses) this.connectToPeer(addr).catch(() => {});
+  }
+
+  handshakeBytes(nonce) {
+    return Buffer.concat([Buffer.from('enigma.ghostmesh.ws.handshake.v1\0'), nonce]);
+  }
+
+  setupSocket(ws, address, onAuthenticated = null, onError = null) {
+    const state = {
+      address,
+      authenticated: false,
+      peerId: null,
+      localNonce: crypto.randomBytes(32),
+    };
+    this.pendingSockets.add(ws);
+    const timer = setTimeout(() => ws.close(1008, 'handshake timeout'), this.handshakeTimeoutMs);
+    ws.send(JSON.stringify({
+      kind: 'enigma.ghostmesh.ws.challenge.v1',
+      nonce: state.localNonce.toString('base64'),
+    }));
+
+    ws.on('message', (data, isBinary) => {
+      if (!state.authenticated) {
+        if (receivedBinaryFrame(data, isBinary)) {
+          ws.close(1003, 'handshake requires text frames');
+          return;
+        }
+        try {
+          const message = JSON.parse(Buffer.from(data).toString('utf8'));
+          if (message.kind === 'enigma.ghostmesh.ws.challenge.v1') {
+            const nonce = Buffer.from(message.nonce || '', 'base64');
+            if (nonce.length !== 32) throw new Error('invalid handshake nonce');
+            const signature = crypto.sign(
+              null,
+              this.handshakeBytes(nonce),
+              importRawEd25519PrivateKey(this.identity.secretKey),
+            );
+            ws.send(JSON.stringify({
+              kind: 'enigma.ghostmesh.ws.response.v1',
+              nonce: message.nonce,
+              public_key: this.identity.publicKey.toString('hex'),
+              signature: signature.toString('base64'),
+            }));
+            return;
+          }
+          if (message.kind !== 'enigma.ghostmesh.ws.response.v1') throw new Error('unexpected handshake message');
+          const publicKey = Buffer.from(message.public_key || '', 'hex');
+          const nonce = Buffer.from(message.nonce || '', 'base64');
+          const signature = Buffer.from(message.signature || '', 'base64');
+          if (
+            publicKey.length !== 32
+            || nonce.length !== 32
+            || signature.length !== 64
+            || !crypto.timingSafeEqual(nonce, state.localNonce)
+            || !crypto.verify(null, this.handshakeBytes(nonce), importRawEd25519PublicKey(publicKey), signature)
+          ) {
+            throw new Error('invalid signed handshake response');
+          }
+          const publicKeyHex = publicKey.toString('hex');
+          if (!this.allowUnlistedPeers && !this.allowedPeerPublicKeys.has(publicKeyHex)) {
+            throw new Error('peer identity is not allowlisted');
+          }
+          if (this.sockets.size >= this.maxConnections && !this.sockets.has(publicKeyHex)) {
+            throw new Error('connection capacity reached');
+          }
+          state.authenticated = true;
+          state.peerId = publicKeyHex;
+          clearTimeout(timer);
+          this.pendingSockets.delete(ws);
+          const prior = this.sockets.get(publicKeyHex);
+          if (prior && prior !== ws) prior.close(1000, 'superseded authenticated connection');
+          this.sockets.set(publicKeyHex, ws);
+          this.emit('peer:connect', { peerId: publicKeyHex, publicKey, address });
+          onAuthenticated?.(publicKeyHex);
+        } catch (error) {
+          onError?.(error);
+          ws.close(1008, 'authentication failed');
+        }
+        return;
+      }
+      if (!receivedBinaryFrame(data, isBinary)) {
+        ws.close(1003, 'GhostMesh packets must be binary');
+        return;
+      }
+      const packetBuffer = Buffer.from(data);
+      this.emit('packet', { packetBuffer, fromPeerId: state.peerId, transportId: this.id });
+    });
+
+    ws.on('close', () => {
+      clearTimeout(timer);
+      this.pendingSockets.delete(ws);
+      if (!state.authenticated) onError?.(new Error('WebSocket peer closed before authentication completed'));
+      if (state.peerId && this.sockets.get(state.peerId) === ws) {
+        this.sockets.delete(state.peerId);
+        this.emit('peer:disconnect', { peerId: state.peerId });
+      }
+    });
+    ws.on('error', (error) => {
+      clearTimeout(timer);
+      this.pendingSockets.delete(ws);
+      onError?.(error);
+    });
+  }
+
+  async connectToPeer(address) {
+    return await new Promise((resolve, reject) => {
+      const url = address.startsWith('ws://') || address.startsWith('wss://') ? address : `ws://${address}`;
+      const ws = new WebSocket(url, { maxPayload: MAX_PACKET_SIZE });
+      let settled = false;
+      const finish = (fn, value) => {
+        if (settled) return;
+        settled = true;
+        fn(value);
+      };
+      ws.once('open', () => this.setupSocket(
+        ws,
+        address,
+        (peerId) => finish(resolve, peerId),
+        (error) => finish(reject, error),
+      ));
+      ws.once('error', (error) => finish(reject, error));
+    });
+  }
+
+  async send(rawPacketBuffer, peerId) {
+    const ws = this.sockets.get(peerId);
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    ws.send(rawPacketBuffer, { binary: true });
+    return true;
+  }
+
+  async broadcast(rawPacketBuffer) {
+    let sent = 0;
+    for (const ws of this.sockets.values()) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(rawPacketBuffer, { binary: true });
+        sent++;
+      }
+    }
+    return sent > 0;
+  }
+
+  async stop() {
+    await super.stop();
+    for (const ws of [...this.sockets.values(), ...this.pendingSockets]) {
+      try { ws.close(); } catch {}
+    }
+    this.sockets.clear();
+    this.pendingSockets.clear();
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(resolve));
+      this.server = null;
+    }
+  }
+
+  getStats() {
+    return {
+      id: this.id,
+      running: this.running,
+      listenPort: this.actualPort,
+      connectedPeers: this.sockets.size,
+      pendingHandshakes: this.pendingSockets.size,
+      maxConnections: this.maxConnections,
+    };
+  }
+}