@highway1/core 0.1.10 → 0.1.13

package/src/messaging/router.ts

@@ -0,0 +1,307 @@
+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 } from './envelope.js';
+import { createLogger } from '../utils/logger.js';
+import { MessagingError } from '../utils/errors.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 {
+            stream = await libp2p.dialProtocol(multiaddr(addr), PROTOCOL_PREFIX);
+            logger.info('Direct dial succeeded', { addr });
+            break;
+          } catch {
+            // try next
+          }
+        }
+
+        // Fall back to relay addresses (dial the full circuit multiaddr directly)
+        if (!stream) {
+          const allRelayAddrs = [
+            ...relayMultiaddrs,
+            ...(relayPeers ?? []).map((r) => buildCircuitRelayAddr(r, targetPeerIdStr!)),
+          ];
+          let lastError: unknown;
+          for (const addr of allRelayAddrs) {
+            try {
+              stream = await libp2p.dialProtocol(multiaddr(addr), PROTOCOL_PREFIX);
+              logger.info('Relay dial succeeded', { addr });
+              break;
+            } catch (relayErr) {
+              logger.warn('Relay dial failed', { addr, error: (relayErr as Error).message });
+              lastError = relayErr;
+            }
+          }
+          if (!stream) throw lastError ?? new MessagingError('All dial attempts failed');
+        }
+
+        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);
+        }
+      });
+
+      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;
+    }
+
+    // Skip signature verification for now — both sides use auto-generated libp2p keys
+    // which differ from the Ed25519 DID keys. Full verification comes in Phase 2 when
+    // DID keys and libp2p keys are unified.
+
+    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,127 @@
+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;
+  /** 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,
+      privateKey,
+    } = config;
+
+    // Add relay listen addresses so libp2p auto-reserves slots on bootstrap relay nodes
+    const relayListenAddrs = bootstrapPeers.map((peer) => `${peer}/p2p-circuit`);
+
+    const libp2pConfig: any = {
+      addresses: {
+        listen: [...listenAddresses, ...relayListenAddrs],
+      },
+      ...(privateKey ? { privateKey } : {}),
+      transports: [
+        tcp(),
+        circuitRelayTransport(),
+      ],
+      connectionEncrypters: [noise()],
+      streamMuxers: [mplex()],
+      services: {
+        identify: identify(),
+        ping: ping(),
+      },
+    };
+
+    if (enableRelay) {
+      libp2pConfig.services.relay = circuitRelayServer();
+    }
+
+    if (enableDHT) {
+      libp2pConfig.services.dht = kadDHT({
+        clientMode: false,
+        peerInfoMapper: passthroughMapper,
+        validators: {
+          clawiverse: async () => {},
+        },
+        selectors: {
+          clawiverse: () => 0,
+        },
+      });
+    }
+
+    if (bootstrapPeers.length > 0) {
+      libp2pConfig.peerDiscovery = [
+        bootstrap({
+          list: bootstrapPeers,
+        }),
+      ];
+    }
+
+    const libp2p = await createLibp2p(libp2pConfig);
+
+    logger.info('Libp2p node created');
+
+    return {
+      libp2p,
+      start: async () => {
+        await libp2p.start();
+        logger.info('Node started', {
+          peerId: libp2p.peerId.toString(),
+          addresses: libp2p.getMultiaddrs().map((ma) => ma.toString()),
+          relay: enableRelay,
+        });
+      },
+      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);
+  }
+}

package/src/trust/endorsement.ts

@@ -0,0 +1,167 @@
+/**
+ * Endorsement System
+ *
+ * Allows agents to endorse each other, building a web of trust
+ */
+
+import type { Level } from 'level';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('endorsement');
+
+/**
+ * Endorsement Record
+ */
+export interface Endorsement {
+  from: string;                 // Endorser DID
+  to: string;                   // Endorsed agent DID
+  score: number;                // 0-1
+  reason: string;
+  timestamp: number;
+  signature: string;            // Signed by endorser
+}
+
+/**
+ * Sign function type
+ */
+export type SignFunction = (data: Uint8Array) => Promise<Uint8Array>;
+
+/**
+ * Verify function type
+ */
+export type VerifyFunction = (signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array) => Promise<boolean>;
+
+/**
+ * Endorsement Manager
+ */
+export class EndorsementManager {
+  constructor(
+    private db: Level<string, Endorsement>,
+    private getPublicKey: (did: string) => Promise<Uint8Array>
+  ) {}
+
+  /**
+   * Create an endorsement
+   */
+  async endorse(
+    fromDid: string,
+    toDid: string,
+    score: number,
+    reason: string,
+    signFn: SignFunction
+  ): Promise<Endorsement> {
+    if (score < 0 || score > 1) {
+      throw new Error('Score must be between 0 and 1');
+    }
+
+    const endorsement: Omit<Endorsement, 'signature'> = {
+      from: fromDid,
+      to: toDid,
+      score,
+      reason,
+      timestamp: Date.now(),
+    };
+
+    // Sign the endorsement
+    const data = new TextEncoder().encode(JSON.stringify(endorsement));
+    const signatureBytes = await signFn(data);
+    const signature = Buffer.from(signatureBytes).toString('hex');
+
+    const signedEndorsement: Endorsement = {
+      ...endorsement,
+      signature,
+    };
+
+    logger.info('Created endorsement', { from: fromDid, to: toDid, score });
+    return signedEndorsement;
+  }
+
+  /**
+   * Verify endorsement signature
+   */
+  async verify(endorsement: Endorsement, verifyFn: VerifyFunction): Promise<boolean> {
+    try {
+      const { signature, ...endorsementWithoutSig } = endorsement;
+      const data = new TextEncoder().encode(JSON.stringify(endorsementWithoutSig));
+      const signatureBytes = Buffer.from(signature, 'hex');
+      const publicKey = await this.getPublicKey(endorsement.from);
+
+      return await verifyFn(signatureBytes, data, publicKey);
+    } catch (error) {
+      logger.error('Failed to verify endorsement', { error });
+      return false;
+    }
+  }
+
+  /**
+   * Publish endorsement to local database
+   */
+  async publish(endorsement: Endorsement): Promise<void> {
+    const key = `endorsement:${endorsement.to}:${endorsement.from}`;
+    await this.db.put(key, endorsement);
+    logger.info('Published endorsement', { from: endorsement.from, to: endorsement.to });
+  }
+
+  /**
+   * Get all endorsements for an agent
+   */
+  async getEndorsements(agentDid: string): Promise<Endorsement[]> {
+    const endorsements: Endorsement[] = [];
+    const prefix = `endorsement:${agentDid}:`;
+
+    try {
+      for await (const [_, value] of this.db.iterator({
+        gte: prefix,
+        lte: prefix + '\xff',
+      })) {
+        endorsements.push(value);
+      }
+    } catch (error) {
+      logger.error('Failed to get endorsements', { agentDid, error });
+    }
+
+    return endorsements;
+  }
+
+  /**
+   * Get endorsements given by an agent
+   */
+  async getEndorsementsBy(fromDid: string): Promise<Endorsement[]> {
+    const endorsements: Endorsement[] = [];
+
+    try {
+      for await (const [_, value] of this.db.iterator()) {
+        if (value.from === fromDid) {
+          endorsements.push(value);
+        }
+      }
+    } catch (error) {
+      logger.error('Failed to get endorsements by agent', { fromDid, error });
+    }
+
+    return endorsements;
+  }
+
+  /**
+   * Calculate average endorsement score
+   */
+  async getAverageScore(agentDid: string): Promise<number> {
+    const endorsements = await this.getEndorsements(agentDid);
+
+    if (endorsements.length === 0) {
+      return 0;
+    }
+
+    const totalScore = endorsements.reduce((sum, e) => sum + e.score, 0);
+    return totalScore / endorsements.length;
+  }
+
+  /**
+   * Delete an endorsement
+   */
+  async deleteEndorsement(fromDid: string, toDid: string): Promise<void> {
+    const key = `endorsement:${toDid}:${fromDid}`;
+    await this.db.del(key);
+    logger.info('Deleted endorsement', { from: fromDid, to: toDid });
+  }
+}