@voidly/agent-sdk 3.2.7 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.2.7",
+  "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",