@highway1/core 0.1.46 → 0.1.48

package/dist/index.d.ts

@@ -622,6 +622,217 @@ interface MessageRouter {
  */
 declare function createMessageRouter(libp2p: Libp2p, verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>, dht?: DHTOperations, relayPeers?: string[]): MessageRouter;
 
+/**
+ * Message Queue Types
+ *
+ * Types for message queue, storage, and filtering operations.
+ */
+
+/**
+ * Message direction
+ */
+type MessageDirection = 'inbound' | 'outbound';
+/**
+ * Message status
+ */
+type MessageStatus = 'pending' | 'delivered' | 'failed' | 'archived';
+/**
+ * Stored message with metadata
+ */
+interface StoredMessage {
+    envelope: MessageEnvelope;
+    direction: MessageDirection;
+    status: MessageStatus;
+    receivedAt?: number;
+    sentAt?: number;
+    readAt?: number;
+    trustScore?: number;
+    error?: string;
+}
+/**
+ * Message filter for queries
+ */
+interface MessageFilter {
+    fromDid?: string | string[];
+    toDid?: string | string[];
+    protocol?: string | string[];
+    minTrustScore?: number;
+    maxAge?: number;
+    type?: 'request' | 'response' | 'notification';
+    unreadOnly?: boolean;
+    status?: MessageStatus | MessageStatus[];
+}
+/**
+ * Pagination options
+ */
+interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+    startKey?: string;
+}
+/**
+ * Paginated message results
+ */
+interface MessagePage {
+    messages: StoredMessage[];
+    total: number;
+    hasMore: boolean;
+    nextKey?: string;
+}
+/**
+ * Blocklist entry
+ */
+interface BlocklistEntry {
+    did: string;
+    reason: string;
+    blockedAt: number;
+    blockedBy: string;
+}
+/**
+ * Allowlist entry
+ */
+interface AllowlistEntry {
+    did: string;
+    addedAt: number;
+    note?: string;
+}
+/**
+ * Seen cache entry (for deduplication)
+ */
+interface SeenEntry {
+    messageId: string;
+    seenAt: number;
+    fromDid: string;
+}
+/**
+ * Rate limit state
+ */
+interface RateLimitState {
+    did: string;
+    tokens: number;
+    lastRefill: number;
+    totalRequests: number;
+    firstSeen: number;
+}
+/**
+ * Defense check result
+ */
+interface DefenseResult {
+    allowed: boolean;
+    reason?: 'blocked' | 'duplicate' | 'trust_too_low' | 'rate_limited' | 'invalid';
+    trustScore?: number;
+    remainingTokens?: number;
+    resetTime?: number;
+}
+/**
+ * Rate limit result
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetTime: number;
+    limit: number;
+}
+/**
+ * Queue statistics
+ */
+interface QueueStats {
+    inboxTotal: number;
+    inboxUnread: number;
+    outboxPending: number;
+    outboxFailed: number;
+    blockedAgents: number;
+    allowedAgents: number;
+    rateLimitedAgents: number;
+}
+/**
+ * Subscription callback
+ */
+type MessageCallback = (message: StoredMessage) => void | Promise<void>;
+/**
+ * Subscription filter
+ */
+interface SubscriptionFilter extends MessageFilter {
+    webhookUrl?: string;
+}
+
+/**
+ * Message Storage - LevelDB operations for message queue
+ *
+ * Key schema:
+ *   msg:inbound:{timestamp}:{id}   → StoredMessage
+ *   msg:outbound:{timestamp}:{id}  → StoredMessage
+ *   block:{did}                    → BlocklistEntry
+ *   allow:{did}                    → AllowlistEntry
+ *   seen:{messageId}               → SeenEntry
+ *   rate:{did}                     → RateLimitState
+ *   idx:from:{did}:{timestamp}:{id} → '1'
+ */
+
+declare class MessageStorage {
+    private db;
+    private ready;
+    constructor(dbPath: string);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    putMessage(msg: StoredMessage): Promise<void>;
+    getMessage(id: string): Promise<StoredMessage | null>;
+    updateMessage(id: string, updates: Partial<StoredMessage>): Promise<void>;
+    deleteMessage(id: string): Promise<void>;
+    queryMessages(direction: 'inbound' | 'outbound', filter?: MessageFilter, pagination?: PaginationOptions): Promise<MessagePage>;
+    private matchesFilter;
+    countMessages(direction: 'inbound' | 'outbound', filter?: MessageFilter): Promise<number>;
+    putBlock(entry: BlocklistEntry): Promise<void>;
+    getBlock(did: string): Promise<BlocklistEntry | null>;
+    deleteBlock(did: string): Promise<void>;
+    listBlocked(): Promise<BlocklistEntry[]>;
+    putAllow(entry: AllowlistEntry): Promise<void>;
+    getAllow(did: string): Promise<AllowlistEntry | null>;
+    deleteAllow(did: string): Promise<void>;
+    listAllowed(): Promise<AllowlistEntry[]>;
+    putSeen(entry: SeenEntry): Promise<void>;
+    getSeen(messageId: string): Promise<SeenEntry | null>;
+    cleanupSeen(maxAgeMs: number): Promise<void>;
+    putRateLimit(state: RateLimitState): Promise<void>;
+    getRateLimit(did: string): Promise<RateLimitState | null>;
+    cleanupRateLimits(maxAgeMs: number): Promise<void>;
+}
+
+/**
+ * Message Queue
+ *
+ * Persistent inbox/outbox backed by LevelDB.
+ * Supports real-time subscriptions and pagination.
+ */
+
+interface MessageQueueConfig {
+    dbPath: string;
+}
+declare class MessageQueue {
+    private storage;
+    private subscriptions;
+    private subCounter;
+    constructor(config: MessageQueueConfig);
+    get store(): MessageStorage;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getInbox(filter?: MessageFilter, pagination?: PaginationOptions): Promise<MessagePage>;
+    getMessage(id: string): Promise<StoredMessage | null>;
+    markAsRead(id: string): Promise<void>;
+    deleteMessage(id: string): Promise<void>;
+    getOutbox(pagination?: PaginationOptions): Promise<MessagePage>;
+    retryMessage(id: string): Promise<void>;
+    enqueueInbound(envelope: MessageEnvelope, trustScore?: number): Promise<StoredMessage>;
+    enqueueOutbound(envelope: MessageEnvelope): Promise<StoredMessage>;
+    markOutboundDelivered(id: string): Promise<void>;
+    markOutboundFailed(id: string, error: string): Promise<void>;
+    subscribe(filter: SubscriptionFilter, callback: MessageCallback): string;
+    unsubscribe(subscriptionId: string): void;
+    private notifySubscribers;
+    private matchesSubscriptionFilter;
+    getStats(): Promise<QueueStats>;
+}
+
 /**
  * Sybil Defense Mechanisms
  *
@@ -886,6 +1097,102 @@ declare class TrustSystem {
  */
 declare function createTrustSystem(config: TrustSystemConfig): TrustSystem;
 
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Classic token bucket algorithm for per-sender rate limiting.
+ * Tokens refill at a constant rate up to capacity.
+ */
+interface TokenBucketConfig {
+    capacity: number;
+    refillRate: number;
+}
+declare class TokenBucket {
+    private tokens;
+    private lastRefill;
+    private readonly capacity;
+    private readonly refillRate;
+    constructor(config: TokenBucketConfig, initialTokens?: number, lastRefill?: number);
+    /** Attempt to consume one token. Returns true if allowed. */
+    consume(): boolean;
+    getRemaining(): number;
+    /** Milliseconds until at least one token is available */
+    getResetTime(): number;
+    /** Serialize state for persistence */
+    toState(): {
+        tokens: number;
+        lastRefill: number;
+    };
+    private refill;
+}
+/**
+ * Rate limiter tiers based on trust score
+ */
+interface RateLimitTiers {
+    /** Trust < 0.3: new/unknown agents */
+    newAgent: TokenBucketConfig;
+    /** Trust 0.3–0.6: established agents */
+    established: TokenBucketConfig;
+    /** Trust > 0.6: trusted agents */
+    trusted: TokenBucketConfig;
+}
+declare const DEFAULT_RATE_LIMIT_TIERS: RateLimitTiers;
+declare function getTierConfig(trustScore: number, tiers: RateLimitTiers): TokenBucketConfig;
+
+/**
+ * Defense Middleware
+ *
+ * Checks incoming messages against:
+ * 1. Allowlist bypass
+ * 2. Blocklist rejection
+ * 3. Deduplication (seen cache)
+ * 4. Trust score filtering
+ * 5. Rate limiting (token bucket, tiered by trust)
+ */
+
+interface DefenseConfig {
+    trustSystem: TrustSystem;
+    storage: MessageStorage;
+    /** Minimum trust score to accept messages (0 = accept all) */
+    minTrustScore?: number;
+    /** Auto-block agents below this score */
+    autoBlockThreshold?: number;
+    rateLimitTiers?: RateLimitTiers;
+    /** TTL for seen-cache entries in ms (default: 1 hour) */
+    seenTtlMs?: number;
+}
+declare class DefenseMiddleware {
+    private readonly trust;
+    private readonly storage;
+    private readonly minTrustScore;
+    private readonly autoBlockThreshold;
+    private readonly tiers;
+    private readonly seenTtlMs;
+    private readonly seenCache;
+    private readonly MAX_SEEN_CACHE;
+    private readonly buckets;
+    constructor(config: DefenseConfig);
+    /**
+     * Run all defense checks on an incoming message.
+     * Returns { allowed: true } if the message should be processed,
+     * or { allowed: false, reason } if it should be dropped.
+     */
+    checkMessage(envelope: MessageEnvelope): Promise<DefenseResult>;
+    blockAgent(did: string, reason: string, blockedBy?: string): Promise<void>;
+    unblockAgent(did: string): Promise<void>;
+    isBlocked(did: string): Promise<boolean>;
+    allowAgent(did: string, note?: string): Promise<void>;
+    removeFromAllowlist(did: string): Promise<void>;
+    isAllowed(did: string): Promise<boolean>;
+    checkRateLimit(did: string, trustScore: number): Promise<RateLimitResult>;
+    hasSeen(messageId: string): boolean;
+    markAsSeen(messageId: string): void;
+    /** Periodic cleanup of expired seen entries */
+    cleanupSeen(): Promise<void>;
+    /** Periodic cleanup of stale rate limit buckets (24h inactive) */
+    cleanupRateLimits(): Promise<void>;
+}
+
 declare enum LogLevel {
     DEBUG = 0,
     INFO = 1,
@@ -922,4 +1229,4 @@ declare class MessagingError extends ClawiverseError {
     constructor(message: string, details?: unknown);
 }
 
-export { type AgentCard, CLAWIVERSE_CONTEXT, type Capability, CapabilityMatcher, type CapabilityParameter, CapabilityTypes, type Challenge, type ChallengeSolution, ClawiverseError, type ClawiverseNode, type DHTOperations, DiscoveryError, type Endorsement, EndorsementManager, IdentityError, type Interaction, InteractionHistory, type InteractionStats, type KeyPair, type LegacyAgentCard, LogLevel, Logger, type MessageEnvelope, type MessageHandler, type MessageRouter, MessagingError, ParameterTypes, type PeerHint, type PeerTrustLevel, type ResolvedDID, SCHEMA_ORG_CONTEXT, SearchIndex, type SearchResult, type SemanticQuery, SemanticSearchEngine, type SignFunction, type SignedMessage, SybilDefense, 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, importKeyPair, isLegacyCard, isValidContext, matchesCapability, sign, signAgentCard, signEnvelope, signMessage, upgradeLegacyCard, validateAgentCard, validateDID, validateEnvelope, verify, verifyAgentCard, verifyEnvelope, verifyMessage };
+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 };