@highway1/core 0.1.39 → 0.1.41

package/src/messaging/router.ts

@@ -0,0 +1,368 @@
+import type { Libp2p } from 'libp2p';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { multiaddr } from '@multiformats/multiaddr';
+import type { MessageEnvelope } from './envelope.js';
+import type { DHTOperations } from '../discovery/dht.js';
+import { encodeMessage, decodeMessage } from './codec.js';
+import { validateEnvelope, verifyEnvelope } from './envelope.js';
+import { createLogger } from '../utils/logger.js';
+import { MessagingError } from '../utils/errors.js';
+import { extractPublicKey } from '../identity/did.js';
+import { verify } from '../identity/keys.js';
+
+const logger = createLogger('router');
+
+export type MessageHandler = (
+  envelope: MessageEnvelope
+) => Promise<MessageEnvelope | void>;
+
+export interface PeerHint {
+  peerId: string;
+  multiaddrs: string[];
+}
+
+export interface MessageRouter {
+  registerHandler: (protocol: string, handler: MessageHandler) => void;
+  unregisterHandler: (protocol: string) => void;
+  registerCatchAllHandler: (handler: MessageHandler) => void;
+  sendMessage: (envelope: MessageEnvelope, peerHint?: PeerHint) => Promise<MessageEnvelope | void>;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+}
+
+/**
+ * Create a message router for a libp2p node.
+ * When dht is provided, sendMessage can resolve DIDs to peer addresses via DHT lookup.
+ * When relayPeers is provided, sendMessage will attempt relay fallback if direct dial fails.
+ */
+export function createMessageRouter(
+  libp2p: Libp2p,
+  verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>,
+  dht?: DHTOperations,
+  relayPeers?: string[]
+): MessageRouter {
+  const handlers = new Map<string, MessageHandler>();
+  let catchAllHandler: MessageHandler | undefined;
+  const PROTOCOL_PREFIX = '/clawiverse/msg/1.0.0';
+
+  return {
+    registerHandler: (protocol: string, handler: MessageHandler) => {
+      handlers.set(protocol, handler);
+      logger.info('Registered message handler', { protocol });
+    },
+
+    unregisterHandler: (protocol: string) => {
+      handlers.delete(protocol);
+      logger.info('Unregistered message handler', { protocol });
+    },
+
+    registerCatchAllHandler: (handler: MessageHandler) => {
+      catchAllHandler = handler;
+      logger.info('Registered catch-all message handler');
+    },
+
+    sendMessage: async (envelope: MessageEnvelope, peerHint?: PeerHint) => {
+      try {
+        if (!validateEnvelope(envelope)) {
+          throw new MessagingError('Invalid message envelope');
+        }
+
+        // Resolve peer: try peerHint first, then DHT
+        let targetPeerIdStr: string | undefined;
+        let targetMultiaddrs: string[] = [];
+
+        if (peerHint) {
+          targetPeerIdStr = peerHint.peerId;
+          targetMultiaddrs = peerHint.multiaddrs;
+          logger.info('Using peer hint for direct addressing', { peerId: targetPeerIdStr });
+        } else if (dht) {
+          const resolved = await dht.resolveDID(envelope.to);
+          if (resolved) {
+            targetPeerIdStr = resolved.peerId;
+            targetMultiaddrs = resolved.multiaddrs;
+          }
+        }
+
+        if (!targetPeerIdStr) {
+          throw new MessagingError(
+            `Cannot resolve recipient: ${envelope.to} — provide peerHint or ensure agent is in DHT`
+          );
+        }
+
+        const targetPeerId = peerIdFromString(targetPeerIdStr);
+
+        if (targetMultiaddrs.length > 0) {
+          const mas = targetMultiaddrs.map((a) => multiaddr(a));
+          await libp2p.peerStore.merge(targetPeerId, { multiaddrs: mas });
+        }
+
+        logger.info('Dialing peer for message delivery', {
+          peerId: targetPeerIdStr,
+          multiaddrs: targetMultiaddrs,
+        });
+
+        let stream: any;
+
+        // Separate relay addrs from direct addrs
+        const relayMultiaddrs = targetMultiaddrs.filter((a) => a.includes('/p2p-circuit/'));
+        const directMultiaddrs = targetMultiaddrs.filter((a) => !a.includes('/p2p-circuit/'));
+
+        // Try direct addresses first
+        for (const addr of directMultiaddrs) {
+          try {
+            const conn = await libp2p.dial(multiaddr(addr));
+            stream = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
+            logger.info('Direct dial succeeded', { addr });
+            break;
+          } catch {
+            // try next
+          }
+        }
+
+        let lastError: unknown;
+
+        // Fall back to relay: dial the circuit addr to establish connection, then newStream
+        if (!stream) {
+          const allRelayAddrs = [
+            ...relayMultiaddrs,
+            ...(relayPeers ?? []).map((r) => buildCircuitRelayAddr(r, targetPeerIdStr!)),
+          ];
+          // Deduplicate
+          const uniqueRelayAddrs = [...new Set(allRelayAddrs)];
+          for (const addr of uniqueRelayAddrs) {
+            try {
+              // Step 1: establish the relay connection
+              const conn = await libp2p.dial(multiaddr(addr));
+              logger.info('Relay connection established', { addr });
+              // Step 2: open a protocol stream on the relay (limited) connection
+              stream = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
+              logger.info('Relay stream opened', { addr });
+              break;
+            } catch (relayErr) {
+              logger.warn('Relay dial failed', { addr, error: (relayErr as Error).message });
+              lastError = relayErr;
+            }
+          }
+        }
+
+        // Last resort: query DHT for relay-capable peers
+        if (!stream && dht && 'queryRelayPeers' in dht) {
+          const discoveredRelays = await (dht as any).queryRelayPeers();
+          for (const relayAddr of discoveredRelays) {
+            const circuitAddr = buildCircuitRelayAddr(relayAddr, targetPeerIdStr!);
+            try {
+              const conn = await libp2p.dial(multiaddr(circuitAddr));
+              stream = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
+              logger.info('DHT-discovered relay succeeded', { relayAddr });
+              break;
+            } catch (e) {
+              logger.warn('DHT relay failed', { relayAddr, error: (e as Error).message });
+              lastError = e;
+            }
+          }
+        }
+
+        if (!stream) {
+          throw lastError ?? new MessagingError('All dial attempts failed (including DHT-discovered relays)');
+        }
+
+        const encoded = encodeMessage(envelope);
+        await stream.sink(
+          (async function* () {
+            yield encoded;
+          })()
+        );
+
+        logger.info('Message sent over libp2p stream', {
+          id: envelope.id,
+          from: envelope.from,
+          to: envelope.to,
+          protocol: envelope.protocol,
+        });
+
+        // If this is a request, wait for response
+        if (envelope.type === 'request') {
+          logger.debug('Waiting for response to request', { id: envelope.id });
+
+          try {
+            // Add timeout to prevent infinite blocking
+            const RESPONSE_TIMEOUT = 30000; // 30 seconds
+
+            const responsePromise = (async () => {
+              const responseChunks: Uint8Array[] = [];
+              for await (const chunk of stream.source) {
+                responseChunks.push(chunk.subarray());
+              }
+
+              if (responseChunks.length > 0) {
+                const responseData = new Uint8Array(
+                  responseChunks.reduce((acc, chunk) => acc + chunk.length, 0)
+                );
+                let offset = 0;
+                for (const chunk of responseChunks) {
+                  responseData.set(chunk, offset);
+                  offset += chunk.length;
+                }
+
+                const responseEnvelope = decodeMessage(responseData);
+                logger.info('Received response', {
+                  id: responseEnvelope.id,
+                  replyTo: responseEnvelope.replyTo,
+                });
+
+                return responseEnvelope;
+              } else {
+                logger.warn('No response received for request', { id: envelope.id });
+                return undefined;
+              }
+            })();
+
+            const timeoutPromise = new Promise<undefined>((resolve) => {
+              setTimeout(() => {
+                logger.warn('Response timeout', { id: envelope.id, timeout: RESPONSE_TIMEOUT });
+                resolve(undefined);
+              }, RESPONSE_TIMEOUT);
+            });
+
+            const response = await Promise.race([responsePromise, timeoutPromise]);
+            return response;
+          } catch (error) {
+            logger.warn('Error reading response', { error });
+            return undefined;
+          }
+        }
+
+        return undefined;
+      } catch (error) {
+        if (error instanceof MessagingError) throw error;
+        throw new MessagingError('Failed to send message', error);
+      }
+    },
+
+    start: async () => {
+      await libp2p.handle(PROTOCOL_PREFIX, async ({ stream }) => {
+        try {
+          await handleIncomingStream(stream, handlers, catchAllHandler, verifyFn);
+        } catch (error) {
+          logger.error('Error handling incoming stream', error);
+        }
+      }, { runOnLimitedConnection: true });
+
+      logger.info('Message router started');
+    },
+
+    stop: async () => {
+      await libp2p.unhandle(PROTOCOL_PREFIX);
+      handlers.clear();
+      catchAllHandler = undefined;
+      logger.info('Message router stopped');
+    },
+  };
+}
+
+function buildCircuitRelayAddr(relayAddr: string, targetPeerId: string): string {
+  return `${relayAddr}/p2p-circuit/p2p/${targetPeerId}`;
+}
+
+async function handleIncomingStream(
+  stream: any,
+  handlers: Map<string, MessageHandler>,
+  catchAllHandler: MessageHandler | undefined,
+  verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>
+): Promise<void> {
+  try {
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of stream.source) {
+      chunks.push(chunk.subarray());
+    }
+
+    const data = new Uint8Array(
+      chunks.reduce((acc, chunk) => acc + chunk.length, 0)
+    );
+    let offset = 0;
+    for (const chunk of chunks) {
+      data.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    const envelope = decodeMessage(data);
+
+    if (!validateEnvelope(envelope)) {
+      logger.warn('Received invalid message envelope');
+      return;
+    }
+
+    // Verify signature against sender DID embedded public key.
+    const isValidSignature = await verifyEnvelope(envelope, async (signature, data) => {
+      const senderPublicKey = extractPublicKey(envelope.from);
+      return verify(signature, data, senderPublicKey);
+    });
+    if (!isValidSignature) {
+      logger.warn('Received message with invalid signature', {
+        id: envelope.id,
+        from: envelope.from,
+      });
+      return;
+    }
+
+    // Optional caller-supplied verification hook (e.g. policy checks).
+    try {
+      const { signature, ...envelopeWithoutSig } = envelope;
+      const dataBytes = new TextEncoder().encode(JSON.stringify(envelopeWithoutSig));
+      const signatureBytes = Buffer.from(signature, 'hex');
+      const hookValid = await verifyFn(signatureBytes, dataBytes);
+      if (!hookValid) {
+        logger.warn('Message rejected by custom verifier', {
+          id: envelope.id,
+          from: envelope.from,
+        });
+        return;
+      }
+    } catch (error) {
+      logger.warn('Custom verification hook failed', {
+        id: envelope.id,
+        from: envelope.from,
+        error: (error as Error).message,
+      });
+      return;
+    }
+
+    logger.info('Received message', {
+      id: envelope.id,
+      from: envelope.from,
+      to: envelope.to,
+      protocol: envelope.protocol,
+      payload: envelope.payload,
+    });
+
+    const handler = handlers.get(envelope.protocol);
+    let response: MessageEnvelope | void = undefined;
+
+    if (handler) {
+      response = await handler(envelope);
+    } else if (catchAllHandler) {
+      logger.debug('Using catch-all handler for protocol', { protocol: envelope.protocol });
+      response = await catchAllHandler(envelope);
+    } else {
+      logger.warn('No handler for protocol', { protocol: envelope.protocol });
+    }
+
+    // Send response back if handler returned one
+    if (response) {
+      const encoded = encodeMessage(response);
+      logger.info('Sending response back to sender', {
+        responseId: response.id,
+        replyTo: response.replyTo,
+        size: encoded.length
+      });
+
+      await stream.sink(
+        (async function* () {
+          yield encoded;
+        })()
+      );
+    }
+  } catch (error) {
+    logger.error('Error handling incoming message', error);
+  }
+}

package/src/transport/connection.ts

@@ -0,0 +1,77 @@
+import type { Libp2p } from 'libp2p';
+import { createLogger } from '../utils/logger.js';
+import { TransportError } from '../utils/errors.js';
+
+const logger = createLogger('connection');
+
+export interface ConnectionManager {
+  connect: (peerId: string) => Promise<void>;
+  disconnect: (peerId: string) => Promise<void>;
+  isConnected: (peerId: string) => boolean;
+  getConnectedPeers: () => string[];
+}
+
+/**
+ * Create a connection manager for a libp2p node
+ */
+export function createConnectionManager(
+  libp2p: Libp2p
+): ConnectionManager {
+  return {
+    connect: async (peerIdStr: string) => {
+      try {
+        // Parse peer ID and multiaddr
+        const connections = libp2p.getConnections();
+        const existing = connections.find(
+          (conn) => conn.remotePeer.toString() === peerIdStr
+        );
+
+        if (existing) {
+          logger.debug('Already connected to peer', { peerId: peerIdStr });
+          return;
+        }
+
+        // In a real implementation, we would dial the peer
+        // For now, we rely on libp2p's automatic connection management
+        logger.info('Connecting to peer', { peerId: peerIdStr });
+      } catch (error) {
+        throw new TransportError('Failed to connect to peer', error);
+      }
+    },
+
+    disconnect: async (peerIdStr: string) => {
+      try {
+        const connections = libp2p.getConnections();
+        const matching = connections.filter(
+          (conn) => conn.remotePeer.toString() === peerIdStr
+        );
+
+        for (const conn of matching) {
+          await conn.close();
+        }
+
+        logger.info('Disconnected from peer', { peerId: peerIdStr });
+      } catch (error) {
+        throw new TransportError('Failed to disconnect from peer', error);
+      }
+    },
+
+    isConnected: (peerIdStr: string) => {
+      const connections = libp2p.getConnections();
+      return connections.some(
+        (conn) => conn.remotePeer.toString() === peerIdStr
+      );
+    },
+
+    getConnectedPeers: () => {
+      const connections = libp2p.getConnections();
+      const peers = new Set<string>();
+
+      for (const conn of connections) {
+        peers.add(conn.remotePeer.toString());
+      }
+
+      return Array.from(peers);
+    },
+  };
+}

package/src/transport/index.ts

@@ -0,0 +1,2 @@
+export * from './node.js';
+export * from './connection.js';

package/src/transport/node.ts

@@ -0,0 +1,152 @@
+import { createLibp2p, Libp2p } from 'libp2p';
+import { tcp } from '@libp2p/tcp';
+import { noise } from '@chainsafe/libp2p-noise';
+import { mplex } from '@libp2p/mplex';
+import { kadDHT, passthroughMapper } from '@libp2p/kad-dht';
+import { bootstrap } from '@libp2p/bootstrap';
+import { identify } from '@libp2p/identify';
+import { ping } from '@libp2p/ping';
+import {
+  circuitRelayTransport,
+  circuitRelayServer,
+} from '@libp2p/circuit-relay-v2';
+import { createLogger } from '../utils/logger.js';
+import { TransportError } from '../utils/errors.js';
+import type { KeyPair } from '../identity/keys.js';
+import type { PrivateKey } from '@libp2p/interface';
+
+const logger = createLogger('transport');
+
+export interface TransportConfig {
+  keyPair?: KeyPair;
+  listenAddresses?: string[];
+  bootstrapPeers?: string[];
+  enableDHT?: boolean;
+  /** Run as a relay server so NAT'd agents can receive messages through this node */
+  enableRelay?: boolean;
+  /** Reserve a relay slot on bootstrap nodes so others can reach us (only needed for hw1 join) */
+  reserveRelaySlot?: boolean;
+  /** Enable mDNS local peer discovery (default: false) */
+  enableMDNS?: boolean;
+  /** libp2p PrivateKey for persistent PeerID (from @libp2p/crypto) */
+  privateKey?: PrivateKey;
+}
+
+export interface ClawiverseNode {
+  libp2p: Libp2p;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  getMultiaddrs: () => string[];
+  getPeerId: () => string;
+}
+
+/**
+ * Create a Clawiverse transport node with libp2p
+ */
+export async function createNode(
+  config: TransportConfig
+): Promise<ClawiverseNode> {
+  try {
+    const {
+      listenAddresses = ['/ip4/0.0.0.0/tcp/0'],
+      bootstrapPeers = [],
+      enableDHT = true,
+      enableRelay = false,
+      reserveRelaySlot = false,
+      enableMDNS = false,
+      privateKey,
+    } = config;
+
+    // Reserve relay slots by adding p2p-circuit listen addresses (for hw1 join)
+    const relayListenAddrs = reserveRelaySlot
+      ? bootstrapPeers.map((peer) => `${peer}/p2p-circuit`)
+      : [];
+
+    const libp2pConfig: any = {
+      addresses: {
+        listen: [...listenAddresses, ...relayListenAddrs],
+      },
+      ...(privateKey ? { privateKey } : {}),
+      transports: [
+        tcp(),
+        circuitRelayTransport(),
+      ],
+      connectionEncrypters: [noise()],
+      streamMuxers: [mplex()],
+      connectionManager: {
+        minConnections: bootstrapPeers.length > 0 ? 1 : 0,
+        maxConnections: 50,
+      },
+      services: {
+        identify: identify(),
+        ping: ping(),
+      },
+    };
+
+    if (enableRelay) {
+      libp2pConfig.services.relay = circuitRelayServer({
+        reservations: {
+          maxReservations: 100, // Allow up to 100 concurrent relay reservations
+        },
+      });
+    }
+
+    if (enableDHT) {
+      libp2pConfig.services.dht = kadDHT({
+        clientMode: false,
+        peerInfoMapper: passthroughMapper,
+        validators: {
+          clawiverse: async () => {},
+        },
+        selectors: {
+          clawiverse: () => 0,
+        },
+        // Optimize for small networks: reduce replication factor and query timeout
+        kBucketSize: 20,  // Default K=20, keep for compatibility
+        querySelfInterval: 300000,  // Self-query every 5 min (default 30s)
+        // Allow queries to complete faster in small networks
+        allowQueryWithZeroPeers: true,
+      });
+    }
+
+    const peerDiscovery: any[] = [];
+    if (bootstrapPeers.length > 0) peerDiscovery.push(bootstrap({ list: bootstrapPeers }));
+    if (enableMDNS) {
+      const { mdns } = await import('@libp2p/mdns');
+      peerDiscovery.push(mdns());
+    }
+    if (peerDiscovery.length > 0) libp2pConfig.peerDiscovery = peerDiscovery;
+
+    const libp2p = await createLibp2p(libp2pConfig);
+
+    logger.info('Libp2p node created', {
+      listenAddresses: libp2pConfig.addresses.listen,
+      reserveRelaySlot,
+    });
+
+    return {
+      libp2p,
+      start: async () => {
+        await libp2p.start();
+        logger.info('Node started', {
+          peerId: libp2p.peerId.toString(),
+          addresses: libp2p.getMultiaddrs().map((ma) => ma.toString()),
+          relay: enableRelay,
+          reserveRelaySlot,
+        });
+      },
+      stop: async () => {
+        await libp2p.stop();
+        logger.info('Node stopped');
+      },
+      getMultiaddrs: () => {
+        return libp2p.getMultiaddrs().map((ma) => ma.toString());
+      },
+      getPeerId: () => {
+        return libp2p.peerId.toString();
+      },
+    };
+  } catch (error) {
+    throw new TransportError('Failed to create transport node', error);
+  }
+}