@claw-network/node 0.2.2 → 0.3.0

package/dist/services/messaging-service.js

@@ -0,0 +1,705 @@
+/**
+ * MessagingService — orchestrates P2P direct messaging.
+ *
+ * Responsibilities:
+ * - Send messages to target DIDs via libp2p stream protocol
+ * - Receive inbound messages and store in inbox
+ * - Queue messages for offline peers in outbox, deliver on reconnect
+ * - Maintain DID → PeerId mapping via announce protocol
+ * - Periodic TTL cleanup of expired messages
+ */
+import { generateX25519Keypair, x25519SharedSecret, hkdfSha256, encryptAes256Gcm, decryptAes256Gcm, bytesToHex, hexToBytes, } from '@claw-network/core';
+import { createLogger } from '../logger.js';
+import { gzipSync, gunzipSync } from 'node:zlib';
+// ── Constants ────────────────────────────────────────────────────
+const PROTO_DM = '/clawnet/1.0.0/dm';
+const PROTO_DID_ANNOUNCE = '/clawnet/1.0.0/did-announce';
+const PROTO_RECEIPT = '/clawnet/1.0.0/receipt';
+/** Maximum payload size in bytes (64 KB). */
+const MAX_PAYLOAD_BYTES = 65_536;
+/** Cleanup interval for expired messages (5 minutes). */
+const CLEANUP_INTERVAL_MS = 5 * 60_000;
+/** Max attempts before giving up on an outbox message. */
+const MAX_DELIVERY_ATTEMPTS = 50;
+/** Rate limit: max messages per DID per minute. */
+const RATE_LIMIT_PER_MIN = 600;
+/** Rate limit window in milliseconds (1 minute). */
+const RATE_LIMIT_WINDOW_MS = 60_000;
+/** Inbound P2P rate limit: max inbound messages per peer per minute. */
+const INBOUND_RATE_LIMIT = 300;
+/** Interval at which empty rate-limit buckets are pruned (2 minutes). */
+const RATE_BUCKET_GC_INTERVAL_MS = 2 * 60_000;
+/** Maximum concurrency for multicast delivery. */
+const MULTICAST_CONCURRENCY = 20;
+/** Base delay for exponential backoff in outbox retry (ms). */
+const OUTBOX_RETRY_BASE_MS = 1_000;
+/** Maximum backoff delay for outbox retry (ms). */
+const OUTBOX_RETRY_MAX_MS = 60_000;
+/** Valid DID format: did:claw:<multibase-base58btc-encoded-key>. */
+const DID_PATTERN = /^did:claw:z[1-9A-HJ-NP-Za-km-z]{32,64}$/;
+/** Payload size threshold for automatic gzip compression (1 KB). */
+const COMPRESSION_THRESHOLD_BYTES = 1024;
+/** HKDF info tag for E2E messaging encryption. */
+const E2E_MSG_INFO = Buffer.from('clawnet:e2e-msg:v1', 'utf-8');
+/** Priority levels — higher number = higher priority. */
+export var MessagePriority;
+(function (MessagePriority) {
+    MessagePriority[MessagePriority["LOW"] = 0] = "LOW";
+    MessagePriority[MessagePriority["NORMAL"] = 1] = "NORMAL";
+    MessagePriority[MessagePriority["HIGH"] = 2] = "HIGH";
+    MessagePriority[MessagePriority["URGENT"] = 3] = "URGENT";
+})(MessagePriority || (MessagePriority = {}));
+// ── Helpers ──────────────────────────────────────────────────────
+/** Read all data from a stream source into a single Buffer, enforcing a size limit. */
+async function readStream(source, maxBytes = MAX_PAYLOAD_BYTES * 2) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of source) {
+        const bytes = chunk instanceof Uint8Array ? chunk : chunk.subarray();
+        total += bytes.length;
+        if (total > maxBytes) {
+            throw new Error(`Stream exceeded size limit: ${total} > ${maxBytes}`);
+        }
+        chunks.push(Buffer.from(bytes));
+    }
+    return Buffer.concat(chunks);
+}
+/** Write a UTF-8 JSON string to a stream sink. */
+async function writeStream(sink, data) {
+    const encoded = Buffer.from(data, 'utf-8');
+    await sink((async function* () {
+        yield encoded;
+    })());
+}
+// ── Service ──────────────────────────────────────────────────────
+export class MessagingService {
+    log;
+    store;
+    p2p;
+    localDid;
+    cleanupTimer;
+    /**
+     * DID → PeerId mapping. Populated via the did-announce protocol when
+     * peers connect. This is a best-effort cache; entries are never evicted
+     * but may become stale when peers go offline.
+     */
+    didToPeerId = new Map();
+    peerIdToDid = new Map();
+    /** WebSocket subscribers that receive real-time inbox pushes. */
+    subscribers = new Set();
+    /** Sliding-window rate limiter: DID → array of timestamps (ms). */
+    rateBuckets = new Map();
+    /** Inbound rate limiter: peerId → array of timestamps. */
+    inboundRateBuckets = new Map();
+    /** Timer for periodic rate-bucket garbage collection. */
+    rateBucketGcTimer;
+    constructor(p2p, store, localDid) {
+        this.log = createLogger({ level: 'info' });
+        this.p2p = p2p;
+        this.store = store;
+        this.localDid = localDid;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────
+    async start() {
+        // Register stream protocol handlers
+        await this.p2p.handleProtocol(PROTO_DM, (incoming) => {
+            void this.handleInboundMessage(incoming);
+        });
+        await this.p2p.handleProtocol(PROTO_DID_ANNOUNCE, (incoming) => {
+            void this.handleDidAnnounce(incoming);
+        });
+        await this.p2p.handleProtocol(PROTO_RECEIPT, (incoming) => {
+            void this.handleDeliveryReceipt(incoming);
+        });
+        // When a new peer connects, exchange DID announcements
+        this.p2p.onPeerDisconnect(() => {
+            // No-op for now; outbox delivery is handled via flush on connect.
+        });
+        // Announce our DID to all currently connected peers
+        void this.announceToAll();
+        // Periodic cleanup of expired messages
+        this.cleanupTimer = setInterval(() => {
+            try {
+                this.store.cleanupInbox();
+                this.store.cleanupOutbox();
+            }
+            catch {
+                /* best-effort */
+            }
+        }, CLEANUP_INTERVAL_MS);
+        // Periodic GC for rate-limit buckets to prevent memory leaks
+        this.rateBucketGcTimer = setInterval(() => {
+            this.pruneRateBuckets();
+        }, RATE_BUCKET_GC_INTERVAL_MS);
+        this.log.info('[messaging] service started', { localDid: this.localDid });
+    }
+    async stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        if (this.rateBucketGcTimer) {
+            clearInterval(this.rateBucketGcTimer);
+            this.rateBucketGcTimer = undefined;
+        }
+        try {
+            await this.p2p.unhandleProtocol(PROTO_DM);
+        }
+        catch { /* ignore */ }
+        try {
+            await this.p2p.unhandleProtocol(PROTO_DID_ANNOUNCE);
+        }
+        catch { /* ignore */ }
+        try {
+            await this.p2p.unhandleProtocol(PROTO_RECEIPT);
+        }
+        catch { /* ignore */ }
+        this.subscribers.clear();
+    }
+    // ── Public API ─────────────────────────────────────────────────
+    /**
+     * Send a message to a target DID.
+     * If the target peer is online and reachable, delivers directly.
+     * Otherwise queues in outbox for later delivery.
+     */
+    async send(targetDid, topic, payload, opts = {}) {
+        const ttlSec = opts.ttlSec ?? 86400;
+        const priority = opts.priority ?? MessagePriority.NORMAL;
+        // Rate limit check
+        this.enforceRateLimit(this.localDid);
+        // Apply compression + encryption to payload
+        const { encoded, compressed, encrypted } = this.encodePayload(payload, opts);
+        // Validate payload size after encoding
+        const payloadBytes = Buffer.byteLength(encoded, 'utf-8');
+        if (payloadBytes > MAX_PAYLOAD_BYTES) {
+            throw new Error(`Payload too large: ${payloadBytes} bytes (max ${MAX_PAYLOAD_BYTES})`);
+        }
+        const peerId = this.didToPeerId.get(targetDid);
+        if (peerId) {
+            // Try direct delivery
+            const delivered = await this.deliverDirect(peerId, targetDid, topic, encoded, ttlSec, priority, compressed, encrypted, opts.idempotencyKey);
+            if (delivered) {
+                return { messageId: `msg_direct_${Date.now().toString(36)}`, delivered: true, compressed, encrypted };
+            }
+        }
+        // Queue in outbox for later delivery
+        const messageId = this.store.addToOutbox({ targetDid, topic, payload: encoded, ttlSec, priority });
+        this.log.info('message queued in outbox', { messageId, targetDid, topic });
+        return { messageId, delivered: false, compressed, encrypted };
+    }
+    /**
+     * Send a message to multiple target DIDs (multicast).
+     * Each target is attempted independently — partial success is possible.
+     */
+    async sendMulticast(targetDids, topic, payload, opts = {}) {
+        const ttlSec = opts.ttlSec ?? 86400;
+        const priority = opts.priority ?? MessagePriority.NORMAL;
+        // Rate limit check (counts as 1 call for rate-limit purposes)
+        this.enforceRateLimit(this.localDid);
+        // Apply compression (encryption not applied in multicast — each recipient needs their own key)
+        const { encoded, compressed, encrypted } = this.encodePayload(payload, { ...opts, encryptForKeyHex: undefined });
+        const payloadBytes = Buffer.byteLength(encoded, 'utf-8');
+        if (payloadBytes > MAX_PAYLOAD_BYTES) {
+            throw new Error(`Payload too large: ${payloadBytes} bytes (max ${MAX_PAYLOAD_BYTES})`);
+        }
+        // Deliver to all targets concurrently with bounded concurrency
+        const results = await this.deliverMulticast(targetDids, topic, encoded, ttlSec, priority, compressed, encrypted, opts.idempotencyKey);
+        return { results };
+    }
+    /** Query the local inbox. */
+    getInbox(opts) {
+        return this.store.getInbox(opts);
+    }
+    /** Acknowledge (consume) a message from inbox. */
+    ackMessage(messageId) {
+        return this.store.consumeMessage(messageId);
+    }
+    /** Flush outbox: attempt to deliver all pending messages for a specific DID with exponential backoff. */
+    async flushOutboxForDid(targetDid) {
+        const peerId = this.didToPeerId.get(targetDid);
+        if (!peerId)
+            return 0;
+        const entries = this.store.getOutboxForTarget(targetDid);
+        let delivered = 0;
+        const now = Date.now();
+        for (const entry of entries) {
+            if (entry.attempts > MAX_DELIVERY_ATTEMPTS) {
+                this.store.removeFromOutbox(entry.id);
+                continue;
+            }
+            // Exponential backoff: skip if too soon since last attempt
+            const backoff = Math.min(OUTBOX_RETRY_BASE_MS * (2 ** entry.attempts), OUTBOX_RETRY_MAX_MS);
+            const lastAttempt = entry.lastAttempt ?? 0;
+            if (lastAttempt > 0 && now - lastAttempt < backoff) {
+                continue;
+            }
+            this.store.recordAttempt(entry.id);
+            const ok = await this.deliverDirect(peerId, targetDid, entry.topic, entry.payload, entry.ttlSec);
+            if (ok) {
+                this.store.removeFromOutbox(entry.id);
+                delivered++;
+            }
+        }
+        return delivered;
+    }
+    /**
+     * Called when a peer connects. Announces our DID and flushes any
+     * pending outbox messages for that peer's DID.
+     */
+    async onPeerConnected(peerId) {
+        // Announce our DID to the new peer
+        await this.announceDidToPeer(peerId);
+        // Check if we know this peer's DID and flush outbox
+        const did = this.peerIdToDid.get(peerId);
+        if (did) {
+            const flushed = await this.flushOutboxForDid(did);
+            if (flushed > 0) {
+                this.log.info('flushed outbox messages on reconnect', { peerId, did, flushed });
+            }
+        }
+    }
+    /** Return the current DID→PeerId mapping (for debugging/status). */
+    getDidPeerMap() {
+        return Object.fromEntries(this.didToPeerId);
+    }
+    // ── Subscriber Management (WebSocket push) ─────────────────────
+    /** Register a subscriber for real-time inbox pushes. */
+    addSubscriber(cb) {
+        this.subscribers.add(cb);
+    }
+    /** Remove a subscriber. */
+    removeSubscriber(cb) {
+        this.subscribers.delete(cb);
+    }
+    /** Number of active WS subscribers. */
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+    /** Notify all subscribers of a new inbox message (non-blocking). */
+    notifySubscribers(msg) {
+        // Use queueMicrotask to avoid blocking the current handler when there are many subscribers
+        for (const cb of this.subscribers) {
+            queueMicrotask(() => {
+                try {
+                    cb(msg);
+                }
+                catch { /* best-effort */ }
+            });
+        }
+    }
+    // ── Rate Limiting ──────────────────────────────────────────────
+    /**
+     * Check rate limit for a DID. Throws if limit exceeded.
+     * Uses a sliding window of timestamps with binary search eviction.
+     */
+    enforceRateLimit(did) {
+        this.checkRateBucket(this.rateBuckets, did, RATE_LIMIT_PER_MIN);
+    }
+    /** Check if a DID is currently rate-limited (without consuming a slot). */
+    isRateLimited(did) {
+        const now = Date.now();
+        const windowStart = now - RATE_LIMIT_WINDOW_MS;
+        const timestamps = this.rateBuckets.get(did);
+        if (!timestamps)
+            return false;
+        const startIdx = this.bisectLeft(timestamps, windowStart);
+        return (timestamps.length - startIdx) >= RATE_LIMIT_PER_MIN;
+    }
+    /**
+     * Enforce inbound rate limit for a peerId. Throws if limit exceeded.
+     * Prevents P2P peers from spamming without limit.
+     */
+    enforceInboundRateLimit(peerId) {
+        this.checkRateBucket(this.inboundRateBuckets, peerId, INBOUND_RATE_LIMIT);
+    }
+    /**
+     * Core rate-limit check: evict expired entries via binary search,
+     * push new timestamp, throw if over limit.
+     */
+    checkRateBucket(buckets, key, limit) {
+        const now = Date.now();
+        const windowStart = now - RATE_LIMIT_WINDOW_MS;
+        let timestamps = buckets.get(key);
+        if (!timestamps) {
+            timestamps = [];
+            buckets.set(key, timestamps);
+        }
+        // Binary search eviction — O(log n) instead of O(n)
+        const startIdx = this.bisectLeft(timestamps, windowStart);
+        if (startIdx > 0) {
+            timestamps.splice(0, startIdx);
+        }
+        if (timestamps.length >= limit) {
+            throw new RateLimitError(key, limit);
+        }
+        timestamps.push(now);
+    }
+    /** Binary search: find first index where timestamps[i] >= target. */
+    bisectLeft(arr, target) {
+        let lo = 0, hi = arr.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (arr[mid] < target)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo;
+    }
+    /** Remove empty and stale rate-limit buckets to prevent memory leaks. */
+    pruneRateBuckets() {
+        const now = Date.now();
+        const windowStart = now - RATE_LIMIT_WINDOW_MS;
+        for (const [key, ts] of this.rateBuckets) {
+            if (ts.length === 0 || ts[ts.length - 1] < windowStart) {
+                this.rateBuckets.delete(key);
+            }
+        }
+        for (const [key, ts] of this.inboundRateBuckets) {
+            if (ts.length === 0 || ts[ts.length - 1] < windowStart) {
+                this.inboundRateBuckets.delete(key);
+            }
+        }
+    }
+    // ── Private: Payload Encoding (compression + encryption) ────────
+    /**
+     * Encode a payload: optionally compress (gzip) then optionally encrypt (X25519+AES-256-GCM).
+     * Returns the encoded string and flags indicating what was applied.
+     */
+    encodePayload(payload, opts) {
+        let data = payload;
+        let compressed = false;
+        let encrypted = false;
+        // Compression: gzip if enabled and payload > threshold
+        if (opts.compress !== false && Buffer.byteLength(data, 'utf-8') > COMPRESSION_THRESHOLD_BYTES) {
+            const gzipped = gzipSync(Buffer.from(data, 'utf-8'));
+            data = gzipped.toString('base64');
+            compressed = true;
+        }
+        // E2E Encryption: X25519 ECDH + HKDF + AES-256-GCM
+        if (opts.encryptForKeyHex) {
+            const recipientPubKey = hexToBytes(opts.encryptForKeyHex);
+            const ephemeral = generateX25519Keypair();
+            const shared = x25519SharedSecret(ephemeral.privateKey, recipientPubKey);
+            const derived = hkdfSha256(shared, undefined, new Uint8Array(E2E_MSG_INFO), 32);
+            const plainBytes = Buffer.from(data, 'utf-8');
+            const enc = encryptAes256Gcm(derived, new Uint8Array(plainBytes));
+            data = JSON.stringify({
+                _e2e: 1,
+                pk: bytesToHex(ephemeral.publicKey),
+                n: enc.nonceHex,
+                c: enc.ciphertextHex,
+                t: enc.tagHex,
+            });
+            encrypted = true;
+        }
+        return { encoded: data, compressed, encrypted };
+    }
+    /**
+     * Decrypt an E2E-encrypted payload using the local node's X25519 private key.
+     * Returns the decrypted payload string or null if not encrypted / decryption fails.
+     */
+    static decryptPayload(payload, recipientPrivateKey) {
+        try {
+            const envelope = JSON.parse(payload);
+            if (envelope._e2e !== 1 || !envelope.pk || !envelope.n || !envelope.c || !envelope.t)
+                return null;
+            const senderPub = hexToBytes(envelope.pk);
+            const shared = x25519SharedSecret(recipientPrivateKey, senderPub);
+            const derived = hkdfSha256(shared, undefined, new Uint8Array(E2E_MSG_INFO), 32);
+            const decrypted = decryptAes256Gcm(derived, {
+                nonceHex: envelope.n,
+                ciphertextHex: envelope.c,
+                tagHex: envelope.t,
+            });
+            return Buffer.from(decrypted).toString('utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Decompress a gzip-compressed payload (base64-encoded gzip → utf-8 string).
+     * Returns the decompressed string, or null if decompression fails.
+     */
+    static decompressPayload(payload) {
+        try {
+            const buf = Buffer.from(payload, 'base64');
+            const decompressed = gunzipSync(buf);
+            return decompressed.toString('utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Get the current inbox sequence number (for WS replay). */
+    getCurrentSeq() {
+        return this.store.currentSeq();
+    }
+    // ── Private: Direct Delivery ───────────────────────────────────
+    async deliverDirect(peerId, targetDid, topic, payload, ttlSec, priority = MessagePriority.NORMAL, compressed = false, encrypted = false, idempotencyKey) {
+        let stream = null;
+        try {
+            stream = await this.p2p.newStream(peerId, PROTO_DM);
+            const message = JSON.stringify({
+                sourceDid: this.localDid,
+                targetDid,
+                topic,
+                payload,
+                ttlSec,
+                sentAtMs: Date.now(),
+                priority,
+                compressed,
+                encrypted,
+                idempotencyKey,
+            });
+            await writeStream(stream.sink, message);
+            await stream.close();
+            this.log.info('message delivered', { peerId, targetDid, topic });
+            return true;
+        }
+        catch (err) {
+            this.log.warn('direct delivery failed', {
+                peerId,
+                targetDid,
+                error: err.message,
+            });
+            if (stream) {
+                try {
+                    await stream.close();
+                }
+                catch { /* ignore */ }
+            }
+            return false;
+        }
+    }
+    // ── Private: Inbound Message Handler ───────────────────────────
+    async handleInboundMessage(incoming) {
+        const { stream, connection } = incoming;
+        try {
+            // Inbound rate limit check — prevent P2P spam
+            const remotePeer = connection.remotePeer?.toString();
+            if (remotePeer) {
+                try {
+                    this.enforceInboundRateLimit(remotePeer);
+                }
+                catch {
+                    this.log.warn('inbound rate limit exceeded, dropping stream', { peerId: remotePeer });
+                    try {
+                        await stream.close();
+                    }
+                    catch { /* ignore */ }
+                    return;
+                }
+            }
+            // readStream enforces size limit before reading all into memory
+            const raw = await readStream(stream.source);
+            await stream.close();
+            const msg = JSON.parse(raw.toString('utf-8'));
+            if (!msg.sourceDid || !msg.topic || !msg.payload) {
+                this.log.warn('inbound message missing required fields');
+                return;
+            }
+            // Store in inbox (deduplication handled by store if idempotencyKey is present)
+            const messageId = this.store.addToInbox({
+                sourceDid: msg.sourceDid,
+                targetDid: msg.targetDid ?? this.localDid,
+                topic: msg.topic,
+                payload: msg.payload,
+                ttlSec: msg.ttlSec,
+                sentAtMs: msg.sentAtMs,
+                priority: msg.priority ?? MessagePriority.NORMAL,
+                idempotencyKey: msg.idempotencyKey,
+            });
+            // Record DID → PeerId mapping from the sender
+            const remotePeerId = connection.remotePeer?.toString();
+            if (remotePeerId && msg.sourceDid) {
+                this.didToPeerId.set(msg.sourceDid, remotePeerId);
+                this.peerIdToDid.set(remotePeerId, msg.sourceDid);
+            }
+            this.log.info('message received', { messageId, sourceDid: msg.sourceDid, topic: msg.topic });
+            // Push to WebSocket subscribers
+            const currentSeq = this.store.currentSeq();
+            this.notifySubscribers({
+                messageId,
+                sourceDid: msg.sourceDid,
+                topic: msg.topic,
+                payload: msg.payload,
+                receivedAtMs: Date.now(),
+                priority: msg.priority ?? MessagePriority.NORMAL,
+                seq: currentSeq,
+            });
+            // Send delivery receipt back to sender
+            if (remotePeerId) {
+                void this.sendDeliveryReceipt(remotePeerId, messageId, msg.sourceDid);
+            }
+        }
+        catch (err) {
+            this.log.warn('failed to handle inbound message', { error: err.message });
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    // ── Private: DID Announce Protocol ────────────────────────────
+    async handleDidAnnounce(incoming) {
+        const { stream, connection } = incoming;
+        try {
+            const raw = await readStream(stream.source, 1024); // DID announces are tiny
+            await stream.close();
+            const msg = JSON.parse(raw.toString('utf-8'));
+            const remotePeerId = connection.remotePeer?.toString();
+            // Validate DID format to prevent spoofing / garbage entries
+            if (msg.did && !DID_PATTERN.test(msg.did)) {
+                this.log.warn('invalid DID in announce, ignoring', { did: msg.did, peerId: remotePeerId });
+                return;
+            }
+            if (msg.did && remotePeerId) {
+                this.didToPeerId.set(msg.did, remotePeerId);
+                this.peerIdToDid.set(remotePeerId, msg.did);
+                this.log.info('peer DID registered', { did: msg.did, peerId: remotePeerId });
+                // Flush any pending outbox messages for this DID
+                const flushed = await this.flushOutboxForDid(msg.did);
+                if (flushed > 0) {
+                    this.log.info('flushed outbox on DID announce', { did: msg.did, flushed });
+                }
+            }
+        }
+        catch (err) {
+            this.log.warn('failed to handle DID announce', { error: err.message });
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** Announce our DID to a specific peer. */
+    async announceDidToPeer(peerId) {
+        let stream = null;
+        try {
+            stream = await this.p2p.newStream(peerId, PROTO_DID_ANNOUNCE);
+            await writeStream(stream.sink, JSON.stringify({ did: this.localDid }));
+            await stream.close();
+        }
+        catch {
+            // Best-effort; the peer may not support this protocol yet
+            if (stream) {
+                try {
+                    await stream.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    /** Announce our DID to all currently connected peers. */
+    async announceToAll() {
+        const peers = this.p2p.getConnections();
+        for (const peerId of peers) {
+            await this.announceDidToPeer(peerId);
+        }
+    }
+    /**
+     * Deliver to multiple targets concurrently with bounded concurrency.
+     * Uses Promise.allSettled so one failure doesn't block others.
+     */
+    async deliverMulticast(targetDids, topic, payload, ttlSec, priority = MessagePriority.NORMAL, compressed = false, encrypted = false, idempotencyKey) {
+        const results = [];
+        // Process in batches of MULTICAST_CONCURRENCY
+        for (let i = 0; i < targetDids.length; i += MULTICAST_CONCURRENCY) {
+            const batch = targetDids.slice(i, i + MULTICAST_CONCURRENCY);
+            const settled = await Promise.allSettled(batch.map(async (targetDid) => {
+                const peerId = this.didToPeerId.get(targetDid);
+                if (peerId) {
+                    const delivered = await this.deliverDirect(peerId, targetDid, topic, payload, ttlSec, priority, compressed, encrypted, idempotencyKey);
+                    if (delivered) {
+                        return { targetDid, messageId: `msg_direct_${Date.now().toString(36)}`, delivered: true };
+                    }
+                }
+                const messageId = this.store.addToOutbox({ targetDid, topic, payload, ttlSec, priority });
+                return { targetDid, messageId, delivered: false };
+            }));
+            for (const result of settled) {
+                if (result.status === 'fulfilled') {
+                    results.push(result.value);
+                }
+                else {
+                    // This shouldn't normally happen since deliverDirect catches its own errors
+                    this.log.warn('multicast delivery error', { error: String(result.reason) });
+                }
+            }
+        }
+        return results;
+    }
+    // ── Private: Delivery Receipt Protocol ─────────────────────────
+    /** Send a delivery receipt to the sender after receiving a message. */
+    async sendDeliveryReceipt(peerId, messageId, recipientDid) {
+        let stream = null;
+        try {
+            stream = await this.p2p.newStream(peerId, PROTO_RECEIPT);
+            await writeStream(stream.sink, JSON.stringify({
+                type: 'delivered',
+                messageId,
+                recipientDid: this.localDid,
+                senderDid: recipientDid,
+                deliveredAtMs: Date.now(),
+            }));
+            await stream.close();
+            this.log.info('delivery receipt sent', { peerId, messageId });
+        }
+        catch {
+            // Best-effort — receipts are not critical
+            if (stream) {
+                try {
+                    await stream.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    /** Handle an incoming delivery receipt from a remote peer. */
+    async handleDeliveryReceipt(incoming) {
+        const { stream } = incoming;
+        try {
+            const raw = await readStream(stream.source);
+            await stream.close();
+            const receipt = JSON.parse(raw.toString('utf-8'));
+            if (receipt.type === 'delivered' && receipt.messageId) {
+                // Remove from outbox if it was queued
+                this.store.removeFromOutbox(receipt.messageId);
+                this.log.info('delivery receipt received', {
+                    messageId: receipt.messageId,
+                    recipientDid: receipt.recipientDid,
+                });
+                // Notify subscribers about the receipt
+                this.notifySubscribers({
+                    messageId: receipt.messageId,
+                    sourceDid: receipt.recipientDid ?? '',
+                    topic: '_receipt',
+                    payload: JSON.stringify(receipt),
+                    receivedAtMs: receipt.deliveredAtMs ?? Date.now(),
+                    priority: MessagePriority.NORMAL,
+                    seq: 0, // Receipts don't have inbox seq
+                });
+            }
+        }
+        catch {
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+// ── Rate Limit Error ─────────────────────────────────────────────
+export class RateLimitError extends Error {
+    did;
+    limit;
+    constructor(did, limit) {
+        super(`Rate limit exceeded for ${did}: max ${limit} messages/minute`);
+        this.name = 'RateLimitError';
+        this.did = did;
+        this.limit = limit;
+    }
+}
+//# sourceMappingURL=messaging-service.js.map