@highway1/core 0.1.39 → 0.1.41

package/src/discovery/semantic-search.ts

@@ -0,0 +1,218 @@
+/**
+ * Semantic Search Engine
+ *
+ * Provides intelligent agent discovery through semantic search
+ * with local-first strategy and network fallback
+ */
+
+import type { AgentCard } from './agent-card-types.js';
+import { SearchIndex } from './search-index.js';
+import type { SemanticQuery, SearchResult } from './search-index.js';
+import { CapabilityMatcher } from './capability-matcher.js';
+import type { DHTOperations } from './dht.js';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('semantic-search');
+
+/**
+ * Semantic Search Engine
+ */
+export class SemanticSearchEngine {
+  private index: SearchIndex;
+  private matcher: CapabilityMatcher;
+
+  constructor(private dht?: DHTOperations) {
+    this.index = new SearchIndex();
+    this.matcher = new CapabilityMatcher();
+  }
+
+  /**
+   * Main search interface
+   * Local-first with network fallback
+   */
+  async search(query: SemanticQuery): Promise<AgentCard[]> {
+    logger.info('Searching for agents', { query });
+
+    // 1. Search local index
+    const localResults = this.index.search(query);
+    logger.debug('Local search results', { count: localResults.length });
+
+    // 2. If insufficient results, query network
+    const limit = query.limit || 10;
+    if (localResults.length < limit && this.dht) {
+      logger.debug('Insufficient local results, querying network');
+      const networkResults = await this.searchNetwork(query);
+      return this.mergeResults(localResults, networkResults, limit);
+    }
+
+    return localResults.map(r => r.card);
+  }
+
+  /**
+   * Index an Agent Card for local search
+   */
+  indexAgentCard(card: AgentCard): void {
+    this.index.indexAgentCard(card);
+  }
+
+  /**
+   * Remove an Agent Card from local index
+   */
+  removeAgentCard(did: string): void {
+    this.index.removeAgentCard(did);
+  }
+
+  /**
+   * Get all indexed cards
+   */
+  getAllIndexedCards(): AgentCard[] {
+    return this.index.getAllCards();
+  }
+
+  /**
+   * Clear local index
+   */
+  clearIndex(): void {
+    this.index.clear();
+  }
+
+  /**
+   * Get index size
+   */
+  getIndexSize(): number {
+    return this.index.size();
+  }
+
+  /**
+   * Search network via DHT
+   */
+  private async searchNetwork(query: SemanticQuery): Promise<SearchResult[]> {
+    if (!this.dht) {
+      return [];
+    }
+
+    try {
+      // For now, use capability-based DHT query
+      // In future, implement distributed semantic search overlay
+      const capability = query.capability || this.extractPrimaryCapability(query.text);
+
+      if (!capability) {
+        logger.debug('No capability extracted from query, skipping network search');
+        return [];
+      }
+
+      const cards = await this.dht.queryByCapability(capability);
+      logger.debug('Network search results', { count: cards.length });
+
+      // Score network results
+      return cards.map(card => {
+        const score = this.scoreCard(card, query);
+        return { card, score };
+      });
+    } catch (error) {
+      logger.error('Network search failed', { error });
+      return [];
+    }
+  }
+
+  /**
+   * Merge local and network results, removing duplicates
+   */
+  private mergeResults(
+    local: SearchResult[],
+    network: SearchResult[],
+    limit: number
+  ): AgentCard[] {
+    const seen = new Set<string>();
+    const merged: SearchResult[] = [];
+
+    // Add local results first (they're already scored and sorted)
+    for (const result of local) {
+      if (!seen.has(result.card.did)) {
+        seen.add(result.card.did);
+        merged.push(result);
+      }
+    }
+
+    // Add network results
+    for (const result of network) {
+      if (!seen.has(result.card.did)) {
+        seen.add(result.card.did);
+        merged.push(result);
+
+        // Also index for future searches
+        this.index.indexAgentCard(result.card);
+      }
+    }
+
+    // Sort by score and apply limit
+    merged.sort((a, b) => b.score - a.score);
+    return merged.slice(0, limit).map(r => r.card);
+  }
+
+  /**
+   * Score a card against a query
+   */
+  private scoreCard(card: AgentCard, query: SemanticQuery): number {
+    let totalScore = 0;
+    let count = 0;
+
+    for (const capability of card.capabilities) {
+      const score = this.matcher.match(query, capability);
+      if (score > 0) {
+        totalScore += score;
+        count++;
+      }
+    }
+
+    // Average score across matching capabilities
+    const avgScore = count > 0 ? totalScore / count : 0;
+
+    // Boost by trust score if available
+    if (card.trust) {
+      const trustBoost = card.trust.interactionScore * 0.2;
+      return Math.min(avgScore + trustBoost, 1.0);
+    }
+
+    return avgScore;
+  }
+
+  /**
+   * Extract primary capability from natural language text
+   */
+  private extractPrimaryCapability(text?: string): string | undefined {
+    if (!text) return undefined;
+
+    const keywords = this.matcher.extractKeywords(text);
+
+    // Common capability keywords
+    const capabilityKeywords = [
+      'translate', 'translation',
+      'review', 'code',
+      'analyze', 'analysis',
+      'generate', 'generation',
+      'search', 'query',
+      'compute', 'calculation',
+      'store', 'storage',
+      'message', 'messaging',
+      'auth', 'authentication',
+    ];
+
+    // Find first matching keyword
+    for (const keyword of keywords) {
+      if (capabilityKeywords.includes(keyword)) {
+        return keyword;
+      }
+    }
+
+    // Return first keyword as fallback
+    return keywords[0];
+  }
+}
+
+/**
+ * Create a semantic search engine
+ */
+export function createSemanticSearch(dht?: DHTOperations): SemanticSearchEngine {
+  return new SemanticSearchEngine(dht);
+}

package/src/identity/did.ts

@@ -0,0 +1,48 @@
+import { base58btc } from 'multiformats/bases/base58';
+import { IdentityError } from '../utils/errors.js';
+
+/**
+ * Derive a did:clawiverse DID from a public key
+ * Format: did:clawiverse:<base58btc-encoded-pubkey>
+ */
+export function deriveDID(publicKey: Uint8Array): string {
+  try {
+    const encoded = base58btc.encode(publicKey);
+    return `did:clawiverse:${encoded}`;
+  } catch (error) {
+    throw new IdentityError('Failed to derive DID', error);
+  }
+}
+
+/**
+ * Extract public key from a did:clawiverse DID
+ */
+export function extractPublicKey(did: string): Uint8Array {
+  if (!did.startsWith('did:clawiverse:')) {
+    throw new IdentityError('Invalid DID format: must start with did:clawiverse:');
+  }
+
+  try {
+    const encoded = did.replace('did:clawiverse:', '');
+    return base58btc.decode(encoded);
+  } catch (error) {
+    throw new IdentityError('Failed to extract public key from DID', error);
+  }
+}
+
+/**
+ * Validate a did:clawiverse DID format
+ */
+export function validateDID(did: string): boolean {
+  if (!did.startsWith('did:clawiverse:')) {
+    return false;
+  }
+
+  try {
+    const encoded = did.replace('did:clawiverse:', '');
+    base58btc.decode(encoded);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/identity/document.ts

@@ -0,0 +1,77 @@
+import { deriveDID } from './did.js';
+
+export interface DIDDocument {
+  '@context': string[];
+  id: string;
+  verificationMethod: VerificationMethod[];
+  authentication: string[];
+  assertionMethod: string[];
+  keyAgreement?: string[];
+  service?: ServiceEndpoint[];
+}
+
+export interface VerificationMethod {
+  id: string;
+  type: string;
+  controller: string;
+  publicKeyMultibase: string;
+}
+
+export interface ServiceEndpoint {
+  id: string;
+  type: string;
+  serviceEndpoint: string;
+}
+
+/**
+ * Create a DID Document for a did:clawiverse identity
+ */
+export function createDIDDocument(
+  publicKey: Uint8Array,
+  services?: ServiceEndpoint[]
+): DIDDocument {
+  const did = deriveDID(publicKey);
+  const keyId = `${did}#key-1`;
+  // Use base58btc encoding for multibase format
+  const publicKeyMultibase = `z${Buffer.from(publicKey).toString('hex')}`;
+
+  return {
+    '@context': [
+      'https://www.w3.org/ns/did/v1',
+      'https://w3id.org/security/suites/ed25519-2020/v1',
+    ],
+    id: did,
+    verificationMethod: [
+      {
+        id: keyId,
+        type: 'Ed25519VerificationKey2020',
+        controller: did,
+        publicKeyMultibase,
+      },
+    ],
+    authentication: [keyId],
+    assertionMethod: [keyId],
+    service: services,
+  };
+}
+
+/**
+ * Validate a DID Document structure
+ */
+export function validateDIDDocument(doc: unknown): doc is DIDDocument {
+  if (typeof doc !== 'object' || doc === null) {
+    return false;
+  }
+
+  const d = doc as Partial<DIDDocument>;
+
+  return (
+    Array.isArray(d['@context']) &&
+    typeof d.id === 'string' &&
+    d.id.startsWith('did:clawiverse:') &&
+    Array.isArray(d.verificationMethod) &&
+    d.verificationMethod.length > 0 &&
+    Array.isArray(d.authentication) &&
+    Array.isArray(d.assertionMethod)
+  );
+}

package/src/identity/index.ts

@@ -0,0 +1,4 @@
+export * from './keys.js';
+export * from './did.js';
+export * from './document.js';
+export * from './signer.js';

package/src/identity/keys.ts

@@ -0,0 +1,79 @@
+import * as ed25519 from '@noble/ed25519';
+import { IdentityError } from '../utils/errors.js';
+
+export interface KeyPair {
+  publicKey: Uint8Array;
+  privateKey: Uint8Array;
+}
+
+/**
+ * Generate a new Ed25519 key pair
+ */
+export async function generateKeyPair(): Promise<KeyPair> {
+  try {
+    const privateKey = ed25519.utils.randomPrivateKey();
+    const publicKey = await ed25519.getPublicKeyAsync(privateKey);
+
+    return {
+      publicKey,
+      privateKey,
+    };
+  } catch (error) {
+    throw new IdentityError('Failed to generate key pair', error);
+  }
+}
+
+/**
+ * Sign a message with a private key
+ */
+export async function sign(
+  message: Uint8Array,
+  privateKey: Uint8Array
+): Promise<Uint8Array> {
+  try {
+    return await ed25519.signAsync(message, privateKey);
+  } catch (error) {
+    throw new IdentityError('Failed to sign message', error);
+  }
+}
+
+/**
+ * Verify a signature
+ */
+export async function verify(
+  signature: Uint8Array,
+  message: Uint8Array,
+  publicKey: Uint8Array
+): Promise<boolean> {
+  try {
+    return await ed25519.verifyAsync(signature, message, publicKey);
+  } catch (error) {
+    throw new IdentityError('Failed to verify signature', error);
+  }
+}
+
+/**
+ * Export key pair to JSON format
+ */
+export function exportKeyPair(keyPair: KeyPair): {
+  publicKey: string;
+  privateKey: string;
+} {
+  return {
+    publicKey: Buffer.from(keyPair.publicKey).toString('hex'),
+    privateKey: Buffer.from(keyPair.privateKey).toString('hex'),
+  };
+}
+
+/**
+ * Import key pair from JSON format
+ */
+export function importKeyPair(exported: {
+  publicKey: string;
+  privateKey: string;
+}): KeyPair {
+  return {
+    publicKey: new Uint8Array(Buffer.from(exported.publicKey, 'hex')),
+    privateKey: new Uint8Array(Buffer.from(exported.privateKey, 'hex')),
+  };
+}

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';