@voidly/agent-sdk 3.2.7 → 3.3.1

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.
@@ -337,7 +364,11 @@ declare class VoidlyAgent {
         messageType?: string;
         unreadOnly?: boolean;
     }): Promise<DecryptedMessage[]>;
-    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports)
+     * Returns decrypted messages AND IDs of messages that failed to decrypt.
+     * Failed messages should be marked as read on the relay — they are permanently
+     * undecryptable and will poison the queue if left unread (Signal-style handling).
+     */
     private _decryptMessages;
     /**
      * Delete a message by ID (must be sender or recipient).

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 ────────────────────────────────────────────────────────
   /**
@@ -4214,6 +4220,7 @@ var VoidlyAgent = class _VoidlyAgent {
       } catch {
       }
     }
+    const effectiveConfig = !mlkemSk && config?.postQuantum !== false ? { ...config, postQuantum: false } : config;
     const agent = new _VoidlyAgent({
       did: creds.did,
       apiKey: creds.apiKey,
@@ -4224,7 +4231,7 @@ var VoidlyAgent = class _VoidlyAgent {
       },
       mlkemPublicKey: mlkemPk,
       mlkemSecretKey: mlkemSk
-    }, config);
+    }, effectiveConfig);
     if (creds.ratchetStates) {
       for (const [pairId, rs] of Object.entries(creds.ratchetStates)) {
         try {
@@ -4519,6 +4526,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.
@@ -4747,14 +4785,37 @@ var VoidlyAgent = class _VoidlyAgent {
       throw new Error(`Receive failed: ${err.error?.message || err.error || res.statusText}`);
     }
     const data = await res.json();
-    return this._decryptMessages(data.messages);
+    const { decrypted, failedIds } = await this._decryptMessages(data.messages);
+    if (failedIds.length > 0) {
+      try {
+        await this.markReadBatch(failedIds);
+      } catch {
+        for (const id of failedIds) {
+          try {
+            await this.markRead(id);
+          } catch {
+          }
+        }
+      }
+    }
+    return decrypted;
   }
-  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports)
+   * Returns decrypted messages AND IDs of messages that failed to decrypt.
+   * Failed messages should be marked as read on the relay — they are permanently
+   * undecryptable and will poison the queue if left unread (Signal-style handling).
+   */
   async _decryptMessages(rawMessages) {
     const decrypted = [];
+    const failedIds = [];
+    const resetPeers = /* @__PURE__ */ new Set();
     for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
+        if (resetPeers.has(msg.from)) {
+          failedIds.push(msg.id);
+          continue;
+        }
         let senderEncPub;
         let senderSignPubBytes = null;
         if (msg.sender_encryption_key) {
@@ -4890,6 +4951,15 @@ var VoidlyAgent = class _VoidlyAgent {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
               this._decryptFailCount++;
+              failedIds.push(msg.id);
+              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 +4987,23 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (!rawPlaintext) {
           this._decryptFailCount++;
+          failedIds.push(msg.id);
+          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 +5068,10 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (this.requireSignatures && !signatureValid) {
           this._decryptFailCount++;
+          failedIds.push(msg.id);
+          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,13 +5098,22 @@ var VoidlyAgent = class _VoidlyAgent {
         });
       } catch {
         this._decryptFailCount++;
+        failedIds.push(msg.id);
+        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(() => {
       });
     }
-    return decrypted;
+    return { decrypted, failedIds };
   }
   // ─── Message Management ─────────────────────────────────────────────────────
   /**
@@ -6371,7 +6469,13 @@ var VoidlyAgent = class _VoidlyAgent {
                 if (eventType === "message" && dataStr) {
                   try {
                     const rawMsg = JSON.parse(dataStr);
-                    const decrypted = await this._decryptMessages([rawMsg]);
+                    const { decrypted, failedIds } = await this._decryptMessages([rawMsg]);
+                    for (const id of failedIds) {
+                      try {
+                        await this.markRead(id);
+                      } catch {
+                      }
+                    }
                     if (decrypted.length > 0) {
                       consecutiveEmpty = 0;
                       sseFailures = 0;

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 ────────────────────────────────────────────────────────
   /**
@@ -4204,6 +4210,7 @@ var VoidlyAgent = class _VoidlyAgent {
       } catch {
       }
     }
+    const effectiveConfig = !mlkemSk && config?.postQuantum !== false ? { ...config, postQuantum: false } : config;
     const agent = new _VoidlyAgent({
       did: creds.did,
       apiKey: creds.apiKey,
@@ -4214,7 +4221,7 @@ var VoidlyAgent = class _VoidlyAgent {
       },
       mlkemPublicKey: mlkemPk,
       mlkemSecretKey: mlkemSk
-    }, config);
+    }, effectiveConfig);
     if (creds.ratchetStates) {
       for (const [pairId, rs] of Object.entries(creds.ratchetStates)) {
         try {
@@ -4509,6 +4516,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.
@@ -4737,14 +4775,37 @@ var VoidlyAgent = class _VoidlyAgent {
       throw new Error(`Receive failed: ${err.error?.message || err.error || res.statusText}`);
     }
     const data = await res.json();
-    return this._decryptMessages(data.messages);
+    const { decrypted, failedIds } = await this._decryptMessages(data.messages);
+    if (failedIds.length > 0) {
+      try {
+        await this.markReadBatch(failedIds);
+      } catch {
+        for (const id of failedIds) {
+          try {
+            await this.markRead(id);
+          } catch {
+          }
+        }
+      }
+    }
+    return decrypted;
   }
-  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports)
+   * Returns decrypted messages AND IDs of messages that failed to decrypt.
+   * Failed messages should be marked as read on the relay — they are permanently
+   * undecryptable and will poison the queue if left unread (Signal-style handling).
+   */
   async _decryptMessages(rawMessages) {
     const decrypted = [];
+    const failedIds = [];
+    const resetPeers = /* @__PURE__ */ new Set();
     for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
+        if (resetPeers.has(msg.from)) {
+          failedIds.push(msg.id);
+          continue;
+        }
         let senderEncPub;
         let senderSignPubBytes = null;
         if (msg.sender_encryption_key) {
@@ -4880,6 +4941,15 @@ var VoidlyAgent = class _VoidlyAgent {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
               this._decryptFailCount++;
+              failedIds.push(msg.id);
+              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 +4977,23 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (!rawPlaintext) {
           this._decryptFailCount++;
+          failedIds.push(msg.id);
+          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 +5058,10 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         if (this.requireSignatures && !signatureValid) {
           this._decryptFailCount++;
+          failedIds.push(msg.id);
+          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,13 +5088,22 @@ var VoidlyAgent = class _VoidlyAgent {
         });
       } catch {
         this._decryptFailCount++;
+        failedIds.push(msg.id);
+        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(() => {
       });
     }
-    return decrypted;
+    return { decrypted, failedIds };
   }
   // ─── Message Management ─────────────────────────────────────────────────────
   /**
@@ -6361,7 +6459,13 @@ var VoidlyAgent = class _VoidlyAgent {
                 if (eventType === "message" && dataStr) {
                   try {
                     const rawMsg = JSON.parse(dataStr);
-                    const decrypted = await this._decryptMessages([rawMsg]);
+                    const { decrypted, failedIds } = await this._decryptMessages([rawMsg]);
+                    for (const id of failedIds) {
+                      try {
+                        await this.markRead(id);
+                      } catch {
+                      }
+                    }
                     if (decrypted.length > 0) {
                       consecutiveEmpty = 0;
                       sseFailures = 0;

package/package.json

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