@highway1/core 0.1.46 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highway1/core",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "Core protocol implementation for Clawiverse",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -24,6 +24,11 @@ export * from './discovery/semantic-search.js';
 export * from './messaging/envelope.js';
 export * from './messaging/codec.js';
 export * from './messaging/router.js';
+export * from './messaging/types.js';
+export * from './messaging/storage.js';
+export * from './messaging/queue.js';
+export * from './messaging/defense.js';
+export * from './messaging/rate-limiter.js';
 
 // Trust (Phase 2)
 export * from './trust/index.js';

package/src/messaging/defense.ts

@@ -0,0 +1,236 @@
+/**
+ * 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)
+ */
+
+import { createLogger } from '../utils/logger.js';
+import type { MessageEnvelope } from './envelope.js';
+import type { TrustSystem } from '../trust/index.js';
+import type { MessageStorage } from './storage.js';
+import type { DefenseResult, RateLimitResult } from './types.js';
+import {
+  TokenBucket,
+  DEFAULT_RATE_LIMIT_TIERS,
+  getTierConfig,
+  type RateLimitTiers,
+} from './rate-limiter.js';
+
+const logger = createLogger('defense');
+
+export 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;
+}
+
+export class DefenseMiddleware {
+  private readonly trust: TrustSystem;
+  private readonly storage: MessageStorage;
+  private readonly minTrustScore: number;
+  private readonly autoBlockThreshold: number;
+  private readonly tiers: RateLimitTiers;
+  private readonly seenTtlMs: number;
+
+  // In-memory LRU-style seen cache (backed by LevelDB for persistence)
+  private readonly seenCache = new Map<string, number>(); // id → seenAt
+  private readonly MAX_SEEN_CACHE = 10_000;
+
+  // In-memory token buckets (backed by LevelDB for persistence)
+  private readonly buckets = new Map<string, TokenBucket>();
+
+  constructor(config: DefenseConfig) {
+    this.trust = config.trustSystem;
+    this.storage = config.storage;
+    this.minTrustScore = config.minTrustScore ?? 0;
+    this.autoBlockThreshold = config.autoBlockThreshold ?? 0.1;
+    this.tiers = config.rateLimitTiers ?? DEFAULT_RATE_LIMIT_TIERS;
+    this.seenTtlMs = config.seenTtlMs ?? 60 * 60 * 1000; // 1 hour
+  }
+
+  /**
+   * 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.
+   */
+  async checkMessage(envelope: MessageEnvelope): Promise<DefenseResult> {
+    const did = envelope.from;
+
+    // 1. Allowlist bypass — skip all other checks
+    if (await this.isAllowed(did)) {
+      this.markAsSeen(envelope.id);
+      return { allowed: true };
+    }
+
+    // 2. Blocklist check
+    if (await this.isBlocked(did)) {
+      logger.debug('Message rejected: blocked', { id: envelope.id, from: did });
+      return { allowed: false, reason: 'blocked' };
+    }
+
+    // 3. Deduplication
+    if (this.hasSeen(envelope.id)) {
+      logger.debug('Message rejected: duplicate', { id: envelope.id });
+      return { allowed: false, reason: 'duplicate' };
+    }
+
+    // 4. Trust score check
+    let trustScore = 0;
+    try {
+      const score = await this.trust.getTrustScore(did);
+      trustScore = score.interactionScore;
+
+      // Auto-block very low trust agents
+      if (trustScore < this.autoBlockThreshold && trustScore > 0) {
+        logger.warn('Auto-blocking low-trust agent', { did, trustScore });
+        await this.blockAgent(did, `Auto-blocked: trust score ${trustScore.toFixed(2)} below threshold`);
+        return { allowed: false, reason: 'blocked' };
+      }
+
+      if (trustScore < this.minTrustScore) {
+        logger.debug('Message rejected: trust too low', { id: envelope.id, trustScore });
+        return { allowed: false, reason: 'trust_too_low', trustScore };
+      }
+    } catch (err) {
+      logger.warn('Trust score lookup failed, using 0', { did, error: (err as Error).message });
+    }
+
+    // 5. Rate limiting (tiered by trust)
+    const rateLimitResult = await this.checkRateLimit(did, trustScore);
+    if (!rateLimitResult.allowed) {
+      logger.debug('Message rejected: rate limited', {
+        id: envelope.id,
+        from: did,
+        resetTime: rateLimitResult.resetTime,
+      });
+      return {
+        allowed: false,
+        reason: 'rate_limited',
+        remainingTokens: rateLimitResult.remaining,
+        resetTime: rateLimitResult.resetTime,
+      };
+    }
+
+    // All checks passed
+    this.markAsSeen(envelope.id);
+    return { allowed: true, trustScore, remainingTokens: rateLimitResult.remaining };
+  }
+
+  // ─── Blocklist ────────────────────────────────────────────────────────────
+
+  async blockAgent(did: string, reason: string, blockedBy = 'local'): Promise<void> {
+    await this.storage.putBlock({ did, reason, blockedAt: Date.now(), blockedBy });
+    logger.info('Agent blocked', { did, reason });
+  }
+
+  async unblockAgent(did: string): Promise<void> {
+    await this.storage.deleteBlock(did);
+    logger.info('Agent unblocked', { did });
+  }
+
+  async isBlocked(did: string): Promise<boolean> {
+    return (await this.storage.getBlock(did)) !== null;
+  }
+
+  // ─── Allowlist ────────────────────────────────────────────────────────────
+
+  async allowAgent(did: string, note?: string): Promise<void> {
+    await this.storage.putAllow({ did, addedAt: Date.now(), note });
+    logger.info('Agent allowlisted', { did });
+  }
+
+  async removeFromAllowlist(did: string): Promise<void> {
+    await this.storage.deleteAllow(did);
+    logger.info('Agent removed from allowlist', { did });
+  }
+
+  async isAllowed(did: string): Promise<boolean> {
+    return (await this.storage.getAllow(did)) !== null;
+  }
+
+  // ─── Rate Limiting ────────────────────────────────────────────────────────
+
+  async checkRateLimit(did: string, trustScore: number): Promise<RateLimitResult> {
+    const tierConfig = getTierConfig(trustScore, this.tiers);
+
+    // Load or create bucket
+    let bucket = this.buckets.get(did);
+    if (!bucket) {
+      // Try to restore from LevelDB
+      const persisted = await this.storage.getRateLimit(did);
+      if (persisted) {
+        bucket = new TokenBucket(tierConfig, persisted.tokens, persisted.lastRefill);
+      } else {
+        bucket = new TokenBucket(tierConfig);
+      }
+      this.buckets.set(did, bucket);
+    }
+
+    const allowed = bucket.consume();
+    const state = bucket.toState();
+
+    // Persist updated state
+    await this.storage.putRateLimit({
+      did,
+      tokens: state.tokens,
+      lastRefill: state.lastRefill,
+      totalRequests: 0,
+      firstSeen: Date.now(),
+    });
+
+    return {
+      allowed,
+      remaining: bucket.getRemaining(),
+      resetTime: bucket.getResetTime(),
+      limit: tierConfig.capacity,
+    };
+  }
+
+  // ─── Seen Cache (deduplication) ───────────────────────────────────────────
+
+  hasSeen(messageId: string): boolean {
+    return this.seenCache.has(messageId);
+  }
+
+  markAsSeen(messageId: string): void {
+    // Evict oldest entries if at capacity
+    if (this.seenCache.size >= this.MAX_SEEN_CACHE) {
+      const firstKey = this.seenCache.keys().next().value;
+      if (firstKey) this.seenCache.delete(firstKey);
+    }
+    this.seenCache.set(messageId, Date.now());
+
+    // Persist to LevelDB (fire-and-forget)
+    this.storage.putSeen({ messageId, seenAt: Date.now(), fromDid: '' }).catch(() => {});
+  }
+
+  /** Periodic cleanup of expired seen entries */
+  async cleanupSeen(): Promise<void> {
+    const cutoff = Date.now() - this.seenTtlMs;
+    for (const [id, seenAt] of this.seenCache) {
+      if (seenAt < cutoff) this.seenCache.delete(id);
+    }
+    await this.storage.cleanupSeen(this.seenTtlMs);
+  }
+
+  /** Periodic cleanup of stale rate limit buckets (24h inactive) */
+  async cleanupRateLimits(): Promise<void> {
+    const staleMs = 24 * 60 * 60 * 1000;
+    const cutoff = Date.now() - staleMs;
+    for (const [did, bucket] of this.buckets) {
+      if (bucket.toState().lastRefill < cutoff) this.buckets.delete(did);
+    }
+    await this.storage.cleanupRateLimits(staleMs);
+  }
+}

package/src/messaging/index.ts

@@ -1,3 +1,8 @@
 export * from './envelope.js';
 export * from './codec.js';
 export * from './router.js';
+export * from './types.js';
+export * from './storage.js';
+export * from './queue.js';
+export * from './defense.js';
+export * from './rate-limiter.js';

package/src/messaging/queue.ts

@@ -0,0 +1,181 @@
+/**
+ * Message Queue
+ *
+ * Persistent inbox/outbox backed by LevelDB.
+ * Supports real-time subscriptions and pagination.
+ */
+
+import { createLogger } from '../utils/logger.js';
+import type { MessageEnvelope } from './envelope.js';
+import { MessageStorage } from './storage.js';
+import type {
+  StoredMessage,
+  MessageFilter,
+  PaginationOptions,
+  MessagePage,
+  MessageCallback,
+  SubscriptionFilter,
+  QueueStats,
+} from './types.js';
+
+const logger = createLogger('message-queue');
+
+export interface MessageQueueConfig {
+  dbPath: string;
+}
+
+interface Subscription {
+  id: string;
+  filter: SubscriptionFilter;
+  callback: MessageCallback;
+}
+
+export class MessageQueue {
+  private storage: MessageStorage;
+  private subscriptions = new Map<string, Subscription>();
+  private subCounter = 0;
+
+  constructor(config: MessageQueueConfig) {
+    this.storage = new MessageStorage(config.dbPath);
+  }
+
+  get store(): MessageStorage {
+    return this.storage;
+  }
+
+  async start(): Promise<void> {
+    await this.storage.open();
+    logger.info('Message queue started');
+  }
+
+  async stop(): Promise<void> {
+    await this.storage.close();
+    this.subscriptions.clear();
+    logger.info('Message queue stopped');
+  }
+
+  // ─── Inbox ────────────────────────────────────────────────────────────────
+
+  async getInbox(filter: MessageFilter = {}, pagination: PaginationOptions = {}): Promise<MessagePage> {
+    return this.storage.queryMessages('inbound', filter, pagination);
+  }
+
+  async getMessage(id: string): Promise<StoredMessage | null> {
+    return this.storage.getMessage(id);
+  }
+
+  async markAsRead(id: string): Promise<void> {
+    await this.storage.updateMessage(id, { readAt: Date.now() });
+  }
+
+  async deleteMessage(id: string): Promise<void> {
+    await this.storage.deleteMessage(id);
+  }
+
+  // ─── Outbox ───────────────────────────────────────────────────────────────
+
+  async getOutbox(pagination: PaginationOptions = {}): Promise<MessagePage> {
+    return this.storage.queryMessages('outbound', {}, pagination);
+  }
+
+  async retryMessage(id: string): Promise<void> {
+    await this.storage.updateMessage(id, { status: 'pending', error: undefined });
+  }
+
+  // ─── Enqueue ──────────────────────────────────────────────────────────────
+
+  async enqueueInbound(envelope: MessageEnvelope, trustScore?: number): Promise<StoredMessage> {
+    const msg: StoredMessage = {
+      envelope,
+      direction: 'inbound',
+      status: 'pending',
+      receivedAt: Date.now(),
+      trustScore,
+    };
+    await this.storage.putMessage(msg);
+    logger.debug('Enqueued inbound message', { id: envelope.id, from: envelope.from });
+    this.notifySubscribers(msg);
+    return msg;
+  }
+
+  async enqueueOutbound(envelope: MessageEnvelope): Promise<StoredMessage> {
+    const msg: StoredMessage = {
+      envelope,
+      direction: 'outbound',
+      status: 'pending',
+      sentAt: Date.now(),
+    };
+    await this.storage.putMessage(msg);
+    logger.debug('Enqueued outbound message', { id: envelope.id, to: envelope.to });
+    return msg;
+  }
+
+  async markOutboundDelivered(id: string): Promise<void> {
+    await this.storage.updateMessage(id, { status: 'delivered' });
+  }
+
+  async markOutboundFailed(id: string, error: string): Promise<void> {
+    await this.storage.updateMessage(id, { status: 'failed', error });
+  }
+
+  // ─── Subscriptions ────────────────────────────────────────────────────────
+
+  subscribe(filter: SubscriptionFilter, callback: MessageCallback): string {
+    const id = `sub_${++this.subCounter}`;
+    this.subscriptions.set(id, { id, filter, callback });
+    logger.debug('Subscription added', { id });
+    return id;
+  }
+
+  unsubscribe(subscriptionId: string): void {
+    this.subscriptions.delete(subscriptionId);
+    logger.debug('Subscription removed', { id: subscriptionId });
+  }
+
+  private notifySubscribers(msg: StoredMessage): void {
+    for (const sub of this.subscriptions.values()) {
+      if (this.matchesSubscriptionFilter(msg, sub.filter)) {
+        Promise.resolve(sub.callback(msg)).catch((err) => {
+          logger.warn('Subscription callback error', { id: sub.id, error: (err as Error).message });
+        });
+      }
+    }
+  }
+
+  private matchesSubscriptionFilter(msg: StoredMessage, filter: SubscriptionFilter): boolean {
+    if (filter.fromDid) {
+      const froms = Array.isArray(filter.fromDid) ? filter.fromDid : [filter.fromDid];
+      if (!froms.includes(msg.envelope.from)) return false;
+    }
+    if (filter.protocol) {
+      const protos = Array.isArray(filter.protocol) ? filter.protocol : [filter.protocol];
+      if (!protos.includes(msg.envelope.protocol)) return false;
+    }
+    if (filter.type && msg.envelope.type !== filter.type) return false;
+    return true;
+  }
+
+  // ─── Stats ────────────────────────────────────────────────────────────────
+
+  async getStats(): Promise<QueueStats> {
+    const [inboxTotal, inboxUnread, outboxPending, outboxFailed, blocked, allowed] =
+      await Promise.all([
+        this.storage.countMessages('inbound'),
+        this.storage.countMessages('inbound', { unreadOnly: true }),
+        this.storage.countMessages('outbound', { status: 'pending' }),
+        this.storage.countMessages('outbound', { status: 'failed' }),
+        this.storage.listBlocked().then((l) => l.length),
+        this.storage.listAllowed().then((l) => l.length),
+      ]);
+
+    return {
+      inboxTotal,
+      inboxUnread,
+      outboxPending,
+      outboxFailed,
+      blockedAgents: blocked,
+      allowedAgents: allowed,
+      rateLimitedAgents: 0,
+    };
+  }
+}

package/src/messaging/rate-limiter.ts

@@ -0,0 +1,85 @@
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Classic token bucket algorithm for per-sender rate limiting.
+ * Tokens refill at a constant rate up to capacity.
+ */
+
+export interface TokenBucketConfig {
+  capacity: number;    // Max tokens (burst size)
+  refillRate: number;  // Tokens per millisecond
+}
+
+export class TokenBucket {
+  private tokens: number;
+  private lastRefill: number;
+  private readonly capacity: number;
+  private readonly refillRate: number; // tokens per ms
+
+  constructor(config: TokenBucketConfig, initialTokens?: number, lastRefill?: number) {
+    this.capacity = config.capacity;
+    this.refillRate = config.refillRate;
+    this.tokens = initialTokens ?? config.capacity;
+    this.lastRefill = lastRefill ?? Date.now();
+  }
+
+  /** Attempt to consume one token. Returns true if allowed. */
+  consume(): boolean {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+
+  getRemaining(): number {
+    this.refill();
+    return Math.floor(this.tokens);
+  }
+
+  /** Milliseconds until at least one token is available */
+  getResetTime(): number {
+    this.refill();
+    if (this.tokens >= 1) return 0;
+    const needed = 1 - this.tokens;
+    return Math.ceil(needed / this.refillRate);
+  }
+
+  /** Serialize state for persistence */
+  toState(): { tokens: number; lastRefill: number } {
+    return { tokens: this.tokens, lastRefill: this.lastRefill };
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const newTokens = elapsed * this.refillRate;
+    this.tokens = Math.min(this.capacity, this.tokens + newTokens);
+    this.lastRefill = now;
+  }
+}
+
+/**
+ * Rate limiter tiers based on trust score
+ */
+export 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;
+}
+
+export const DEFAULT_RATE_LIMIT_TIERS: RateLimitTiers = {
+  newAgent:    { capacity: 10,   refillRate: 10   / (60 * 1000) }, // 10/min, burst 10
+  established: { capacity: 100,  refillRate: 60   / (60 * 1000) }, // 60/min, burst 100
+  trusted:     { capacity: 1000, refillRate: 600  / (60 * 1000) }, // 600/min, burst 1000
+};
+
+export function getTierConfig(trustScore: number, tiers: RateLimitTiers): TokenBucketConfig {
+  if (trustScore >= 0.6) return tiers.trusted;
+  if (trustScore >= 0.3) return tiers.established;
+  return tiers.newAgent;
+}

package/src/messaging/router.ts

@@ -132,15 +132,27 @@ export function createMessageRouter(
               });
               const s = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
               logger.info('Direct dial succeeded', { addr });
-              return s;
+              return { conn, stream: s };
             } catch {
               return null;
             }
           });
 
-          stream = await Promise.race(
-            directDialPromises.map(p => p.then(s => s || Promise.reject()))
+          const winner = await Promise.race(
+            directDialPromises.map(p => p.then(r => r || Promise.reject()))
           ).catch(() => undefined);
+
+          if (winner) {
+            stream = winner.stream;
+            // Close connections whose streams were not selected
+            Promise.allSettled(directDialPromises).then((results) => {
+              for (const result of results) {
+                if (result.status === 'fulfilled' && result.value && result.value.stream !== stream) {
+                  result.value.conn.close().catch(() => {});
+                }
+              }
+            });
+          }
         }
 
         let lastError: unknown;
@@ -163,7 +175,7 @@ export function createMessageRouter(
                 logger.info('Relay connection established', { addr });
                 const s = await conn.newStream(PROTOCOL_PREFIX, { runOnLimitedConnection: true });
                 logger.info('Relay stream opened', { addr });
-                return s;
+                return { conn, stream: s };
               } catch (relayErr) {
                 logger.warn('Relay dial failed', { addr, error: (relayErr as Error).message });
                 lastError = relayErr;
@@ -171,9 +183,21 @@ export function createMessageRouter(
               }
             });
 
-            stream = await Promise.race(
-              relayDialPromises.map(p => p.then(s => s || Promise.reject()))
+            const winner = await Promise.race(
+              relayDialPromises.map(p => p.then(r => r || Promise.reject()))
             ).catch(() => undefined);
+
+            if (winner) {
+              stream = winner.stream;
+              // Close connections whose streams were not selected
+              Promise.allSettled(relayDialPromises).then((results) => {
+                for (const result of results) {
+                  if (result.status === 'fulfilled' && result.value && result.value.stream !== stream) {
+                    result.value.conn.close().catch(() => {});
+                  }
+                }
+              });
+            }
           }
         }
 
@@ -218,7 +242,7 @@ export function createMessageRouter(
 
           try {
             // Add timeout to prevent infinite blocking
-            const RESPONSE_TIMEOUT = 5000; // 5 seconds
+            const RESPONSE_TIMEOUT = 30000; // 30 seconds (CVP-0010 §4.2)
 
             const responsePromise = (async () => {
               const responseChunks: Uint8Array[] = [];
@@ -301,6 +325,13 @@ async function handleIncomingStream(
     }
 
     const data = concatUint8Arrays(chunks);
+
+    // Ignore empty streams (from unused parallel dial connections)
+    if (data.length === 0) {
+      logger.debug('Received empty stream, ignoring');
+      return;
+    }
+
     const envelope = decodeMessage(data);
 
     if (!validateEnvelope(envelope)) {