whalibmob 5.19.0 → 5.19.1

package/README.md

@@ -2007,10 +2007,11 @@ Every option is optional; `sessionDir` is the only one most senders ever set.
 | `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. |
-| `refreshVersion` | `true` | **iOS sessions only.** Check the App Store for the current build on every `init()` and write it into the session file. Set `false` to keep announcing whatever the session registered with — see [Keeping the Announced Version Current](#keeping-the-announced-version-current). Android is unaffected either way. |
+| `refreshVersion` | `true` | Check the platform's store for the current build on every connect and reconnect, and write it into the session file. Both iOS and Android. Set `false` to keep announcing whatever the session registered with — see [Keeping the Announced Version Current](#keeping-the-announced-version-current). |
 | `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. |
+| `tcTokenPresendTimeoutMs` | `5000` | How long the first message to a new contact waits for its trusted-contact token before going out without one — see [tcToken — Error 463 Defense](#tctoken--error-463-defense). `0` sends immediately and lets the token arrive for the next message. |
 
 ```js
 const client = new WhalibmobClient({
@@ -3278,8 +3279,9 @@ whalibmob implements the full lifecycle to prevent this:
 | Step | What the library does automatically |
 |---|---|
 | **History seed** | On every history sync chunk, `tcToken` bytes are extracted from each conversation in the protobuf and loaded into `TcTokenStore` in memory. The first send after reconnect already has a valid token ready — no 463 risk on cold start. |
+| **First contact** | The very first DM to a contact has no token on file yet. Before the stanza is built, the library issues one and waits for it, so that message carries a `<tctoken>` like every later one instead of counting as an anonymous reach-out. The wait is bounded by `tcTokenPresendTimeoutMs` (default 5 s) — past it the message goes out regardless and the token lands in time for the next one. |
 | **Attach on send** | Before dispatching any DM, `MessageSender` looks up the token for the recipient JID, checks it has not expired (28-day rolling window), and pushes a `<tctoken>` child node into the message stanza. |
-| **Proactive issuance** | After each successful DM send, the library fires a `<iq type='set' xmlns='privacy'>` requesting a fresh token for that JID from the server — once per 7-day bucket, deduplicated in-flight. |
+| **Renewal** | After a successful DM send, the library fires a `<iq type='set' xmlns='privacy'>` requesting a fresh token for that JID from the server — once per 7-day bucket, deduplicated in-flight. This one is fire-and-forget: the token being attached right now is still valid, so nothing waits for it. |
 | **Incoming notification** | When a contact starts a new conversation, WhatsApp pushes a `<notification type='privacy_token'>`. The library catches it in `_handlePrivacyTokenNotification` and stores the token immediately. |
 | **Identity change re-issue** | When decrypting a `pkmsg` (new Signal session from peer), the library calls `_reissueTcTokenAfterIdentityChange` to re-issue the token for the new session. |
 | **Error 463 recovery** | If a send fails with error 463, the library issues a fresh token, waits for the server response, and automatically retries the same message with the new token attached. |

package/lib/Client.js

@@ -79,6 +79,12 @@ const MEX_QUERY_REACHOUT_TIMELOCK = '23983697327930364';
 // server takes a longer one, answers <iq type="result"/> and keeps the old text.
 const ABOUT_MAX_LENGTH = 139;
 
+// How long the first message to a contact waits for its trusted-contact token.
+// One round-trip to the server, no more: past this the message goes out without
+// a token rather than sitting in the queue, and the issuance finishes in the
+// background for the next send.
+const TC_TOKEN_PRESEND_TIMEOUT_MS = 5000;
+
 // The names privacy settings actually go by on the wire, and the friendly
 // aliases this library has always accepted for them. The wire names are the
 // right-hand column.
@@ -464,6 +470,15 @@ class WhalibmobClient extends EventEmitter {
     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)
+    // jid → in-flight pre-send issuance promise. A Set would only say that one
+    // is running; concurrent first sends to the same contact have to be able to
+    // wait for the same answer, so the promise itself is what gets shared.
+    this._tcTokenIssuanceWaiters  = new Map();
+    // How long a first send will wait for its token before going out without
+    // one. _sendIq gives up after 15s, which is far too long to hold a message.
+    this._tcTokenPresendTimeoutMs =
+      Number(opts.tcTokenPresendTimeoutMs) >= 0
+        ? Number(opts.tcTokenPresendTimeoutMs) : TC_TOKEN_PRESEND_TIMEOUT_MS;
     // Last known account restriction, or null until one is fetched or pushed.
     this._reachoutTimelock        = null;
     this._reachoutTimelockInFlight = null;
@@ -4765,6 +4780,97 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
+  /**
+   * Put a trusted-contact token on file *before* the first message to a contact
+   * is built, so that message carries a `<tctoken>` like every later one.
+   *
+   * The token never came from the contact. `_issuePrivacyTokens` is an IQ to
+   * s.whatsapp.net and the server answers with the bytes, so nothing here waits
+   * on the other side replying, having us in their address book, or a
+   * conversation existing at all.
+   *
+   * What was missing was only the ordering. Issuance ran after
+   * `_dispatchAndAck` and fire-and-forget, so the first message to any new
+   * contact went out with no token and the server counted it as an anonymous
+   * reach-out. At bulk that is one such event per number, which is exactly the
+   * fuel for error 463. The official app issues on opening the chat — before
+   * anything is typed — so `issue → send` is the faithful order, not `send →
+   * issue`.
+   *
+   * Three cases return without waiting, and each matters:
+   *
+   *   - a live token is already on file. Renewal is due eventually, but the
+   *     post-send path does that without holding a message up.
+   *   - `shouldIssue` is false. We already asked inside this 7-day bucket and
+   *     the server gave us nothing; asking again now would put a round-trip in
+   *     front of every send for nothing.
+   *   - the JID is the PSA account or a bot, which cannot timelock us.
+   *
+   * @param   {string}  tcJid        storage key, already through _resolveTcTokenJid
+   * @param   {string}  routingToJid the JID the message is addressed to
+   * @returns {Promise<boolean>}     whether a usable token is on file now
+   */
+  async ensureTcTokenBeforeSend(tcJid, routingToJid) {
+    const store = this._tcTokenStore;
+    if (!store) return false;
+
+    const { tcTokenExpired, isRegularTcTokenUser } = require('./messages/TcTokenStore');
+    if (!isRegularTcTokenUser(tcJid)) return false;
+
+    // Never ourselves. A note-to-self is not a reach-out, and holding it up for
+    // a token nobody will check is the one stall this change could introduce.
+    const bare      = String(tcJid).split('@')[0].split(':')[0];
+    const ownPhone  = this._store && this._store.phoneNumber
+      ? String(this._store.phoneNumber) : null;
+    const ownLidUsr = this._myLid ? String(this._myLid).split('@')[0].split(':')[0] : null;
+    if ((ownPhone && bare === ownPhone) || (ownLidUsr && bare === ownLidUsr)) return false;
+
+    const live = entry =>
+      !!(entry && entry.token && entry.token.length && !tcTokenExpired(entry.timestamp));
+
+    if (live(store.get(tcJid))) return true;
+    if (!store.shouldIssue(tcJid)) return false;
+
+    // A second send to the same contact must wait on the first one's answer
+    // rather than issue a competing IQ for the same JID.
+    let pending = this._tcTokenIssuanceWaiters.get(tcJid);
+    if (!pending) {
+      const issueTs  = Math.floor(Date.now() / 1000);
+      const issueJid = this._resolveTcTokenIssuanceJid(routingToJid);
+      _whaDbg('[DBG] TCTOKEN_PRESEND issuing for ' + tcJid + ' (as ' + issueJid + ')');
+      pending = this._issuePrivacyTokens(issueJid, issueTs)
+        .then(result => { this._storeTcTokenFromIqResult(result, tcJid, issueTs); })
+        .catch(err => {
+          _whaDbg('[DBG] TCTOKEN_PRESEND_ERR jid=' + tcJid + ' err=' + (err && err.message));
+        })
+        .finally(() => { this._tcTokenIssuanceWaiters.delete(tcJid); });
+      this._tcTokenIssuanceWaiters.set(tcJid, pending);
+    }
+
+    // Bounded wait. A send is never failed or delayed indefinitely over a token:
+    // past the deadline it goes out without one, the issuance carries on in the
+    // background, and the next message to this contact picks the token up.
+    const limit = this._tcTokenPresendTimeoutMs;
+    if (limit <= 0) return false;
+
+    let timer = null;
+    const deadline = new Promise(resolve => {
+      timer = setTimeout(() => resolve(false), limit);
+    });
+    const finished = await Promise.race([pending.then(() => true), deadline]);
+    if (timer) clearTimeout(timer);
+
+    if (!finished) {
+      _whaDbg('[DBG] TCTOKEN_PRESEND timed out after ' + limit + 'ms jid=' + tcJid +
+        ' — sending without a token');
+      return false;
+    }
+
+    const ok = live(store.get(tcJid));
+    _whaDbg('[DBG] TCTOKEN_PRESEND ' + (ok ? 'ready' : 'no bytes returned') + ' jid=' + tcJid);
+    return ok;
+  }
+
   /**
    * Parse the IQ result from `_issuePrivacyTokens` and persist the token.
    *

package/lib/messages/MessageSender.js

@@ -1097,6 +1097,28 @@ class MessageSender {
     // filed when it arrived. Looking it up by the phone JID — which is what
     // this did — never found one, so nothing was ever attached.
     const tcJid   = this._client._resolveTcTokenJid(routingToJid);
+
+    // A protocol message — a revoke, an ephemeral-timer change — is bookkeeping
+    // rather than a reach-out, so it never triggers an issuance. An existing
+    // token still rides along on it, which is what the apps do.
+    const isProtocolMsg = !!(options && options._protocol);
+
+    // First message to this contact: fetch the token now, before the stanza is
+    // built, so it goes out on this message instead of on the next one.
+    //
+    // The device enumeration above has already run, so the LID is known by the
+    // time we get here and the issuance and the storage agree on the contact.
+    // Doing this any earlier would issue against the phone JID while the token
+    // got filed under the LID, which is the split that used to leave live
+    // tokens unused.
+    //
+    // Returns without waiting when a live token is already on file, so this
+    // costs one round-trip per contact rather than one per message. It never
+    // throws and never fails the send.
+    if (tcStore && !isProtocolMsg) {
+      await this._client.ensureTcTokenBeforeSend(tcJid, routingToJid);
+    }
+
     if (tcStore) {
       const tcEntry = tcStore.get(tcJid);
       if (tcEntry && tcEntry.token && tcEntry.token.length) {
@@ -1153,11 +1175,16 @@ class MessageSender {
       }
     }
 
-    // ─── Fire-and-forget: issue privacy token to contact ─────────────────────
-    // After each DM send we ask WhatsApp to issue us a trusted-contact token
-    // for this JID (one issuance per 7-day bucket is enough).  The token is
-    // stored and attached on future sends so the server does not count them
-    // as anonymous "reaching out" events (which would trigger error 463).
+    // ─── Fire-and-forget: renew the privacy token ────────────────────────────
+    // The first message to a contact now gets its token before the stanza is
+    // built, up above, so what is left here is renewal: a contact whose token
+    // is still live but whose 7-day bucket has rolled over. That case must not
+    // hold a message up — the token being attached right now is perfectly
+    // valid — so it stays fire-and-forget.
+    //
+    // The gate below is what keeps the two from firing twice for one contact.
+    // A successful pre-send issuance saves senderTimestamp, which puts
+    // shouldIssue in the current bucket and makes this a no-op.
     //
     // Two targets never get one. WhatsApp's own announcement account
     // (0@s.whatsapp.net) and the bot numbers, including Meta AI, are not
@@ -1166,7 +1193,6 @@ class MessageSender {
     // too — they are bookkeeping, not a reach-out. Attaching an existing token
     // to them is still correct
     // and still happens above — this only governs asking for a new one.
-    const isProtocolMsg = !!(options && options._protocol);
     if (tcStore && isRegularTcTokenUser(tcJid) && !isProtocolMsg &&
         tcStore.shouldIssue(tcJid) &&
         !this._client._inFlightTcTokenIssuance.has(tcJid)) {

package/package.json

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