whalibmob 5.14.1 → 5.14.3

package/README.md

@@ -127,6 +127,7 @@ npm install -g whalibmob
       - [Reading it out of an APK you already have](#reading-it-out-of-an-apk-you-already-have)
     - [Device Attestation with Frida (optional)](#device-attestation-with-frida-optional)
     - [Connect](#connect)
+      - [Client Options](#client-options)
   - [Linking to an Existing Account (Pairing Code)](#linking-to-an-existing-account-pairing-code)
     - [Requesting a Pairing Code](#requesting-a-pairing-code)
     - [Reconnecting a Linked Session](#reconnecting-a-linked-session)
@@ -1928,6 +1929,37 @@ client.on('connected', () => {
 await client.init('919634847671')
 ```
 
+#### Client Options
+
+Every option is optional; `sessionDir` is the only one most senders ever set.
+
+| Option | Default | What it does |
+|---|---|---|
+| `sessionDir` | `~/.waSession` | The authentication folder. Each number gets its own subfolder inside it — see [Saving & Restoring Sessions](#saving--restoring-sessions). |
+| `autoFixNumber` | `true` | Re-file the session automatically when the server reports the account under a different number. Set `false` to be told instead of fixed — see [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under). |
+| `autoRead` | `true` | Send read receipts for incoming messages. `false` leaves them unread. |
+| `pino` | off | Debug logging. `true` turns it on at `debug` level; an object is passed to `pino` as-is. |
+| `sentCacheSize` | `2000` | How many sent messages keep their plaintext so a retry receipt naming them can be answered. |
+| `maxRetryResends` | `5` | How many times one message may be re-sent in answer to retry receipts before the client gives up. |
+
+```js
+const client = new WhalibmobClient({
+  sessionDir:      path.join(process.env.HOME, '.waSession'),
+  sentCacheSize:   10000,
+  maxRetryResends: 8
+})
+```
+
+**When to raise the last two.** A recipient's device that cannot decrypt a message asks for it again, and whalibmob answers by rebuilding the Signal session and re-sending. Answering requires the original text, which is why sent messages are held: a receipt naming a message no longer in the cache cannot be answered at all, and that message — already acked by the server — silently never arrives.
+
+The defaults cover an ordinary sender. Raise `sentCacheSize` if you push messages faster than replies come back, which is easy to do when several recipients are being worked through at once: your own replies age out of the cache while the recipient is still asking for them. The symptom is this line in the debug log:
+
+```
+[DBG] RETRY_RECV msgId=... — no cached plaintext, skipping resend
+```
+
+If you see it, the cache is smaller than your in-flight window. An entry holds the encoded message, not the media it points at, so entries are small and raising the bound costs little memory.
+
 ## Linking to an Existing Account (Pairing Code)
 
 Registering a number over SMS makes whalibmob that number's **own device**. Sometimes that is not what you want — the number is already in use on a phone, or the verification SMS never arrives. For those cases whalibmob can instead connect over a **WebSocket** and link itself to an account that already exists, exactly the way the WhatsApp Web and desktop clients do.

package/lib/Client.js

@@ -29,7 +29,19 @@ const {
 // How many times a message may be re-sent in answer to retry receipts before
 // the client stops. Each resend can itself draw retries, so this is what keeps
 // an undecryptable message from turning into a flood.
-const MAX_RETRY_RESENDS = 2;
+//
+// Matched to the cap on retries we ask for ourselves (5, in _sendRetryRequest):
+// a device that keeps failing is worth the same number of rounds in either
+// direction. Two rounds gave up while the recipient was still asking.
+const MAX_RETRY_RESENDS = 5;
+
+// How many sent messages keep their plaintext for answering a retry receipt.
+// A receipt naming a message no longer held here cannot be answered at all —
+// the message is acked by the server and then silently never arrives. The
+// bound exists for memory, and an entry is small (the encoded Message, not the
+// media it points at), so it is set well above a busy sender's in-flight window
+// rather than at the smallest number that usually works.
+const SENT_CACHE_SIZE = 2000;
 const { NodeCache }       = require('@cacheable/node-cache');
 
 // Group metadata cache lifetime — matches DeviceManager's device cache.
@@ -369,6 +381,11 @@ class WhalibmobClient extends EventEmitter {
     // the second sender's pkmsg arrives after the key was consumed and deleted.
     this._retryAdvertisedPreKeys = new Set();
     this._sentMsgCache     = new Map();   // msgId → {plaintext, toJid, msgId, mediaType, options, recipientPhone}
+    // A sender that keeps more messages in flight than the cache holds outruns
+    // its own ability to answer retries, so both bounds are open to being
+    // raised for that kind of load.
+    this._sentCacheSize    = Number(opts.sentCacheSize)  > 0 ? Number(opts.sentCacheSize)  : SENT_CACHE_SIZE;
+    this._maxRetryResends  = Number(opts.maxRetryResends) > 0 ? Number(opts.maxRetryResends) : MAX_RETRY_RESENDS;
     this._tcTokenStore            = null; // TcTokenStore — loaded in init()
     this._inFlightTcTokenIssuance = new Set(); // dedupe concurrent proactive issuePrivacyTokens per JID
     this._inFlight463Recoveries   = new Set(); // dedupe concurrent 463-triggered token issuances per JID (separate from proactive)
@@ -2415,7 +2432,7 @@ class WhalibmobClient extends EventEmitter {
     // another send and floods the chat. Give up after a few rounds and leave
     // the message undelivered rather than keep spamming.
     const depth = (cached.retryDepth || 0) + 1;
-    if (depth > MAX_RETRY_RESENDS) {
+    if (depth > this._maxRetryResends) {
       _whaDbg('[DBG] RETRY_RECV msgId=' + msgId + ' — giving up after ' +
         cached.retryDepth + ' resends\n');
       return;
@@ -2432,50 +2449,9 @@ class WhalibmobClient extends EventEmitter {
       : fromStr;
     const recipientPhone = targetJid.split('@')[0].split(':')[0].split('.')[0];
 
-    // The retry names the device under one address family, but a contact holds
-    // a session under each: a Signal address is (user, device) with the server
-    // stripped, and the LID user and the phone user are different strings, so
-    // one session is not reachable under the other's name. Purging only the
-    // family the receipt happened to arrive in left the other one in place —
-    // the resend picked it straight back up and produced the same ciphertext
-    // the device had just said it could not read, so the message stayed
-    // undecryptable until something else rebuilt the session.
-    //
-    // This is what made a reply sent after a companion-device exchange stick on
-    // "Waiting for this message" on the primary: the receipt came in one family,
-    // the stale session sat in the other, and every resend re-used it.
-    const recipientUsers = new Set([recipientPhone]);
-    const mappedPn  = this._lidToPn && this._lidToPn.get(recipientPhone);
-    const mappedLid = this._pnToLid && this._pnToLid.get(recipientPhone);
-    if (mappedPn)  recipientUsers.add(mappedPn);
-    if (mappedLid) recipientUsers.add(mappedLid);
-
     _whaDbg('[DBG] RETRY_RECV msgId=' + msgId + ' from=' + fromStr +
-      ' users=[' + [...recipientUsers].join(',') + '] — clearing session + resending\n');
-
-    // Delete all Signal sessions for the recipient's devices so next send creates fresh pkmsg
-    const sigStore = this._signal && this._signal.store;
-    if (sigStore && sigStore._sessions) {
-      const sessions = sigStore._sessions;
-      Object.keys(sessions).forEach(addr => {
-        // Match on the user segment rather than a bare prefix: "4071.0" must
-        // not be cleared by a retry for "407".
-        const user = addr.slice(0, addr.lastIndexOf('.'));
-        if (recipientUsers.has(user)) {
-          _whaDbg('[DBG] RETRY deleting session for ' + addr);
-          delete sessions[addr];
-        }
-      });
-    }
-
-    // Clear device manager cache so we re-fetch devices on next send. LID device
-    // lists are filed under a "lid:" key, so clearing the bare user only ever
-    // dropped the phone-side list.
-    if (this._devMgr) {
-      const cacheKeys = [];
-      for (const u of recipientUsers) cacheKeys.push(u, 'lid:' + u);
-      this._devMgr.clearCache(cacheKeys);
-    }
+      ' — clearing session + resending\n');
+    this._purgeContactSessions(recipientPhone, 'RETRY');
 
     // Re-send the message — will create fresh pre-key (pkmsg) sessions.
     // A group resend must go back through the group path: it needs a fresh
@@ -2723,6 +2699,71 @@ class WhalibmobClient extends EventEmitter {
     this._retryPending.delete(msgId);
   }
 
+  // Drop every Signal session and cached device list a contact owns, so the
+  // next send to them has to fetch a prekey bundle and open a fresh session.
+  //
+  // A contact holds a session under each address family: a Signal address is
+  // (user, device) with the server stripped, and the LID user and the phone
+  // user are different strings, so one session is not reachable under the
+  // other's name. Clearing only the family whose name happened to be at hand
+  // leaves the other in place, and the next send picks it straight back up —
+  // which is how a message stayed undecryptable on a device that had already
+  // said it could not read it.
+  //
+  // Device lists are filed the same way, LID ones under a "lid:" key, so both
+  // spellings of both users have to go.
+  //
+  // Returns the set of users it resolved, for callers that want to log it.
+  _purgeContactSessions(user, tag) {
+    const label = tag || 'PURGE';
+    const users = new Set([String(user)]);
+    const mappedPn  = this._lidToPn && this._lidToPn.get(user);
+    const mappedLid = this._pnToLid && this._pnToLid.get(user);
+    if (mappedPn)  users.add(mappedPn);
+    if (mappedLid) users.add(mappedLid);
+
+    const sigStore = this._signal && this._signal.store;
+    if (sigStore && sigStore._sessions) {
+      const sessions = sigStore._sessions;
+      for (const addr of Object.keys(sessions)) {
+        // Match on the address's user segment rather than a bare string
+        // prefix: a purge for "407" must not take "4071.0" with it.
+        const addrUser = addr.slice(0, addr.lastIndexOf('.'));
+        if (users.has(addrUser)) {
+          _whaDbg('[DBG] ' + label + ' deleting session for ' + addr);
+          // Through the store rather than off the object it hands back: a bare
+          // `delete` leaves the file alone and the store unmarked, so nothing
+          // is written on the way out and a restart loads every purged session
+          // straight back — the one case the purge exists to prevent. Not
+          // awaited on purpose; the method's body is synchronous, so the
+          // delete and the save have both happened by the time it returns.
+          sigStore.deleteSession(addr);
+        }
+      }
+    }
+
+    if (this._devMgr) {
+      const cacheKeys = [];
+      for (const u of users) cacheKeys.push(u, 'lid:' + u);
+      this._devMgr.clearCache(cacheKeys);
+    }
+
+    _whaDbg('[DBG] ' + label + ' purged users=[' + [...users].join(',') + ']');
+    return users;
+  }
+
+  // Hold a sent message's plaintext so a retry receipt naming it can be
+  // answered. Both send paths file their entry here so the bound lives in one
+  // place instead of being repeated as a literal at each call site.
+  _cacheSentMessage(entry) {
+    if (!this._sentMsgCache || !entry || !entry.msgId) return;
+    this._sentMsgCache.set(entry.msgId, entry);
+    // Map preserves insertion order, so the first key is the oldest entry.
+    while (this._sentMsgCache.size > this._sentCacheSize) {
+      this._sentMsgCache.delete(this._sentMsgCache.keys().next().value);
+    }
+  }
+
   _sendRetryRequest(msgId, origNode) {
     const existing = this._retryPending.get(msgId);
     const count    = existing ? existing.count + 1 : 1;
@@ -2943,23 +2984,16 @@ class WhalibmobClient extends EventEmitter {
     }
 
     if (type === 'identity') {
-      // Server push: a contact re-registered WhatsApp (new identity key / new phone).
-      // Their old Signal sessions are no longer valid — clear them and the device
-      // cache so the next send builds a fresh pkmsg session from scratch.
+      // Server push: a contact re-registered WhatsApp (new identity key / new
+      // phone). Every session we hold with them is anchored in an identity key
+      // that no longer exists, so all of them have to go — under both the
+      // number and the LID, or the next send reaches for the survivor and the
+      // contact receives ciphertext nothing on their side can open. A retry
+      // receipt cannot rescue that: the session is not stale, it is dead.
       const fromJid   = String(attrs.from || '');
       const fromPhone = fromJid.split('@')[0].split(':')[0];
-      if (fromPhone && this._devMgr) {
-        this._devMgr._dcDel([fromPhone]);
-        _whaDbg('[DBG] NOTIF_IDENTITY flushed device cache for re-registered ' + fromPhone);
-      }
-      if (fromPhone && this._signal && this._signal.store && this._signal.store._sessions) {
-        const sessions = this._signal.store._sessions;
-        let cleared = 0;
-        for (const addr of Object.keys(sessions)) {
-          if (addr.startsWith(fromPhone + '.')) { delete sessions[addr]; cleared++; }
-        }
-        _whaDbg('[DBG] NOTIF_IDENTITY cleared ' + cleared + ' Signal sessions for ' + fromPhone);
-      }
+      if (fromPhone) this._purgeContactSessions(fromPhone, 'NOTIF_IDENTITY');
+      this.emit('identity_change', { jid: fromJid, user: fromPhone });
     }
 
     // Ack the notification

package/lib/messages/MessageSender.js

@@ -1091,17 +1091,10 @@ class MessageSender {
     }
 
     // Cache plaintext so Client can re-send with fresh session on recipient retry
-    if (this._client._sentMsgCache) {
-      this._client._sentMsgCache.set(msgId, {
-        plaintext, toJid, msgId, mediaType, options, recipientPhone,
-        retryDepth: options._retryDepth || 0
-      });
-      // Keep cache bounded — evict oldest entries beyond 200
-      if (this._client._sentMsgCache.size > 200) {
-        const firstKey = this._client._sentMsgCache.keys().next().value;
-        this._client._sentMsgCache.delete(firstKey);
-      }
-    }
+    this._client._cacheSentMessage({
+      plaintext, toJid, msgId, mediaType, options, recipientPhone,
+      retryDepth: options._retryDepth || 0
+    });
 
     const dispatchResult = await this._dispatchAndAck(msgNode, msgId);
 
@@ -1436,16 +1429,10 @@ class MessageSender {
     // does, and without this the client had nothing to re-send and dropped it
     // with "no cached plaintext" — so the message was acked by the server and
     // then silently never arrived.
-    if (this._client._sentMsgCache) {
-      this._client._sentMsgCache.set(msgId, {
-        plaintext, toJid: groupJid, msgId, mediaType, options, isGroup: true,
-        retryDepth: options._retryDepth || 0
-      });
-      if (this._client._sentMsgCache.size > 200) {
-        const firstKey = this._client._sentMsgCache.keys().next().value;
-        this._client._sentMsgCache.delete(firstKey);
-      }
-    }
+    this._client._cacheSentMessage({
+      plaintext, toJid: groupJid, msgId, mediaType, options, isGroup: true,
+      retryDepth: options._retryDepth || 0
+    });
 
     const msgNode = new BinaryNode('message', stanzaAttrs, msgContent);
     const dispatchResult = await this._dispatchAndAck(msgNode, msgId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.14.1",
+  "version": "5.14.3",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API and web ",
   "author": "Kunboruto20",
   "main": "index.js",