whalibmob 5.16.0 → 5.18.0

package/README.md

@@ -9,6 +9,8 @@
 
 CONTACT ME ON TELEGRAM  IF YOU WANT TO WORK WITH ME AND IF YOU HAVE PROBLEM WITH WHALIBMOB : @brtyu545
 
+**Need test numbers to try whalibmob with?** Message me on Telegram at **@brtyu545** — I can provide phone numbers for receiving SMS verification codes, so you can register and test whalibmob without using your own number.
+
 If you want News about whalibmob enter this whalibmob channel: https://t.me/+sHN4MDCyB7U5OWY0
 
 
@@ -2005,6 +2007,7 @@ 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. |
 | `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. |
@@ -2571,6 +2574,60 @@ of a pile by prefix.
 > is moved unless you ask — `wa migrate-sessions` does that, one number or all
 > of them, and re-running it is safe.
 
+### Keeping the Announced Version Current
+
+Every connection announces the WhatsApp build it claims to be. The server checks
+it, and when it stops recognising the number it refuses the handshake with
+`405` — a failure that says nothing about the version and has nothing to do with
+the account.
+
+A session records the version it registered with. Left alone it announces that
+same number forever, so a number registered in spring is still claiming a spring
+build in autumn, and one day the connect simply stops working.
+
+**iOS sessions now refresh themselves.** On every `init()` the client asks the
+App Store what the current build is and writes it into `<phone>.json` before the
+handshake. Nothing to run, nothing to remember:
+
+```js
+client.on('version_update', ({ from, to }) => {
+  console.log('announcing', to, 'instead of', from)
+})
+
+await client.init('40756469325')
+```
+
+Three rules keep this from being the thing that breaks a working session:
+
+- **It never goes backwards.** The App Store lookup answers with a pinned
+  fallback rather than failing when it cannot reach the network, and that
+  fallback can easily be older than what the session holds. Moving a session to
+  an older version is the one outcome that makes a `405` *more* likely.
+- **`WA_VERSION` still wins.** A version pinned on the way out of a `405` is a
+  decision, and is never quietly replaced.
+- **A failed lookup changes nothing.** The session keeps the version it has and
+  the connect carries on.
+
+Set `{ refreshVersion: false }` on the client to turn it off.
+
+> [!NOTE]
+> **Android is deliberately left alone.** Its version comes out of the APK the
+> token material was read from, and the two have to agree — the registration
+> token is computed from that build. Refreshing the announced version behind the
+> caller's back would put it out of step with the token. Android keeps the
+> explicit flow: `wa apk-material --download`, then `wa refresh-version`.
+
+The manual tool still works on both platforms, and is the only way to move an
+Android session:
+
+```bash
+wa refresh-version 40756469325                    # current build for the platform
+wa refresh-version 40756469325 --version 2.25.1.2 # or one you name
+```
+
+Companion sessions have never had this problem: `connectWeb()` reads the live
+web revision on every connect already.
+
 ### One-time Pre-keys
 
 A pre-key is a one-shot Diffie-Hellman key the account leaves with the server so

package/lib/Client.js

@@ -379,6 +379,13 @@ class WhalibmobClient extends EventEmitter {
     // automatically on the first refused login. Set { autoFixNumber: false } to
     // be told about it instead.
     this._autoFixNumber  = opts.autoFixNumber !== false;
+    // An iOS session checks the App Store for the current build on every
+    // connect and writes it back — see _refreshIosVersion(). Set
+    // { refreshVersion: false } to keep announcing whatever the session
+    // registered with. Android is not affected either way: its version comes
+    // out of the APK the token material was read from, and that stays a
+    // deliberate step.
+    this._refreshVersion = opts.refreshVersion !== false;
     this._numberFixAttempted = false;
     this._pingTimer               = null;
     this._keepTimer               = null;
@@ -497,6 +504,67 @@ class WhalibmobClient extends EventEmitter {
     return this.init(phoneNumber);
   }
 
+  /**
+   * Bring an iOS session's announced version up to date, on every connect.
+   *
+   * A session records the version it registered with and announces that
+   * forever after. Months later the server stops accepting it and the connect
+   * is refused with a 405 that says nothing about why — and the only remaining
+   * move, before this, was to run `wa refresh-version` by hand or register the
+   * number again. The companion path never had that problem because
+   * connectWeb() reads the live revision every time; this is the same idea for
+   * the primary one.
+   *
+   * iOS only, and deliberately so. Android's version comes out of the APK the
+   * token material was read from — the two have to agree, because the token is
+   * computed from that build — so refreshing it behind the caller's back would
+   * put the announced version and the token out of step. Android keeps its
+   * Play Store flow exactly as it was.
+   *
+   * Three rules keep this from being the thing that breaks a working session:
+   *
+   *   • It never goes backwards. fetchIosVersion() answers with the pinned
+   *     fallback rather than failing when the lookup does not work, and that
+   *     fallback can easily be older than what a session already holds. Moving
+   *     a session to an older version is the one outcome that makes a 405 more
+   *     likely rather than less.
+   *   • WA_VERSION still wins. Someone who has pinned a version on the way out
+   *     of a 405 must not have it quietly replaced.
+   *   • It never throws, and it never blocks for long. A lookup that fails
+   *     leaves the session exactly as it was and the connect carries on.
+   */
+  async _refreshIosVersion() {
+    if (!this._refreshVersion || this._mode === 'web' || !this._store) return;
+    if (process.env.WA_VERSION) {
+      _whaDbg('[DBG] VERSION refresh skipped — WA_VERSION is set');
+      return;
+    }
+
+    const device = this._store.device || getDeviceConfig();
+    if (device.os === 'android') return;   // the APK flow owns this
+
+    try {
+      const { compareVersions } = require('./Registration');
+      const before = this._store.version;
+      const live   = await fetchIosVersion(!!device.business);
+      if (!live) return;
+
+      if (before && compareVersions(live, before) <= 0) {
+        _whaDbg('[DBG] VERSION already current (' + before + ', App Store says ' + live + ')');
+        return;
+      }
+
+      this._store.version = live;
+      this._persistStore();
+      _whaDbg('[DBG] VERSION refreshed ' + (before || 'none') + ' → ' + live +
+        ' (App Store listing)');
+      this.emit('version_update', { from: before || null, to: live, source: 'App Store listing' });
+    } catch (err) {
+      // A session that cannot ask keeps the version it has.
+      _whaDbg('[DBG] VERSION refresh failed: ' + (err && err.message));
+    }
+  }
+
   async init(phoneNumber) {
     phoneNumber = String(phoneNumber).replace(/\D/g, '');
     this._phoneNumber = phoneNumber;
@@ -526,6 +594,10 @@ class WhalibmobClient extends EventEmitter {
       );
     }
 
+    // Before the handshake, which reads the version straight out of the store.
+    // iOS only; Android keeps its APK flow. See _refreshIosVersion().
+    await this._refreshIosVersion();
+
     const signalFile  = path.join(this._sessionDir, `${phoneNumber}.signal.json`);
     const skFile      = path.join(this._sessionDir, `${phoneNumber}.sk.json`);
     const tcTokenFile = path.join(this._sessionDir, `${phoneNumber}.tctoken.json`);
@@ -3361,6 +3433,19 @@ class WhalibmobClient extends EventEmitter {
       const isLid     = fromJid.endsWith('@lid');
       const mappedPn  = isLid && this._lidToPn ? this._lidToPn.get(fromUser) : null;
       const fromPhone = isLid ? mappedPn : fromUser;
+      // Before throwing the cache away: the notification says what changed and
+      // carries the hash of the list it should produce. Apply it, check the
+      // hash, and if it matches there is nothing to invalidate and nothing to
+      // ask usync about — see DeviceManager.verifyDeviceDelta().
+      if (fromPhone && this._devMgr) {
+        const delta = this._parseDeviceDelta(node);
+        if (delta && this._devMgr.verifyDeviceDelta(fromPhone, delta.changes, delta.hash)) {
+          _whaDbg('[DBG] NOTIF_DEVICES delta verified for ' + fromPhone +
+            ' — cache kept, no usync needed');
+          return;
+        }
+      }
+
       if (fromUser && this._devMgr) {
         this._devMgr._dcDel(isLid ? [fromUser, 'lid:' + fromUser] : [fromUser]);
         if (mappedPn) this._devMgr._dcDel([mappedPn]);
@@ -3412,6 +3497,54 @@ class WhalibmobClient extends EventEmitter {
     }
   }
 
+  /**
+   * Read a `devices` notification as a change plus the hash it should produce.
+   *
+   *   <notification type="devices" from="…">
+   *     <add device_hash="2:…"><device jid="40711111111:3@s.whatsapp.net"/></add>
+   *   </notification>
+   *
+   * Children are `add`, `remove`, or `update`. Only the first two say something
+   * that can be applied; `update` does not name what it changed, so it is
+   * treated as unreadable here and the caller falls back to invalidating.
+   *
+   * All children must agree on the hash — the server sends one per child, and a
+   * notification carrying two different ones is describing intermediate states
+   * this cannot reconstruct.
+   *
+   * @returns {{changes: Array<{tag, deviceId}>, hash: string}|null}
+   */
+  _parseDeviceDelta(node) {
+    if (!node || !Array.isArray(node.content)) return null;
+
+    const changes = [];
+    let hash = null;
+
+    for (const child of node.content) {
+      if (!child || !child.description) continue;
+      const tag = child.description;
+      if (tag !== 'add' && tag !== 'remove') return null;   // 'update' and friends
+
+      const childHash = child.attrs && child.attrs.device_hash;
+      if (!childHash) return null;
+      if (hash === null) hash = String(childHash);
+      else if (hash !== String(childHash)) return null;     // disagreeing children
+
+      const deviceNode = findChild(child, 'device');
+      const jid = deviceNode && deviceNode.attrs && deviceNode.attrs.jid;
+      if (!jid) return null;
+
+      const raw    = String(jid).split('@')[0];
+      const colon  = raw.indexOf(':');
+      const device = colon >= 0 ? parseInt(raw.slice(colon + 1), 10) : 0;
+      if (!Number.isFinite(device)) return null;
+
+      changes.push({ tag, deviceId: device });
+    }
+
+    return changes.length && hash ? { changes, hash } : null;
+  }
+
   _processDeviceUpdate(devicesNode) {
     // Called from _handleNotification(type='account_sync') and type='devices'.
     // Rebuilds the device cache for the affected phones from the server-provided list.

package/lib/DeviceManager.js

@@ -1178,6 +1178,78 @@ class DeviceManager {
   }
 
   // ─── Invalidate cached device list (used on phash mismatch / 421 retry) ───
+  /**
+   * Apply a device-list change and check the result against the server's own
+   * hash of what the list should now be.
+   *
+   * A `devices` notification says what changed — one device added, one removed —
+   * and carries `device_hash`, the participant hash of the list the server
+   * believes we should end up with. That hash is the thing worth having: it
+   * turns "I applied the change, probably correctly" into something checkable.
+   *
+   * So the change is applied to the cached list, the hash of the result is
+   * computed, and the two are compared. Equal, and the cache is provably right
+   * and is kept. Different, and the cache is wrong in some way this side cannot
+   * see, so it is thrown away and the next send asks usync for the whole list.
+   *
+   * That second branch is exactly what this did for every notification before —
+   * drop everything, ask again. Which is safe, and costs a round trip each time
+   * somebody opens WhatsApp Web. This keeps the cache when it can prove it is
+   * right, and falls back to the old behaviour when it cannot.
+   *
+   * Safe by construction: if this hash were computed differently from the
+   * server's, nothing would ever match and every notification would take the
+   * fallback — which is where it started.
+   *
+   * @param   {string} phone        digits, the cache key
+   * @param   {Array<{tag: string, deviceId: number}>} changes
+   * @param   {string} serverHash   the notification's device_hash
+   * @returns {boolean} whether the result verified and the cache was kept
+   */
+  verifyDeviceDelta(phone, changes, serverHash) {
+    if (!phone || !serverHash || !Array.isArray(changes) || !changes.length) return false;
+
+    // No baseline means there is nothing to apply a change to. Caching just the
+    // one device named in the notification would make a list of one look
+    // authoritative, which is how a recipient's other devices stop being
+    // written to.
+    const cached = this._dcGet(phone);
+    if (!cached || !cached.length) return false;
+
+    const next = new Set(cached);
+    for (const { tag, deviceId } of changes) {
+      if (!Number.isFinite(deviceId)) return false;
+      if (tag === 'add')         next.add(deviceId);
+      else if (tag === 'remove') next.delete(deviceId);
+      else return false;   // 'update' and anything unknown: do not guess
+    }
+
+    const ids  = [...next].sort((a, b) => a - b);
+    const jids = ids.map(d => makeDeviceJid(phone, d));
+
+    let ours;
+    try {
+      // Lazily required: MessageSender requires this file, so taking it at the
+      // top would close the cycle before either module finishes loading.
+      const { computePhash } = require('./messages/MessageSender');
+      ours = computePhash(jids);
+    } catch (_) {
+      return false;
+    }
+
+    if (ours !== String(serverHash)) {
+      _whaDbg('[DBG] DEV_HASH mismatch for ' + phone + ' ours=' + ours +
+        ' server=' + serverHash + ' — dropping cache');
+      this._dcDel([phone]);
+      return false;
+    }
+
+    this._dcSet(phone, ids);
+    _whaDbg('[DBG] DEV_HASH verified for ' + phone + ' ids=[' + ids.join(',') +
+      '] hash=' + ours);
+    return true;
+  }
+
   clearCache(phones) {
     if (!phones || phones.length === 0) {
       this._dcFlush();
@@ -1187,10 +1259,13 @@ class DeviceManager {
   }
 
   // ─── Build participants node ───────────────────────────────────────────────
-  static buildParticipantsNode(encryptedList, mediaSubtype) {
+  static buildParticipantsNode(encryptedList, mediaSubtype, decryptFail) {
     const toNodes = encryptedList.map(({ jid, type, ciphertext }) => {
       const encAttrs = { type, v: '2' };
       if (mediaSubtype) encAttrs.mediatype = mediaSubtype;
+      // What the recipient shows if this payload will not decrypt — see
+      // resolveDecryptFail() in MessageSender.
+      if (decryptFail) encAttrs['decrypt-fail'] = decryptFail;
       // Always encode the jid as a binary JID object (JID_PAIR / AD_JID) so the
       // server can route the per-device enc payload to the correct Signal session.
       // Raw UTF-8 strings are silently dropped for @lid recipients.

package/lib/Registration.js

@@ -2137,7 +2137,7 @@ async function verifyCode(store, code, opts) {
   throw new Error(`Verification failed: ${reason || JSON.stringify(result)}`);
 }
 
-module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, currentVersionFor, refreshSessionVersion, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
+module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, currentVersionFor, refreshSessionVersion, compareVersions, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
 
 // The HTTP reader, exposed for tests. Not part of the public API.
 module.exports._http = { readHttpResponse, parseHttpResponse, decodeChunkedBody };

package/lib/messages/MessageSender.js

@@ -124,6 +124,35 @@ function _getCurve() {
 // Build ADVSignedDeviceIdentity for our primary iOS device.
 // Returns Buffer of encoded proto WITH accountSignatureKey included.
 // Result is cached in store.advIdentity so we only build it once per registration.
+// What the recipient's client should do when one of our payloads will not
+// decrypt for them.
+//
+// The attribute rides on the <enc> node and is read on the other side, not by
+// the server. Absent, a failure draws the "Waiting for this message" placeholder
+// in their chat. `hide` draws nothing at all.
+//
+// That placeholder is right for a real message — the person can see something
+// arrived and ask for it again. It is nonsense for the three kinds below, which
+// are invisible operations on a message that is already there: a reaction that
+// will not decrypt is a heart that never appears, not a message to wait for, and
+// a failed revoke or edit would leave a ghost bubble referring to nothing.
+//
+// The rule is the reference clients' rule, narrowed to what this library sends:
+//
+//   reaction   sendReaction()                   → stanza type 'reaction'
+//   edit       editMessage()                    → edit bit '1'
+//   revoke     deleteMessage(forEveryone: true) → edit bit '7' or '8'
+//
+// Everything else gets nothing, which is the same as saying "show it".
+function resolveDecryptFail(mediaType, options) {
+  if (mediaType === 'reaction') return 'hide';
+  // Any edit bit: 1 is an edit, 7 and 8 are the two revoke forms. The reference
+  // client keys off the presence of the attribute rather than its value, and so
+  // does this.
+  if (options && options.edit) return 'hide';
+  return null;
+}
+
 function _buildOrGetAdvIdentity(store) {
   // Only ever return an identity the server actually issued.
   //
@@ -909,6 +938,7 @@ class MessageSender {
     const ownPhone       = String(this._store.phoneNumber);
     const ownMainJid     = `${ownPhone}@s.whatsapp.net`;
     const mediaSubtype   = options._mediaSubtype || null;
+    const decryptFail    = resolveDecryptFail(mediaType, options);
 
     // For primary iOS devices (registered via SMS), advIdentity is never set
     // because the server only sends device-identity for linked secondary devices.
@@ -1040,7 +1070,8 @@ class MessageSender {
       // Always use <participants><to jid=...><enc> structure — required by MD protocol.
       // Old iOS non-MD used direct <enc> in <message>, but the WhatsApp server now
       // enforces the MD participants wrapper even for single-device sends.
-      const participantsNode = DeviceManager.buildParticipantsNode(encryptedList, mediaSubtype);
+      const participantsNode = DeviceManager.buildParticipantsNode(
+        encryptedList, mediaSubtype, decryptFail);
       msgContent = [...devIdNodes, participantsNode];
     }
 
@@ -1159,6 +1190,7 @@ class MessageSender {
     const ownPhone     = String(this._store.phoneNumber);
     const ownJid       = `${ownPhone}@s.whatsapp.net`;
     const mediaSubtype = options._mediaSubtype || null;
+    const decryptFail  = resolveDecryptFail(mediaType, options);
 
     const isStatus = isStatusBroadcast(groupJid);
 
@@ -1405,10 +1437,17 @@ class MessageSender {
       // participant nodes as on the skmsg, so an image sent to a group carries
       // mediatype on both. Passing null here left the SKDM <enc> nodes
       // unlabelled.
-      msgContent.push(DeviceManager.buildParticipantsNode(skdmEncrypted, mediaSubtype));
+      msgContent.push(DeviceManager.buildParticipantsNode(
+        skdmEncrypted, mediaSubtype, decryptFail));
     }
     const skmsgAttrs = { type: 'skmsg', v: '2' };
     if (mediaSubtype) skmsgAttrs.mediatype = mediaSubtype;
+    // On the skmsg too, and that is where it matters most in a group: the
+    // participant nodes carry the sender-key distribution, but the reaction
+    // itself travels in here. The two reference clients disagree — one sets it
+    // on both, the other only on the participant nodes — and the one that sets
+    // both is the one whose reasoning holds up.
+    if (decryptFail) skmsgAttrs['decrypt-fail'] = decryptFail;
     msgContent.push(new BinaryNode('enc', skmsgAttrs, Buffer.isBuffer(skmsgCiphertext) ? skmsgCiphertext : Buffer.from(skmsgCiphertext)));
 
     // Same reporting token a direct message carries. A poll posted to a group

package/package.json

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