@voidly/agent-sdk 3.2.6 → 3.3.0

package/dist/index.d.ts

@@ -96,6 +96,10 @@ interface VoidlyAgentConfig {
     /** Transport preference for listen() — tries in order, falls back automatically
      * Default: ['sse', 'long-poll']. Options: 'websocket' | 'sse' | 'long-poll' */
     transport?: ('websocket' | 'sse' | 'long-poll')[];
+    /** Auto-reset ratchet after N consecutive decrypt failures from same peer (default: 10, 0 = disabled) */
+    autoResetThreshold?: number;
+    /** Callback when a ratchet is auto-reset due to consecutive failures */
+    onRatchetReset?: (peerDid: string, failCount: number) => void;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -192,6 +196,10 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    /** Per-peer consecutive decrypt failure tracking for auto-recovery */
+    private _peerDecryptFails;
+    /** Max consecutive per-peer decrypt failures before auto-resetting ratchet (0 = disabled) */
+    private _autoResetThreshold;
     private _rpcHandlers;
     private _rpcPending;
     private _coverTrafficTimer;
@@ -202,6 +210,7 @@ declare class VoidlyAgent {
     private _persistPath?;
     private _persistKey;
     private _transportPrefs;
+    private _onRatchetReset?;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -290,6 +299,24 @@ declare class VoidlyAgent {
      * Useful for detecting key mismatches, attacks, or corruption.
      */
     get decryptFailCount(): number;
+    /**
+     * Get per-peer consecutive decrypt failure counts.
+     * Useful for diagnosing which peer conversations have desynchronized ratchets.
+     */
+    get peerDecryptFails(): Record<string, number>;
+    /**
+     * Reset ratchet state for a specific peer.
+     * This clears all ratchet keys for the conversation, causing the next send
+     * to re-initialize a fresh DH exchange. The peer's ratchet will also reset
+     * automatically when they receive the new-format message.
+     *
+     * Use this when ratchet desync is detected (e.g., consecutive decrypt failures).
+     * After calling this, both sides need to send a message to re-establish the ratchet.
+     *
+     * @param peerDid - The DID of the peer whose ratchet should be reset
+     * @returns true if a ratchet was found and reset, false if no ratchet existed
+     */
+    resetRatchet(peerDid: string): boolean;
     /**
      * Generate a did:key identifier from this agent's Ed25519 signing key.
      * did:key is a W3C standard — interoperable across systems.

package/dist/index.js

@@ -4082,6 +4082,10 @@ var VoidlyAgent = class _VoidlyAgent {
     this._identityCache = /* @__PURE__ */ new Map();
     this._seenMessageIds = /* @__PURE__ */ new Set();
     this._decryptFailCount = 0;
+    /** Per-peer consecutive decrypt failure tracking for auto-recovery */
+    this._peerDecryptFails = /* @__PURE__ */ new Map();
+    /** Max consecutive per-peer decrypt failures before auto-resetting ratchet (0 = disabled) */
+    this._autoResetThreshold = 10;
     // RPC handlers: method → handler function
     this._rpcHandlers = /* @__PURE__ */ new Map();
     // RPC pending responses: rpc_id → { resolve, reject, timer }
@@ -4117,6 +4121,8 @@ var VoidlyAgent = class _VoidlyAgent {
     this._onLoad = config?.onLoad;
     this._persistPath = config?.persistPath;
     this._transportPrefs = config?.transport || ["sse", "long-poll"];
+    this._autoResetThreshold = config?.autoResetThreshold ?? 10;
+    this._onRatchetReset = config?.onRatchetReset;
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -4519,6 +4525,37 @@ var VoidlyAgent = class _VoidlyAgent {
   get decryptFailCount() {
     return this._decryptFailCount;
   }
+  /**
+   * Get per-peer consecutive decrypt failure counts.
+   * Useful for diagnosing which peer conversations have desynchronized ratchets.
+   */
+  get peerDecryptFails() {
+    return Object.fromEntries(this._peerDecryptFails);
+  }
+  /**
+   * Reset ratchet state for a specific peer.
+   * This clears all ratchet keys for the conversation, causing the next send
+   * to re-initialize a fresh DH exchange. The peer's ratchet will also reset
+   * automatically when they receive the new-format message.
+   *
+   * Use this when ratchet desync is detected (e.g., consecutive decrypt failures).
+   * After calling this, both sides need to send a message to re-establish the ratchet.
+   *
+   * @param peerDid - The DID of the peer whose ratchet should be reset
+   * @returns true if a ratchet was found and reset, false if no ratchet existed
+   */
+  resetRatchet(peerDid) {
+    const sendPairId = `${this.did}:${peerDid}`;
+    const recvPairId = `${peerDid}:${this.did}`;
+    const hadSend = this._ratchetStates.delete(sendPairId);
+    const hadRecv = this._ratchetStates.delete(recvPairId);
+    this._peerDecryptFails.delete(peerDid);
+    if (hadSend || hadRecv) {
+      this._persistRatchetState().catch(() => {
+      });
+    }
+    return hadSend || hadRecv;
+  }
   /**
    * Generate a did:key identifier from this agent's Ed25519 signing key.
    * did:key is a W3C standard — interoperable across systems.
@@ -4752,9 +4789,11 @@ var VoidlyAgent = class _VoidlyAgent {
   /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
   async _decryptMessages(rawMessages) {
     const decrypted = [];
+    const resetPeers = /* @__PURE__ */ new Set();
     for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
+        if (resetPeers.has(msg.from)) continue;
         let senderEncPub;
         let senderSignPubBytes = null;
         if (msg.sender_encryption_key) {
@@ -4890,6 +4929,14 @@ var VoidlyAgent = class _VoidlyAgent {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
               this._decryptFailCount++;
+              const peerForSkip = msg.from || "unknown";
+              const prevSkipFails = this._peerDecryptFails.get(peerForSkip) || 0;
+              this._peerDecryptFails.set(peerForSkip, prevSkipFails + 1);
+              if (this._autoResetThreshold > 0 && prevSkipFails + 1 >= this._autoResetThreshold) {
+                this.resetRatchet(peerForSkip);
+                resetPeers.add(peerForSkip);
+                this._onRatchetReset?.(peerForSkip, prevSkipFails + 1);
+              }
               continue;
             } else {
               let ck = state.recvChainKey;
@@ -4917,8 +4964,22 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (!rawPlaintext) {
           this._decryptFailCount++;
+          const senderForFail = msg.from || "unknown";
+          const prevFails = this._peerDecryptFails.get(senderForFail) || 0;
+          this._peerDecryptFails.set(senderForFail, prevFails + 1);
+          if (this._autoResetThreshold > 0 && prevFails + 1 >= this._autoResetThreshold) {
+            this.resetRatchet(senderForFail);
+            resetPeers.add(senderForFail);
+            this._onRatchetReset?.(senderForFail, prevFails + 1);
+          }
           continue;
         }
+        {
+          const senderForSuccess = msg.from || "unknown";
+          if (this._peerDecryptFails.has(senderForSuccess)) {
+            this._peerDecryptFails.delete(senderForSuccess);
+          }
+        }
         let plaintextBytes = rawPlaintext;
         let wasPadded = false;
         let wasSealed = false;
@@ -4983,6 +5044,9 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (this.requireSignatures && !signatureValid) {
           this._decryptFailCount++;
+          const peerForSig = msg.from || "unknown";
+          const prevSigFails = this._peerDecryptFails.get(peerForSig) || 0;
+          this._peerDecryptFails.set(peerForSig, prevSigFails + 1);
           continue;
         }
         this._seenMessageIds.add(msg.id);
@@ -5009,9 +5073,17 @@ var VoidlyAgent = class _VoidlyAgent {
         });
       } catch {
         this._decryptFailCount++;
+        const peerForCatch = msg.from || "unknown";
+        const prevCatchFails = this._peerDecryptFails.get(peerForCatch) || 0;
+        this._peerDecryptFails.set(peerForCatch, prevCatchFails + 1);
+        if (this._autoResetThreshold > 0 && prevCatchFails + 1 >= this._autoResetThreshold) {
+          this.resetRatchet(peerForCatch);
+          resetPeers.add(peerForCatch);
+          this._onRatchetReset?.(peerForCatch, prevCatchFails + 1);
+        }
       }
     }
-    if (decrypted.length > 0) {
+    if (decrypted.length > 0 || this._peerDecryptFails.size > 0) {
       this._persistRatchetState().catch(() => {
       });
     }

package/dist/index.mjs

@@ -4072,6 +4072,10 @@ var VoidlyAgent = class _VoidlyAgent {
     this._identityCache = /* @__PURE__ */ new Map();
     this._seenMessageIds = /* @__PURE__ */ new Set();
     this._decryptFailCount = 0;
+    /** Per-peer consecutive decrypt failure tracking for auto-recovery */
+    this._peerDecryptFails = /* @__PURE__ */ new Map();
+    /** Max consecutive per-peer decrypt failures before auto-resetting ratchet (0 = disabled) */
+    this._autoResetThreshold = 10;
     // RPC handlers: method → handler function
     this._rpcHandlers = /* @__PURE__ */ new Map();
     // RPC pending responses: rpc_id → { resolve, reject, timer }
@@ -4107,6 +4111,8 @@ var VoidlyAgent = class _VoidlyAgent {
     this._onLoad = config?.onLoad;
     this._persistPath = config?.persistPath;
     this._transportPrefs = config?.transport || ["sse", "long-poll"];
+    this._autoResetThreshold = config?.autoResetThreshold ?? 10;
+    this._onRatchetReset = config?.onRatchetReset;
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -4509,6 +4515,37 @@ var VoidlyAgent = class _VoidlyAgent {
   get decryptFailCount() {
     return this._decryptFailCount;
   }
+  /**
+   * Get per-peer consecutive decrypt failure counts.
+   * Useful for diagnosing which peer conversations have desynchronized ratchets.
+   */
+  get peerDecryptFails() {
+    return Object.fromEntries(this._peerDecryptFails);
+  }
+  /**
+   * Reset ratchet state for a specific peer.
+   * This clears all ratchet keys for the conversation, causing the next send
+   * to re-initialize a fresh DH exchange. The peer's ratchet will also reset
+   * automatically when they receive the new-format message.
+   *
+   * Use this when ratchet desync is detected (e.g., consecutive decrypt failures).
+   * After calling this, both sides need to send a message to re-establish the ratchet.
+   *
+   * @param peerDid - The DID of the peer whose ratchet should be reset
+   * @returns true if a ratchet was found and reset, false if no ratchet existed
+   */
+  resetRatchet(peerDid) {
+    const sendPairId = `${this.did}:${peerDid}`;
+    const recvPairId = `${peerDid}:${this.did}`;
+    const hadSend = this._ratchetStates.delete(sendPairId);
+    const hadRecv = this._ratchetStates.delete(recvPairId);
+    this._peerDecryptFails.delete(peerDid);
+    if (hadSend || hadRecv) {
+      this._persistRatchetState().catch(() => {
+      });
+    }
+    return hadSend || hadRecv;
+  }
   /**
    * Generate a did:key identifier from this agent's Ed25519 signing key.
    * did:key is a W3C standard — interoperable across systems.
@@ -4742,9 +4779,11 @@ var VoidlyAgent = class _VoidlyAgent {
   /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
   async _decryptMessages(rawMessages) {
     const decrypted = [];
+    const resetPeers = /* @__PURE__ */ new Set();
     for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
+        if (resetPeers.has(msg.from)) continue;
         let senderEncPub;
         let senderSignPubBytes = null;
         if (msg.sender_encryption_key) {
@@ -4880,6 +4919,14 @@ var VoidlyAgent = class _VoidlyAgent {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
               this._decryptFailCount++;
+              const peerForSkip = msg.from || "unknown";
+              const prevSkipFails = this._peerDecryptFails.get(peerForSkip) || 0;
+              this._peerDecryptFails.set(peerForSkip, prevSkipFails + 1);
+              if (this._autoResetThreshold > 0 && prevSkipFails + 1 >= this._autoResetThreshold) {
+                this.resetRatchet(peerForSkip);
+                resetPeers.add(peerForSkip);
+                this._onRatchetReset?.(peerForSkip, prevSkipFails + 1);
+              }
               continue;
             } else {
               let ck = state.recvChainKey;
@@ -4907,8 +4954,22 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (!rawPlaintext) {
           this._decryptFailCount++;
+          const senderForFail = msg.from || "unknown";
+          const prevFails = this._peerDecryptFails.get(senderForFail) || 0;
+          this._peerDecryptFails.set(senderForFail, prevFails + 1);
+          if (this._autoResetThreshold > 0 && prevFails + 1 >= this._autoResetThreshold) {
+            this.resetRatchet(senderForFail);
+            resetPeers.add(senderForFail);
+            this._onRatchetReset?.(senderForFail, prevFails + 1);
+          }
           continue;
         }
+        {
+          const senderForSuccess = msg.from || "unknown";
+          if (this._peerDecryptFails.has(senderForSuccess)) {
+            this._peerDecryptFails.delete(senderForSuccess);
+          }
+        }
         let plaintextBytes = rawPlaintext;
         let wasPadded = false;
         let wasSealed = false;
@@ -4973,6 +5034,9 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (this.requireSignatures && !signatureValid) {
           this._decryptFailCount++;
+          const peerForSig = msg.from || "unknown";
+          const prevSigFails = this._peerDecryptFails.get(peerForSig) || 0;
+          this._peerDecryptFails.set(peerForSig, prevSigFails + 1);
           continue;
         }
         this._seenMessageIds.add(msg.id);
@@ -4999,9 +5063,17 @@ var VoidlyAgent = class _VoidlyAgent {
         });
       } catch {
         this._decryptFailCount++;
+        const peerForCatch = msg.from || "unknown";
+        const prevCatchFails = this._peerDecryptFails.get(peerForCatch) || 0;
+        this._peerDecryptFails.set(peerForCatch, prevCatchFails + 1);
+        if (this._autoResetThreshold > 0 && prevCatchFails + 1 >= this._autoResetThreshold) {
+          this.resetRatchet(peerForCatch);
+          resetPeers.add(peerForCatch);
+          this._onRatchetReset?.(peerForCatch, prevCatchFails + 1);
+        }
       }
     }
-    if (decrypted.length > 0) {
+    if (decrypted.length > 0 || this._peerDecryptFails.size > 0) {
       this._persistRatchetState().catch(() => {
       });
     }

package/examples/post-quantum.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Post-Quantum + Ratchet Persistence — Future-proof encrypted messaging.
+ *
+ * Run:  node examples/post-quantum.mjs
+ *
+ * Features demonstrated:
+ *   1. ML-KEM-768 hybrid key exchange (NIST FIPS 203) — quantum-resistant
+ *   2. Double Ratchet forward secrecy — compromise now can't decrypt past messages
+ *   3. Ratchet persistence — session survives agent restarts
+ *   4. Sealed sender — relay can't see who sent the message
+ *   5. Deniable auth — both parties can produce the signature (plausible deniability)
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+// ─── Register with full security config ─────────────────────────────────────
+const alice = await VoidlyAgent.register(
+  { name: 'pq-alice', capabilities: ['chat', 'intel'] },
+  {
+    pq: true,              // Enable ML-KEM-768 post-quantum hybrid
+    padding: true,         // Pad all messages to power-of-2 (traffic analysis resistance)
+    sealedSender: true,    // Hide sender DID from relay metadata
+    deniable: true,        // HMAC signatures (both parties can produce — deniable)
+    persist: 'memory',     // Ratchet state persists in memory (use 'file' or 'relay' for disk)
+    autoPin: true,         // TOFU: pin first-seen keys, warn on change
+  }
+);
+
+const bob = await VoidlyAgent.register(
+  { name: 'pq-bob', capabilities: ['chat', 'analysis'] },
+  {
+    pq: true,
+    padding: true,
+    sealedSender: true,
+    deniable: true,
+    persist: 'memory',
+    autoPin: true,
+  }
+);
+
+console.log(`Alice: ${alice.did} (PQ + sealed + deniable)`);
+console.log(`Bob:   ${bob.did} (PQ + sealed + deniable)\n`);
+
+// ─── Verify post-quantum is active ──────────────────────────────────────────
+const threat = alice.threatModel();
+console.log('Active protections:');
+threat.protections.forEach(p => console.log(`  ✓ ${p}`));
+console.log('Known gaps:');
+threat.gaps.forEach(g => console.log(`  ⚠ ${g}`));
+
+// ─── Send messages with full protection stack ───────────────────────────────
+console.log('\nSending with PQ hybrid + Double Ratchet + sealed sender + padding...');
+await alice.send(bob.did, 'Quantum-resistant hello from Alice', { threadId: 'pq-demo' });
+await alice.send(bob.did, 'Even a quantum computer cannot decrypt this retroactively');
+
+// Bob receives and decrypts
+const messages = await bob.receive({ limit: 10 });
+for (const msg of messages) {
+  console.log(`\n  Bob received: "${msg.content}"`);
+  console.log(`    From:            ${msg.from.slice(0, 30)}...`);
+  console.log(`    Signature valid: ${msg.signatureValid}`);
+}
+
+// ─── Demonstrate forward secrecy ────────────────────────────────────────────
+console.log('\n─── Forward Secrecy Demo ───');
+console.log('Ratchet advances with each message — past keys are deleted.');
+console.log('Even if an attacker compromises the agent NOW, they cannot');
+console.log('decrypt messages that were already received and processed.\n');
+
+// Bob replies — DH ratchet advances
+await bob.send(alice.did, 'Reply from Bob — ratchet advanced');
+const replies = await alice.receive({ limit: 5 });
+for (const r of replies) {
+  console.log(`  Alice received: "${r.content}"`);
+}
+
+// ─── Credential export (includes ratchet state) ─────────────────────────────
+console.log('\n─── Credential Export ───');
+const creds = alice.exportCredentials();
+console.log(`  DID:          ${creds.did}`);
+console.log(`  Signing key:  ${creds.signingSecretKey.slice(0, 16)}...`);
+console.log(`  PQ enabled:   ${!!creds.mlkemSecretKey}`);
+
+// Restore agent from credentials (e.g., after restart)
+const restored = VoidlyAgent.fromCredentials(creds, {
+  pq: true, padding: true, sealedSender: true, deniable: true, persist: 'memory',
+});
+console.log(`  Restored DID: ${restored.did} (matches: ${restored.did === alice.did})`);
+
+// ─── Flush ratchet state ────────────────────────────────────────────────────
+await alice.flushRatchetState();
+console.log('\n  Ratchet state flushed to persistence backend.');
+
+// Clean shutdown
+alice.stopAll();
+bob.stopAll();
+restored.stopAll();
+
+console.log('\n✓ Done — post-quantum hybrid encryption with forward secrecy.');

package/examples/sse-streaming.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * SSE Streaming — Real-time message delivery via Server-Sent Events.
+ *
+ * Run:  node examples/sse-streaming.mjs
+ *
+ * Instead of polling, Bob opens an SSE connection to the relay.
+ * Messages arrive in near-real-time (~1s latency) with automatic reconnection.
+ * All decryption still happens client-side.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const alice = await VoidlyAgent.register({ name: 'sse-alice' });
+const bob   = await VoidlyAgent.register(
+  { name: 'sse-bob' },
+  { transport: ['sse', 'long-poll'] }  // Prefer SSE, fall back to long-poll
+);
+
+console.log(`Alice: ${alice.did}`);
+console.log(`Bob:   ${bob.did} (SSE transport)\n`);
+
+// Bob listens via SSE — messages arrive in near-real-time
+const handle = bob.listen(
+  (msg) => {
+    console.log(`  ← Bob received: "${msg.content}" from ${msg.from.slice(0, 24)}...`);
+    console.log(`    Signature valid: ${msg.signatureValid}`);
+  },
+  {
+    interval: 2000,    // Reconnect interval if SSE drops
+    adaptive: true,    // Back off when idle
+    heartbeat: false,  // Don't send pings
+  }
+);
+
+// Wait for SSE connection to establish
+await new Promise(r => setTimeout(r, 1500));
+
+// Alice sends a burst of messages
+console.log('Alice sending 3 messages...');
+await alice.send(bob.did, 'Message 1 — SSE delivery');
+await alice.send(bob.did, 'Message 2 — near-real-time');
+await alice.send(bob.did, 'Message 3 — all encrypted');
+
+// Wait for delivery
+await new Promise(r => setTimeout(r, 5000));
+
+// Clean shutdown
+handle.stop();
+alice.stopAll();
+bob.stopAll();
+
+console.log('\n✓ Done — SSE streaming with E2E encryption.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.2.6",
+  "version": "3.3.0",
   "description": "E2E encrypted agent-to-agent communication SDK — Double Ratchet, X3DH, deniable auth, ML-KEM-768 post-quantum, SSE streaming, ratchet persistence, multi-relay federation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",