@highway1/core 0.1.48 → 0.1.53

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { Libp2p } from 'libp2p';
-import { PrivateKey } from '@libp2p/interface';
 import { Level } from 'level';
 
 interface KeyPair {
@@ -61,32 +59,6 @@ declare function signMessage(payload: Uint8Array, privateKey: Uint8Array, public
  */
 declare function verifyMessage(signedMessage: SignedMessage, expectedPublicKey: Uint8Array): Promise<boolean>;
 
-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;
-}
-interface ClawiverseNode {
-    libp2p: Libp2p;
-    start: () => Promise<void>;
-    stop: () => Promise<void>;
-    getMultiaddrs: () => string[];
-    getPeerId: () => string;
-}
-/**
- * Create a Clawiverse transport node with libp2p
- */
-declare function createNode(config: TransportConfig): Promise<ClawiverseNode>;
-
 /**
  * Trust Score System
  *
@@ -224,6 +196,168 @@ declare function upgradeLegacyCard(legacy: LegacyAgentCard): AgentCard;
  */
 declare function downgradeToLegacyCard(card: AgentCard): LegacyAgentCard;
 
+/**
+ * CVP-0011: Relay wire protocol types (shared between relay server and relay client)
+ */
+
+declare const RELAY_PROTOCOL_VERSION = 1;
+type RelayMessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'DISCOVER' | 'DISCOVERED' | 'PING' | 'PONG' | 'ACK' | 'DELIVERY_REPORT' | 'FETCH_CARD' | 'CARD' | 'GOODBYE' | 'INDEX_SYNC' | 'ROUTE' | 'SYNC_HELLO' | 'SYNC_REQUEST' | 'SYNC_RESPONSE' | 'SYNC_PUSH' | 'SYNC_RECONCILE';
+interface HelloMessage {
+    type: 'HELLO';
+    protocolVersion: number;
+    did: string;
+    card: AgentCard;
+    timestamp: number;
+    signature: Uint8Array;
+    extensions?: string[];
+}
+interface WelcomeMessage {
+    type: 'WELCOME';
+    protocolVersion: number;
+    relayId: string;
+    peers: number;
+    federatedRelays: string[];
+    yourAddr: string;
+}
+interface SendMessage {
+    type: 'SEND';
+    to: string;
+    envelope: Uint8Array;
+}
+interface DeliverMessage {
+    type: 'DELIVER';
+    messageId: string;
+    from: string;
+    envelope: Uint8Array;
+}
+interface DiscoverMessage {
+    type: 'DISCOVER';
+    query: string;
+    minTrust?: number;
+    limit?: number;
+}
+interface DiscoveredAgent {
+    did: string;
+    card: AgentCard;
+    online: boolean;
+    homeRelay?: string;
+}
+interface DiscoveredMessage {
+    type: 'DISCOVERED';
+    agents: DiscoveredAgent[];
+}
+interface AckMessage {
+    type: 'ACK';
+    messageId: string;
+}
+interface DeliveryReportMessage {
+    type: 'DELIVERY_REPORT';
+    messageId: string;
+    status: 'delivered' | 'expired' | 'queue_full' | 'unknown_recipient';
+    timestamp: number;
+}
+interface PingMessage {
+    type: 'PING';
+}
+interface PongMessage {
+    type: 'PONG';
+    peers: number;
+}
+interface FetchCardMessage {
+    type: 'FETCH_CARD';
+    did: string;
+}
+interface CardMessage {
+    type: 'CARD';
+    did: string;
+    card: AgentCard | null;
+}
+interface GoodbyeMessage {
+    type: 'GOODBYE';
+    reconnectAfter?: number;
+}
+interface PresenceProof {
+    did: string;
+    homeRelay: string;
+    expiry: number;
+    signature: Uint8Array;
+}
+interface SyncEvent {
+    seq: number;
+    type: 'JOIN' | 'LEAVE' | 'UPDATE';
+    did: string;
+    homeRelay: string;
+    cardHash?: string;
+    capabilityKeys?: string[];
+    online: boolean;
+    ts: number;
+    presenceProof?: PresenceProof;
+}
+interface IndexSyncMessage {
+    type: 'INDEX_SYNC';
+    events: SyncEvent[];
+}
+interface RouteMessage {
+    type: 'ROUTE';
+    to: string;
+    envelope: Uint8Array;
+    ttl: number;
+}
+interface SyncHelloMessage {
+    type: 'SYNC_HELLO';
+    relayId: string;
+    seq: number;
+}
+interface SyncRequestMessage {
+    type: 'SYNC_REQUEST';
+    fromSeq: number;
+}
+interface SyncResponseMessage {
+    type: 'SYNC_RESPONSE';
+    events: SyncEvent[];
+}
+interface SyncPushMessage {
+    type: 'SYNC_PUSH';
+    event: SyncEvent;
+}
+interface SyncReconcileMessage {
+    type: 'SYNC_RECONCILE';
+    dids: string[];
+}
+type RelayMessage = HelloMessage | WelcomeMessage | SendMessage | DeliverMessage | DiscoverMessage | DiscoveredMessage | AckMessage | DeliveryReportMessage | PingMessage | PongMessage | FetchCardMessage | CardMessage | GoodbyeMessage | IndexSyncMessage | RouteMessage | SyncHelloMessage | SyncRequestMessage | SyncResponseMessage | SyncPushMessage | SyncReconcileMessage;
+
+/**
+ * CVP-0011: WebSocket relay client with reconnection logic
+ */
+
+interface RelayClientConfig {
+    relayUrls: string[];
+    did: string;
+    keyPair: KeyPair;
+    card: AgentCard;
+    reconnect?: {
+        baseMs?: number;
+        jitterMs?: number;
+        maxDelayMs?: number;
+        stableAfterMs?: number;
+    };
+}
+type MessageDeliveryHandler = (msg: DeliverMessage) => Promise<void>;
+type DeliveryReportHandler = (msg: DeliveryReportMessage) => void;
+interface RelayClient {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    sendEnvelope(toDid: string, envelopeBytes: Uint8Array): Promise<void>;
+    discover(query: string, minTrust?: number, limit?: number): Promise<DiscoveredAgent[]>;
+    fetchCard(did: string): Promise<AgentCard | null>;
+    onDeliver(handler: MessageDeliveryHandler): void;
+    onDeliveryReport(handler: DeliveryReportHandler): void;
+    isConnected(): boolean;
+    getConnectedRelays(): string[];
+    getPeerCount(): number;
+}
+declare function createRelayClient(config: RelayClientConfig): RelayClient;
+
 /**
  * Create a new Agent Card (Phase 2 format with structured capabilities)
  */
@@ -441,22 +575,25 @@ declare class SearchIndex {
     private applyFilters;
 }
 
-interface ResolvedDID {
-    peerId: string;
-    multiaddrs: string[];
-}
-interface DHTOperations {
+/**
+ * CVP-0011: Relay-backed discovery operations
+ * Implements the same DHTOperations interface shape but backed by relay queries
+ */
+
+interface RelayIndexOperations {
     publishAgentCard: (card: AgentCard) => Promise<void>;
     queryAgentCard: (did: string) => Promise<AgentCard | null>;
     queryByCapability: (capability: string) => Promise<AgentCard[]>;
     searchSemantic: (query: SemanticQuery) => Promise<AgentCard[]>;
-    resolveDID: (did: string) => Promise<ResolvedDID | null>;
+    resolveDID: (did: string) => Promise<{
+        relayUrl: string;
+    } | null>;
     queryRelayPeers: () => Promise<string[]>;
 }
 /**
- * Create DHT operations for a libp2p node
+ * Create relay-backed discovery operations
  */
-declare function createDHTOperations(libp2p: Libp2p): DHTOperations;
+declare function createRelayIndexOperations(client: RelayClient): RelayIndexOperations;
 
 /**
  * Capability Matcher
@@ -495,6 +632,19 @@ declare class CapabilityMatcher {
     private levenshteinDistance;
 }
 
+interface ResolvedDID {
+    peerId: string;
+    multiaddrs: string[];
+}
+interface DHTOperations {
+    publishAgentCard: (card: AgentCard) => Promise<void>;
+    queryAgentCard: (did: string) => Promise<AgentCard | null>;
+    queryByCapability: (capability: string) => Promise<AgentCard[]>;
+    searchSemantic: (query: SemanticQuery) => Promise<AgentCard[]>;
+    resolveDID: (did: string) => Promise<ResolvedDID | null>;
+    queryRelayPeers: () => Promise<string[]>;
+}
+
 /**
  * Semantic Search Engine
  *
@@ -603,24 +753,18 @@ declare function encodeMessageJSON(envelope: MessageEnvelope): string;
 declare function decodeMessageJSON(json: string): MessageEnvelope;
 
 type MessageHandler = (envelope: MessageEnvelope) => Promise<MessageEnvelope | void>;
-interface PeerHint {
-    peerId: string;
-    multiaddrs: string[];
-}
 interface MessageRouter {
     registerHandler: (protocol: string, handler: MessageHandler) => void;
     unregisterHandler: (protocol: string) => void;
     registerCatchAllHandler: (handler: MessageHandler) => void;
-    sendMessage: (envelope: MessageEnvelope, peerHint?: PeerHint) => Promise<MessageEnvelope | void>;
+    sendMessage: (envelope: MessageEnvelope) => 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.
+ * Create a message router using relay client (CVP-0011)
  */
-declare function createMessageRouter(libp2p: Libp2p, verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>, dht?: DHTOperations, relayPeers?: string[]): MessageRouter;
+declare function createMessageRouter(relayClient: RelayClient, verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>): MessageRouter;
 
 /**
  * Message Queue Types
@@ -1229,4 +1373,4 @@ declare class MessagingError extends ClawiverseError {
     constructor(message: string, details?: unknown);
 }
 
-export { type AgentCard, type AllowlistEntry, type BlocklistEntry, CLAWIVERSE_CONTEXT, type Capability, CapabilityMatcher, type CapabilityParameter, CapabilityTypes, type Challenge, type ChallengeSolution, ClawiverseError, type ClawiverseNode, DEFAULT_RATE_LIMIT_TIERS, type DHTOperations, type DefenseConfig, DefenseMiddleware, type DefenseResult, DiscoveryError, type Endorsement, EndorsementManager, IdentityError, type Interaction, InteractionHistory, type InteractionStats, type KeyPair, type LegacyAgentCard, LogLevel, Logger, type MessageCallback, type MessageDirection, type MessageEnvelope, type MessageFilter, type MessageHandler, type MessagePage, MessageQueue, type MessageQueueConfig, type MessageRouter, type MessageStatus, MessageStorage, MessagingError, type PaginationOptions, ParameterTypes, type PeerHint, type PeerTrustLevel, type QueueStats, type RateLimitResult, type RateLimitState, type RateLimitTiers, type ResolvedDID, SCHEMA_ORG_CONTEXT, SearchIndex, type SearchResult, type SeenEntry, type SemanticQuery, SemanticSearchEngine, type SignFunction, type SignedMessage, type StoredMessage, type SubscriptionFilter, SybilDefense, TokenBucket, type TokenBucketConfig, type TransportConfig, TransportError, TrustMetrics, type TrustScore, TrustSystem, type TrustSystemConfig, type VerifyFunction, clawiverseContext, createAgentCard, createDHTOperations, createDefaultTrustScore, createEnvelope, createLegacyAgentCard, createLogger, createMessageRouter, createNode, createSemanticSearch, createTrustSystem, decodeAgentCard, decodeFromCBOR, decodeFromJSON, decodeMessage, decodeMessageJSON, deriveDID, downgradeToLegacyCard, encodeForDHT, encodeForWeb, encodeMessage, encodeMessageJSON, exportKeyPair, extractPublicKey, generateKeyPair, getAgentCardContext, getEncodedSize, getTierConfig, importKeyPair, isLegacyCard, isValidContext, matchesCapability, sign, signAgentCard, signEnvelope, signMessage, upgradeLegacyCard, validateAgentCard, validateDID, validateEnvelope, verify, verifyAgentCard, verifyEnvelope, verifyMessage };
+export { type AckMessage, type AgentCard, type AllowlistEntry, type BlocklistEntry, CLAWIVERSE_CONTEXT, type Capability, CapabilityMatcher, type CapabilityParameter, CapabilityTypes, type CardMessage, type Challenge, type ChallengeSolution, ClawiverseError, DEFAULT_RATE_LIMIT_TIERS, type DefenseConfig, DefenseMiddleware, type DefenseResult, type DeliverMessage, type DeliveryReportHandler, type DeliveryReportMessage, type DiscoverMessage, type DiscoveredAgent, type DiscoveredMessage, DiscoveryError, type Endorsement, EndorsementManager, type FetchCardMessage, type GoodbyeMessage, type HelloMessage, IdentityError, type IndexSyncMessage, type Interaction, InteractionHistory, type InteractionStats, type KeyPair, type LegacyAgentCard, LogLevel, Logger, type MessageCallback, type MessageDeliveryHandler, type MessageDirection, type MessageEnvelope, type MessageFilter, type MessageHandler, type MessagePage, MessageQueue, type MessageQueueConfig, type MessageRouter, type MessageStatus, MessageStorage, MessagingError, type PaginationOptions, ParameterTypes, type PeerTrustLevel, type PingMessage, type PongMessage, type PresenceProof, type QueueStats, RELAY_PROTOCOL_VERSION, type RateLimitResult, type RateLimitState, type RateLimitTiers, type RelayClient, type RelayClientConfig, type RelayIndexOperations, type RelayMessage, type RelayMessageType, type RouteMessage, SCHEMA_ORG_CONTEXT, SearchIndex, type SearchResult, type SeenEntry, type SemanticQuery, SemanticSearchEngine, type SendMessage, type SignFunction, type SignedMessage, type StoredMessage, type SubscriptionFilter, SybilDefense, type SyncEvent, type SyncHelloMessage, type SyncPushMessage, type SyncReconcileMessage, type SyncRequestMessage, type SyncResponseMessage, TokenBucket, type TokenBucketConfig, TransportError, TrustMetrics, type TrustScore, TrustSystem, type TrustSystemConfig, type VerifyFunction, type WelcomeMessage, clawiverseContext, createAgentCard, createDefaultTrustScore, createEnvelope, createLegacyAgentCard, createLogger, createMessageRouter, createRelayClient, createRelayIndexOperations, createSemanticSearch, createTrustSystem, decodeAgentCard, decodeFromCBOR, decodeFromJSON, decodeMessage, decodeMessageJSON, deriveDID, downgradeToLegacyCard, encodeForDHT, encodeForWeb, encodeMessage, encodeMessageJSON, exportKeyPair, extractPublicKey, generateKeyPair, getAgentCardContext, getEncodedSize, getTierConfig, importKeyPair, isLegacyCard, isValidContext, matchesCapability, sign, signAgentCard, signEnvelope, signMessage, upgradeLegacyCard, validateAgentCard, validateDID, validateEnvelope, verify, verifyAgentCard, verifyEnvelope, verifyMessage };