@highway1/core 0.1.43 → 0.1.45

package/src/identity/signer.ts

@@ -0,0 +1,55 @@
+import { sign, verify } from './keys.js';
+import { deriveDID } from './did.js';
+import { IdentityError } from '../utils/errors.js';
+
+export interface SignedMessage {
+  payload: Uint8Array;
+  signature: Uint8Array;
+  signer: string; // DID
+}
+
+/**
+ * Sign a message and return a signed message object
+ */
+export async function signMessage(
+  payload: Uint8Array,
+  privateKey: Uint8Array,
+  publicKey: Uint8Array
+): Promise<SignedMessage> {
+  try {
+    const signature = await sign(payload, privateKey);
+    const signer = deriveDID(publicKey);
+
+    return {
+      payload,
+      signature,
+      signer,
+    };
+  } catch (error) {
+    throw new IdentityError('Failed to sign message', error);
+  }
+}
+
+/**
+ * Verify a signed message
+ */
+export async function verifyMessage(
+  signedMessage: SignedMessage,
+  expectedPublicKey: Uint8Array
+): Promise<boolean> {
+  try {
+    const expectedDID = deriveDID(expectedPublicKey);
+
+    if (signedMessage.signer !== expectedDID) {
+      return false;
+    }
+
+    return await verify(
+      signedMessage.signature,
+      signedMessage.payload,
+      expectedPublicKey
+    );
+  } catch (error) {
+    throw new IdentityError('Failed to verify message', error);
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Clawiverse Core - Main Export
+ */
+
+// Identity
+export * from './identity/keys.js';
+export * from './identity/did.js';
+export * from './identity/signer.js';
+
+// Transport
+export * from './transport/node.js';
+
+// Discovery
+export * from './discovery/agent-card.js';
+export * from './discovery/agent-card-types.js';
+export * from './discovery/agent-card-schema.js';
+export * from './discovery/agent-card-encoder.js';
+export * from './discovery/dht.js';
+export * from './discovery/search-index.js';
+export * from './discovery/capability-matcher.js';
+export * from './discovery/semantic-search.js';
+
+// Messaging
+export * from './messaging/envelope.js';
+export * from './messaging/codec.js';
+export * from './messaging/router.js';
+
+// Trust (Phase 2)
+export * from './trust/index.js';
+
+// Utils
+export * from './utils/logger.js';
+export * from './utils/errors.js';

package/src/messaging/codec.ts

@@ -0,0 +1,47 @@
+import { encode, decode } from 'cbor-x';
+import type { MessageEnvelope } from './envelope.js';
+import { MessagingError } from '../utils/errors.js';
+
+/**
+ * Encode a message envelope to CBOR
+ */
+export function encodeMessage(envelope: MessageEnvelope): Uint8Array {
+  try {
+    return encode(envelope);
+  } catch (error) {
+    throw new MessagingError('Failed to encode message', error);
+  }
+}
+
+/**
+ * Decode a CBOR message to envelope
+ */
+export function decodeMessage(data: Uint8Array): MessageEnvelope {
+  try {
+    return decode(data) as MessageEnvelope;
+  } catch (error) {
+    throw new MessagingError('Failed to decode message', error);
+  }
+}
+
+/**
+ * Encode message to JSON (for debugging/logging)
+ */
+export function encodeMessageJSON(envelope: MessageEnvelope): string {
+  try {
+    return JSON.stringify(envelope, null, 2);
+  } catch (error) {
+    throw new MessagingError('Failed to encode message to JSON', error);
+  }
+}
+
+/**
+ * Decode JSON message to envelope
+ */
+export function decodeMessageJSON(json: string): MessageEnvelope {
+  try {
+    return JSON.parse(json) as MessageEnvelope;
+  } catch (error) {
+    throw new MessagingError('Failed to decode message from JSON', error);
+  }
+}

package/src/messaging/envelope.ts

@@ -0,0 +1,107 @@
+import { MessagingError } from '../utils/errors.js';
+
+export interface MessageEnvelope {
+  id: string;
+  from: string; // DID
+  to: string; // DID
+  type: 'request' | 'response' | 'notification';
+  protocol: string;
+  payload: unknown;
+  timestamp: number;
+  signature: string;
+  replyTo?: string; // For responses, the ID of the request
+}
+
+/**
+ * Create a message envelope
+ */
+export function createEnvelope(
+  from: string,
+  to: string,
+  type: 'request' | 'response' | 'notification',
+  protocol: string,
+  payload: unknown,
+  replyTo?: string
+): Omit<MessageEnvelope, 'signature'> {
+  return {
+    id: generateMessageId(),
+    from,
+    to,
+    type,
+    protocol,
+    payload,
+    timestamp: Date.now(),
+    replyTo,
+  };
+}
+
+/**
+ * Sign a message envelope
+ */
+export async function signEnvelope(
+  envelope: Omit<MessageEnvelope, 'signature'>,
+  signFn: (data: Uint8Array) => Promise<Uint8Array>
+): Promise<MessageEnvelope> {
+  try {
+    const envelopeJson = JSON.stringify(envelope);
+    const envelopeBytes = new TextEncoder().encode(envelopeJson);
+    const signature = await signFn(envelopeBytes);
+
+    return {
+      ...envelope,
+      signature: Buffer.from(signature).toString('hex'),
+    };
+  } catch (error) {
+    throw new MessagingError('Failed to sign envelope', error);
+  }
+}
+
+/**
+ * Verify a message envelope signature
+ */
+export async function verifyEnvelope(
+  envelope: MessageEnvelope,
+  verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>
+): Promise<boolean> {
+  try {
+    const { signature, ...envelopeWithoutSig } = envelope;
+    const envelopeJson = JSON.stringify(envelopeWithoutSig);
+    const envelopeBytes = new TextEncoder().encode(envelopeJson);
+    const signatureBytes = Buffer.from(signature, 'hex');
+
+    return await verifyFn(signatureBytes, envelopeBytes);
+  } catch (error) {
+    throw new MessagingError('Failed to verify envelope', error);
+  }
+}
+
+/**
+ * Validate message envelope structure
+ */
+export function validateEnvelope(msg: unknown): msg is MessageEnvelope {
+  if (typeof msg !== 'object' || msg === null) {
+    return false;
+  }
+
+  const m = msg as Partial<MessageEnvelope>;
+
+  return (
+    typeof m.id === 'string' &&
+    typeof m.from === 'string' &&
+    m.from.startsWith('did:clawiverse:') &&
+    typeof m.to === 'string' &&
+    m.to.startsWith('did:clawiverse:') &&
+    (m.type === 'request' || m.type === 'response' || m.type === 'notification') &&
+    typeof m.protocol === 'string' &&
+    m.payload !== undefined &&
+    typeof m.timestamp === 'number' &&
+    typeof m.signature === 'string'
+  );
+}
+
+/**
+ * Generate a unique message ID
+ */
+function generateMessageId(): string {
+  return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+}

package/src/messaging/index.ts

@@ -0,0 +1,3 @@
+export * from './envelope.js';
+export * from './codec.js';
+export * from './router.js';

package/src/messaging/router.ts

@@ -0,0 +1,384 @@
+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');
+
+/** Helper to efficiently concatenate Uint8Array chunks */
+function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
+  if (arrays.length === 0) return new Uint8Array(0);
+  if (arrays.length === 1) return arrays[0];
+
+  const totalLength = arrays.reduce((acc, arr) => acc + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+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;
+        const DIAL_TIMEOUT = 3000; // 3 seconds per attempt
+
+        // 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 in parallel
+        if (directMultiaddrs.length > 0) {
+          const directDialPromises = directMultiaddrs.map(async (addr) => {
+            try {
+              const conn = await libp2p.dial(multiaddr(addr), {
+                signal: AbortSignal.timeout(DIAL_TIMEOUT)
+              });
+              const s = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
+              logger.info('Direct dial succeeded', { addr });
+              return s;
+            } catch {
+              return null;
+            }
+          });
+
+          stream = await Promise.race(
+            directDialPromises.map(p => p.then(s => s || Promise.reject()))
+          ).catch(() => undefined);
+        }
+
+        let lastError: unknown;
+
+        // Fall back to relay: try all relay addresses in parallel
+        if (!stream) {
+          const allRelayAddrs = [
+            ...relayMultiaddrs,
+            ...(relayPeers ?? []).map((r) => buildCircuitRelayAddr(r, targetPeerIdStr!)),
+          ];
+          // Deduplicate
+          const uniqueRelayAddrs = [...new Set(allRelayAddrs)];
+
+          if (uniqueRelayAddrs.length > 0) {
+            const relayDialPromises = uniqueRelayAddrs.map(async (addr) => {
+              try {
+                const conn = await libp2p.dial(multiaddr(addr), {
+                  signal: AbortSignal.timeout(DIAL_TIMEOUT)
+                });
+                logger.info('Relay connection established', { addr });
+                const s = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
+                logger.info('Relay stream opened', { addr });
+                return s;
+              } catch (relayErr) {
+                logger.warn('Relay dial failed', { addr, error: (relayErr as Error).message });
+                lastError = relayErr;
+                return null;
+              }
+            });
+
+            stream = await Promise.race(
+              relayDialPromises.map(p => p.then(s => s || Promise.reject()))
+            ).catch(() => undefined);
+          }
+        }
+
+        // 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 = 5000; // 5 seconds
+
+            const responsePromise = (async () => {
+              const responseChunks: Uint8Array[] = [];
+              for await (const chunk of stream.source) {
+                responseChunks.push(chunk.subarray());
+              }
+
+              if (responseChunks.length > 0) {
+                const responseData = concatUint8Arrays(responseChunks);
+                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 = concatUint8Arrays(chunks);
+    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);
+  }
+}