whalibmob 5.18.0 → 5.19.1

package/README.md

@@ -1788,9 +1788,9 @@ This runs by itself on a registration that finds no material. To do it separatel
 wa apk-material --download
 ```
 
-It is the route Cobalt takes: an anonymous Play Store token from the Aurora OSS
-dispenser, then Google's own `/fdfe` catalogue and delivery endpoints, then the
-signed CDN URLs. **No Google account of yours is involved.** Only the density
+The route is an anonymous Play Store token from the Aurora OSS dispenser, then
+Google's own `/fdfe` catalogue and delivery endpoints, then the signed CDN URLs.
+**No Google account of yours is involved.** Only the density
 splits are downloaded — the token's key comes from `about_logo.png`, which lives
 in one of those, and the architecture and language splits would be a hundred
 megabytes nothing here reads.
@@ -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({
@@ -2322,6 +2323,8 @@ Every event from the SMS primary API fires here too — `message`, `receipt`, `p
 | `history_sync` | `{ syncTypeName, chats, contacts, pushNames, merged }` | a chunk of history arrived |
 | `history_sync_error` | `{ err, notification }` | a chunk could not be fetched or decrypted |
 | `client_rejected` | `{ reason, location, message }` | the server refused the client itself, not the session — `405` means the announced version is not accepted. Fires whether the refusal arrives during the handshake or once the stream is open, and the client stops retrying either way. Distinct from `auth_failure`, and there is nothing to re-pair. |
+| `version_update` | `{ from, to, source }` | the announced version was refreshed from the platform's store before a handshake. Fires on reconnects as well as the first connect |
+| `apk_material_stale` | `{ materialVersion, liveVersion, hint }` | Android only: the Play Store listing has moved past the APK the cached token material came from. Nothing is broken — registration is what reads that material — but the next number registered from this install would go out under an older build |
 
 ### Reading What the Phone Sent
 
@@ -2585,40 +2588,53 @@ 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:
+**Sessions refresh themselves, on both platforms.** Before every handshake the
+client asks the platform's store what the current build is and writes it into
+`<phone>.json`. iOS reads the App Store listing, Android the Play Store one.
+Nothing to run, nothing to remember:
 
 ```js
-client.on('version_update', ({ from, to }) => {
-  console.log('announcing', to, 'instead of', from)
+client.on('version_update', ({ from, to, source }) => {
+  console.log('announcing', to, 'instead of', from, '—', source)
 })
 
 await client.init('40756469325')
 ```
 
-Three rules keep this from being the thing that breaks a working session:
+**Reconnects are covered too.** The check runs from the socket-connect step
+rather than from `init()`, so the library's own reconnect loop passes through it
+as well. A bot that stays up for weeks does not go on announcing whatever the
+listing said the morning it started. The handshake reads the version out of the
+store at the moment it runs, so a version written here is the one that goes out.
 
-- **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.
+Four rules keep this from being the thing that breaks a working session:
+
+- **It never goes backwards.** Both lookups answer with a pinned fallback rather
+  than failing when they 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.
+- **The network is not asked twice for the same answer.** Each lookup is
+  memoised for six hours, so a connection that flaps every few seconds reaches
+  the store once rather than once per attempt — and a session up for a month
+  still picks up a release the day it lands.
 
 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`.
+> **Registration still reads the APK.** A number being registered announces the
+> `versionName` of the APK its token material came from, because the Android
+> registration token is signed over that build. Only the *announced* version on
+> an already-registered session follows the Play Store listing — no token
+> travels in the handshake, so there is nothing there for it to fall out of step
+> with. When the listing moves past the cached material the client emits
+> `apk_material_stale`, which is the cue to run `wa apk-material --download`
+> before registering the next number.
 
-The manual tool still works on both platforms, and is the only way to move an
-Android session:
+The manual tool still works on both platforms:
 
 ```bash
 wa refresh-version 40756469325                    # current build for the platform
@@ -3263,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. |
@@ -4867,7 +4884,7 @@ come from:
 | order | where the announced version comes from |
 |---|---|
 | 1 | `WA_VERSION`, from the shell **or from a `.env` file in the directory the command runs in** |
-| 2 | the version stored in the session file — what the number was registered with |
+| 2 | the version stored in the session file — refreshed from the platform's store before every handshake, unless `{ refreshVersion: false }` |
 
 Almost every 405 is the first line winning when nobody meant it to.
 

package/lib/AndroidApk.js

@@ -9,8 +9,7 @@
 // put in WA_STATIC_TOKEN can stand in for it. Sending the iOS-shaped token as
 // Android is answered with {"reason":"bad_token"}.
 //
-// What the native client actually computes, and what this file reproduces from
-// Cobalt's WhatsAppAndroidClientInfo:
+// What the native client actually computes, and what this file reproduces:
 //
 //   key   = PBKDF2-HMAC-SHA1(password = packageName || about_logo.png,
 //                            salt = ANDROID_SALT, iterations = 128, dkLen = 64)
@@ -27,7 +26,7 @@ const crypto = require('crypto');
 const zlib   = require('zlib');
 
 // Reverse engineered from the Android binary and identical for the consumer and
-// business builds. Cobalt notes it has been stable across many releases.
+// business builds, and has been stable across many releases.
 const ANDROID_SALT = Buffer.from(
   'PkTwKSZqUfAUyR0rPQ8hYJ0wNsQQ3dW1+3SCnyTXIfEAxxS75FwkDf47wNv/c8pP' +
   '3p0GXKR6OOQmhyERwx74fw1RYSU10I4r1gyBVDbRJ40pidjM41G1I1oN', 'base64');
@@ -124,7 +123,7 @@ function readZipEntry(buf, entries, name) {
 // ─── DER / PKCS#7 ─────────────────────────────────────────────────────────────
 //
 // The signing certificates come out of the v1 (JAR) signature block, which is
-// what Cobalt reads — apk-parser's getApkSingers() is the v1 signer list. Only
+// what the token derivation needs — the v1 signer list. Only
 // enough DER is parsed to walk into SignedData and lift each certificate out
 // whole; nothing here validates a signature.
 
@@ -174,7 +173,7 @@ function certificatesFromPkcs7(der) {
 //
 // The manifest inside an APK is Android's binary XML, not text. Three things are
 // read out of it — the package name, the version name and the version code —
-// the same three Cobalt takes from its parsed manifest. The version name is the
+// all three off the parsed manifest. The version name is the
 // one that matters most: the token is signed over this APK's classes.dex, so the
 // version announced to the server has to be this APK's, not whatever the Play
 // Store currently lists.
@@ -268,8 +267,8 @@ function parseManifest(buf) {
 }
 
 // A split's own name, as Android files it: "config.xxhdpi" out of
-// "base-config.xxhdpi.apk" or "split_config.xxhdpi.apk". Cobalt only searches
-// splits whose name ends in "dpi", which is the density-qualified set.
+// "base-config.xxhdpi.apk" or "split_config.xxhdpi.apk". Only splits whose name
+// ends in "dpi" are searched, which is the density-qualified set.
 function _isDensitySplit(fileName) {
   const base = String(fileName).replace(/\.apk$/i, '');
   return /dpi$/i.test(base);
@@ -295,8 +294,8 @@ function extractMaterial(base, splits) {
   // — and its bytes are the PBKDF2 password, so picking a different density
   // yields a different key and a token the server will not accept. Searching
   // split by split makes the answer depend on the order the splits happen to be
-  // passed in, which for a shell glob is alphabetical and for Cobalt is whatever
-  // its download map iterated: same APK, different token.
+  // passed in, which for a shell glob is alphabetical and for a download map is
+  // whatever it iterated: same APK, different token.
   //
   // So the path decides, not the split. ABOUT_LOGO_PATHS is ordered — hdpi
   // first, the xxhdpi fallback last — and every candidate is searched for the
@@ -355,9 +354,8 @@ function extractMaterial(base, splits) {
 
 // PBKDF2-HMAC-SHA1 over the package name followed by the raw PNG bytes.
 //
-// Cobalt runs the derivation by hand because the JCA factory rejects a binary
-// password; the loop it runs is standard PBKDF2, so this calls the platform's.
-// The two are checked against each other in the token test.
+// A JCA factory rejects a binary password, so a hand-rolled loop is the usual
+// route on the JVM; that loop is standard PBKDF2, so this calls the platform's.
 function deriveSecretKey(packageName, aboutLogo) {
   const password = Buffer.concat([Buffer.from(packageName, 'utf8'), aboutLogo]);
   return crypto.pbkdf2Sync(password, ANDROID_SALT, PBKDF2_ITERATIONS, PBKDF2_KEY_SIZE, 'sha1');
@@ -415,8 +413,7 @@ function looksLikeWhatsAppCertificate(description) {
 
 // ─── Storage ──────────────────────────────────────────────────────────────────
 //
-// Only the derived pieces are kept, the way Cobalt caches them — the APK itself
-// is never needed again.
+// Only the derived pieces are kept — the APK itself is never needed again.
 
 function materialToJson(material) {
   return {

package/lib/Attestation.js

@@ -4,10 +4,9 @@
 //
 // Talks to the on-device Frida attestation server shipped in ./frida (Android
 // Play Integrity / Keystore attestation, iOS App Attest) and folds its output
-// into the registration request, mirroring how Auties00/cobalt consumes the
-// same scripts.
+// into the registration request.
 //
-// Design (matches Cobalt's LinkedWhatsAppClientDeviceAttestor):
+// Design:
 //   • Two data shapes are produced —
 //       Android: { gpia, gg, gi, gp, ge, ga }  (Play Integrity legs)
 //       iOS:     { attestation, assertion, keyId }  (App Attest)
@@ -155,7 +154,7 @@ async function iosAppAttest(noisePubB64, device) {
 
 // ─── High-level: attestation fields shipped on every attested endpoint ────────
 //
-// Returns the alternating name/value pairs Cobalt ships via attestationFields():
+// Returns the alternating name/value pairs the attested endpoints expect:
 //   Android → gpia,_gg,_gi,_gp,_ge,_ga,push_token
 //   iOS     → push_token
 //

package/lib/Client.js

@@ -9,7 +9,7 @@ const crypto        = require('crypto');
 const { Mutex }     = require('async-mutex');
 const { NoiseSocket }     = require('./noise');
 const { MessageSender, generateMessageId, makeJid, buildOrGetAdvIdentity } = require('./messages/MessageSender');
-const { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, assertRegistrationKeys, fetchIosVersion, fetchWaVersion } = require('./Registration');
+const { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, assertRegistrationKeys, fetchIosVersion, fetchAndroidVersion, fetchWaVersion } = require('./Registration');
 const { defaultBaseDir, sessionDirFor, isLegacyLayout,
         preKeyFilesFor, SESSION_SUFFIXES } = require('./SessionPaths');
 const { getDeviceConfig } = require('./DeviceConfig');
@@ -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.
@@ -379,12 +385,11 @@ 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.
+    // A session checks its platform's store for the current build before every
+    // handshake and writes it back — see _refreshAnnouncedVersion(). iOS reads
+    // the App Store listing, Android the Play Store one, and reconnects are
+    // covered as well as the first connect. Set { refreshVersion: false } to
+    // keep announcing whatever the session registered with.
     this._refreshVersion = opts.refreshVersion !== false;
     this._numberFixAttempted = false;
     this._pingTimer               = null;
@@ -465,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;
@@ -505,7 +519,7 @@ class WhalibmobClient extends EventEmitter {
   }
 
   /**
-   * Bring an iOS session's announced version up to date, on every connect.
+   * Bring a session's announced version up to date, before every handshake.
    *
    * A session records the version it registered with and announces that
    * forever after. Months later the server stops accepting it and the connect
@@ -515,56 +529,111 @@ class WhalibmobClient extends EventEmitter {
    * 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.
+   * Both platforms, and the version each one asks for is the one that platform
+   * publishes: the App Store listing for iOS, the Play Store listing for
+   * Android.
+   *
+   * Android was left out of this at first, on the grounds that its version has
+   * to match the APK the token material came from. That holds for registering a
+   * number and nowhere else. The Android token is an HMAC over the APK's
+   * signing certificates, the digest of its classes.dex and the national
+   * number — the version string is not in it — and no token of any kind travels
+   * in the handshake, which carries the version, the username and the device
+   * properties. So there is nothing here for a refreshed version to fall out of
+   * step with. Registration keeps reading the APK's own version through
+   * fetchWaVersion(), so a number being registered still announces the build
+   * its token was computed from.
+   *
+   * Called from _connectSocket() rather than init(), so it covers the
+   * library's own reconnects too. The handshake reads store.version at the
+   * moment it runs, so a version written here is the one that goes out.
    *
    * 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.
+   *   • It never goes backwards. Both lookups answer with a pinned fallback
+   *     rather than failing, 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.
+   *     leaves the session exactly as it was and the connect carries on. The
+   *     lookups memoise for six hours, so a connection that flaps every few
+   *     seconds reaches the network once, not once per attempt.
    */
-  async _refreshIosVersion() {
+  async _refreshAnnouncedVersion() {
     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
+    const device   = this._store.device || getDeviceConfig();
+    const business = !!device.business;
+    const android  = device.os === 'android';
+    const source   = android ? 'Play Store listing' : 'App Store listing';
 
     try {
       const { compareVersions } = require('./Registration');
       const before = this._store.version;
-      const live   = await fetchIosVersion(!!device.business);
+      const live   = android
+        ? await fetchAndroidVersion(business)
+        : await fetchIosVersion(business);
       if (!live) return;
 
       if (before && compareVersions(live, before) <= 0) {
-        _whaDbg('[DBG] VERSION already current (' + before + ', App Store says ' + live + ')');
+        _whaDbg('[DBG] VERSION already current (' + before + ', ' + source +
+          ' 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' });
+        ' (' + source + ')');
+      this.emit('version_update', { from: before || null, to: live, source });
+
+      // On Android the token material carries the version of the APK it was
+      // read from. Once the listing has moved past it, that material is from an
+      // older build — which matters for registering a number, not for this
+      // connection. Say so rather than fetching an APK on the connect path.
+      if (android) this._warnIfApkMaterialStale(device, live);
     } catch (err) {
       // A session that cannot ask keeps the version it has.
       _whaDbg('[DBG] VERSION refresh failed: ' + (err && err.message));
     }
   }
 
+  /**
+   * Note that the cached APK material predates the build Play is serving.
+   *
+   * Only registration reads that material, so nothing is broken here and
+   * nothing is downloaded. It is said once per connection so that a number
+   * registered from this install goes out under a current build if the owner
+   * refreshes the material first.
+   */
+  _warnIfApkMaterialStale(device, liveVersion) {
+    try {
+      const { compareVersions, tryLoadAndroidMaterial } = require('./Registration');
+      if (typeof tryLoadAndroidMaterial !== 'function') return;
+
+      const material   = tryLoadAndroidMaterial(device);
+      const apkVersion = material && material.apkVersion;
+      if (!apkVersion) return;
+      if (compareVersions(liveVersion, apkVersion) <= 0) return;
+
+      _whaDbg('[DBG] APK material is from ' + apkVersion + ', the listing serves ' +
+        liveVersion + ' — run `wa apk-material --download` before registering a number');
+      this.emit('apk_material_stale', {
+        materialVersion: apkVersion,
+        liveVersion,
+        hint: 'wa apk-material --download'
+      });
+    } catch (_) {
+      // Advisory only.
+    }
+  }
+
   async init(phoneNumber) {
     phoneNumber = String(phoneNumber).replace(/\D/g, '');
     this._phoneNumber = phoneNumber;
@@ -594,10 +663,6 @@ 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`);
@@ -702,6 +767,15 @@ class WhalibmobClient extends EventEmitter {
   async _connectSocket() {
     if (this._mode === 'web') return this._connectWebSocket();
 
+    // Before the handshake, which reads the version straight out of the store.
+    //
+    // Here rather than in init() so that the library's own reconnects get it
+    // too: _scheduleReconnect() calls this method directly, and a session that
+    // refreshed only at startup would announce whatever the listing said the
+    // day the process began, however long it then stayed up. The lookups
+    // memoise for six hours, so a flapping connection costs nothing.
+    await this._refreshAnnouncedVersion();
+
     const socket = new NoiseSocket(this._store);
     this._socket = socket;
 
@@ -3433,16 +3507,51 @@ class WhalibmobClient extends EventEmitter {
       const isLid     = fromJid.endsWith('@lid');
       const mappedPn  = isLid && this._lidToPn ? this._lidToPn.get(fromUser) : null;
       const fromPhone = isLid ? mappedPn : fromUser;
+
+      // A contact has two device lists — one under the phone number, one under
+      // the LID — and the notification carries both: `device_hash` for the list
+      // it is addressed under, `device_lid_hash` for the other one, with each
+      // <device> naming its jid and its lid. The server hashes them separately,
+      // so they are checked separately, and one going wrong does not cost the
+      // other. That matters most for the LID half: a LID cache thrown away for
+      // a contact whose number we do not know cannot be refilled by usync,
+      // which only answers questions about phone numbers.
+      const lidAttr = String(attrs.lid || '');
+      const lidUser = isLid ? fromUser
+                    : (lidAttr ? lidAttr.split('@')[0].split(':')[0] : null);
+      // Free mapping, exactly as the notification states it.
+      if (!isLid && lidUser && fromUser) {
+        if (this._lidToPn) this._lidToPn.set(lidUser, fromUser);
+        if (this._pnToLid) this._pnToLid.set(fromUser, lidUser);
+      }
+
       // 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) {
+      if (fromUser && 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 (delta) {
+          // The primary half is keyed the way the notification is addressed.
+          const priKey    = isLid ? 'lid:' + fromUser : fromUser;
+          const priServer = isLid ? 'lid' : 's.whatsapp.net';
+          const priOk     = this._devMgr.verifyDeviceDelta(
+            priKey, fromUser, delta.changes, delta.hash, priServer);
+
+          // The secondary half only exists when the notification arrived under
+          // the number and named the LID alongside it.
+          if (!isLid && lidUser && delta.lidHash && delta.lidChanges) {
+            const lidOk = this._devMgr.verifyDeviceDelta(
+              'lid:' + lidUser, lidUser, delta.lidChanges, delta.lidHash, 'lid');
+            _whaDbg('[DBG] NOTIF_DEVICES lid delta ' +
+              (lidOk ? 'verified' : 'unverified') + ' for lid:' + lidUser);
+          }
+
+          if (priOk) {
+            _whaDbg('[DBG] NOTIF_DEVICES delta verified for ' + priKey +
+              ' — cache kept, no usync needed');
+            return;
+          }
         }
       }
 
@@ -3512,13 +3621,34 @@ class WhalibmobClient extends EventEmitter {
    * notification carrying two different ones is describing intermediate states
    * this cannot reconstruct.
    *
-   * @returns {{changes: Array<{tag, deviceId}>, hash: string}|null}
+   * Each child may also carry `device_lid_hash`, and each `<device>` a `lid`
+   * beside its `jid`, describing the same change to the contact's LID device
+   * list. That half is optional: missing on any child, and only the phone-number
+   * half is returned, which is what the caller then verifies. It is never a
+   * reason to reject the notification outright — the two lists are hashed
+   * independently by the server and are checked independently here.
+   *
+   * @returns {{changes: Array<{tag, deviceId}>, hash: string,
+   *            lidChanges: Array<{tag, deviceId}>|null, lidHash: string|null}|null}
    */
   _parseDeviceDelta(node) {
     if (!node || !Array.isArray(node.content)) return null;
 
-    const changes = [];
-    let hash = null;
+    const changes    = [];
+    const lidChanges = [];
+    let hash    = null;
+    let lidHash = null;
+    let lidOk   = true;   // every child so far carried a usable LID half
+
+    // "user:3@server" / "user@server" → 3 / 0, or null when unreadable.
+    const deviceIdOf = (jid) => {
+      if (!jid) return null;
+      const raw   = String(jid).split('@')[0];
+      const colon = raw.indexOf(':');
+      if (colon < 0) return 0;
+      const device = parseInt(raw.slice(colon + 1), 10);
+      return Number.isFinite(device) ? device : null;
+    };
 
     for (const child of node.content) {
       if (!child || !child.description) continue;
@@ -3531,18 +3661,29 @@ class WhalibmobClient extends EventEmitter {
       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;
-
+      const attrs      = (deviceNode && deviceNode.attrs) || {};
+      const device     = deviceIdOf(attrs.jid);
+      if (device === null) return null;
       changes.push({ tag, deviceId: device });
+
+      // LID half — optional, and giving up on it costs the number half nothing.
+      if (!lidOk) continue;
+      const childLidHash = child.attrs.device_lid_hash;
+      const lidDevice    = deviceIdOf(attrs.lid);
+      if (!childLidHash || lidDevice === null) { lidOk = false; continue; }
+      if (lidHash === null) lidHash = String(childLidHash);
+      else if (lidHash !== String(childLidHash)) { lidOk = false; continue; }
+      lidChanges.push({ tag, deviceId: lidDevice });
     }
 
-    return changes.length && hash ? { changes, hash } : null;
+    if (!changes.length || !hash) return null;
+    const haveLid = lidOk && lidHash && lidChanges.length === changes.length;
+    return {
+      changes,
+      hash,
+      lidChanges: haveLid ? lidChanges : null,
+      lidHash:    haveLid ? lidHash    : null
+    };
   }
 
   _processDeviceUpdate(devicesNode) {
@@ -4639,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.
    *
@@ -5612,10 +5844,9 @@ class WhalibmobClient extends EventEmitter {
 
   // Change bio/about text
   //
-  // The <status> child is byte-for-byte what Baileys and whatsmeow send. The
-  // envelope was not: both of them address this IQ to the server as a *JID*
-  // with nobody in the user part — Baileys writes '@s.whatsapp.net', whatsmeow
-  // uses types.ServerJID — which goes out as JID_PAIR + empty user + the server
+  // The <status> child is the shape the server reads. The envelope was not:
+  // this IQ has to be addressed to the server as a *JID* with nobody in the
+  // user part, which goes out as JID_PAIR + empty user + the server
   // token. This wrote the bare string 's.whatsapp.net', and a bare string is
   // encoded as a plain dictionary token, so where every other client puts an
   // address the server was reading text. That is the whole of the difference,

package/lib/DeviceManager.js

@@ -1201,19 +1201,28 @@ class DeviceManager {
    * 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
+   * Works for either half of a contact's identity. WhatsApp keeps a device list
+   * under the phone number and another under the LID, hashes them separately,
+   * and sends both hashes on the same notification — so each is verified on its
+   * own, and one going wrong does not cost the other.
+   *
+   * @param   {string} cacheKey     the cache entry: digits, or 'lid:<user>'
+   * @param   {string} user         the JID user part the ids belong to
    * @param   {Array<{tag: string, deviceId: number}>} changes
-   * @param   {string} serverHash   the notification's device_hash
+   * @param   {string} serverHash   device_hash, or device_lid_hash
+   * @param   {string} [server]     's.whatsapp.net' (default) or 'lid'
    * @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;
+  verifyDeviceDelta(cacheKey, user, changes, serverHash, server) {
+    server = server || 's.whatsapp.net';
+    if (!cacheKey || !user || !serverHash) return false;
+    if (!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);
+    const cached = this._dcGet(cacheKey);
     if (!cached || !cached.length) return false;
 
     const next = new Set(cached);
@@ -1225,7 +1234,7 @@ class DeviceManager {
     }
 
     const ids  = [...next].sort((a, b) => a - b);
-    const jids = ids.map(d => makeDeviceJid(phone, d));
+    const jids = ids.map(d => makeDeviceJid(user, d, server));
 
     let ours;
     try {
@@ -1238,14 +1247,14 @@ class DeviceManager {
     }
 
     if (ours !== String(serverHash)) {
-      _whaDbg('[DBG] DEV_HASH mismatch for ' + phone + ' ours=' + ours +
+      _whaDbg('[DBG] DEV_HASH mismatch for ' + cacheKey + ' ours=' + ours +
         ' server=' + serverHash + ' — dropping cache');
-      this._dcDel([phone]);
+      this._dcDel([cacheKey]);
       return false;
     }
 
-    this._dcSet(phone, ids);
-    _whaDbg('[DBG] DEV_HASH verified for ' + phone + ' ids=[' + ids.join(',') +
+    this._dcSet(cacheKey, ids);
+    _whaDbg('[DBG] DEV_HASH verified for ' + cacheKey + ' ids=[' + ids.join(',') +
       '] hash=' + ours);
     return true;
   }

package/lib/PlayStore.js

@@ -1,8 +1,7 @@
 'use strict';
 
-// Fetching the WhatsApp APK from Google Play, the way Cobalt's PlayStoreUtils
-// does it, so the Android token material can be refreshed without anyone having
-// to find an APK by hand.
+// Fetching the WhatsApp APK from Google Play, so the Android token material can
+// be refreshed without anyone having to find an APK by hand.
 //
 // The route, in three hops:
 //
@@ -252,7 +251,7 @@ async function acquire(packageName, versionCode, headers) {
       }, headers),
       body
     });
-  } catch (_) { /* best effort, as in Cobalt */ }
+  } catch (_) { /* best effort */ }
 }
 
 // { baseUrl, splits: [{name, url}], cookies: {name: value} }

package/lib/Registration.js

@@ -16,9 +16,9 @@ const { dbg: _whaDbg, warn: _whaWarn } = require('./logger');
 // ---------- Request envelope ----------
 //
 // The registration server reads which platform is calling out of the
-// User-Agent. There is no form field for it — neither this library nor Cobalt
-// sends one — so a request whose User-Agent does not name a platform it knows is
-// refused with {"param":"platform","reason":"bad_param"} on every endpoint. The
+// User-Agent. There is no form field for it — none is sent — so a request whose
+// User-Agent does not name a platform it knows is refused with
+// {"param":"platform","reason":"bad_param"} on every endpoint. The
 // giveaway is that /client_log is refused the same way, and its body carries no
 // device fields at all: nothing about the platform is in the body to begin with.
 //
@@ -26,10 +26,9 @@ const { dbg: _whaDbg, warn: _whaWarn } = require('./logger');
 // was refused everywhere. iOS has always sent the full form and has always
 // worked, which is why only one of the two platforms was broken.
 //
-// The three extra Android headers come from Cobalt's AndroidClientRegistration,
-// which records them as observed on a live native Android registration. Its iOS
-// counterpart documents that the native iOS client omits all three, so the iOS
-// envelope stays exactly as it was.
+// The three extra Android headers were observed on a live native Android
+// registration. The native iOS client omits all three, so the iOS envelope
+// stays exactly as it was.
 // The platform token in the User-Agent. The Business builds name themselves
 // differently — `SMBA` on Android, `SMB iOS` on iOS — and the registration
 // server reads the platform out of exactly this string.
@@ -628,12 +627,48 @@ function parsePhone(phoneNumber) {
 // Cached per variant: the consumer and Business builds ship on their own
 // schedules, and announcing one's version as the other is a version the server
 // has no record of for that platform.
+//
+// The entries expire. Without that the first answer of a process is its last:
+// a session that reconnects for weeks would keep announcing whatever the store
+// happened to say the morning it started, which is the same stale-version
+// problem the refresh exists to solve. Six hours is short enough that a release
+// is picked up the day it lands and long enough that a connection flapping
+// every few seconds never reaches the network for it.
+const VERSION_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
 const _cachedIosVersion     = {};
 const _cachedAndroidVersion = {};
 
+function _cachedVersion(cache, key) {
+  const entry = cache[key];
+  if (!entry) return null;
+  if (Date.now() - entry.at > VERSION_CACHE_TTL_MS) {
+    delete cache[key];
+    return null;
+  }
+  return entry.value;
+}
+
+function _cacheVersion(cache, key, value) {
+  if (value) cache[key] = { value, at: Date.now() };
+  return value;
+}
+
+/**
+ * Drop the memoised lookups so the next call goes to the network.
+ *
+ * Ordinary callers are served by the TTL above; this exists for tests and for
+ * anything that needs a definite answer right now.
+ */
+function clearVersionCache() {
+  for (const k of Object.keys(_cachedIosVersion))     delete _cachedIosVersion[k];
+  for (const k of Object.keys(_cachedAndroidVersion)) delete _cachedAndroidVersion[k];
+}
+
 async function fetchIosVersion(business) {
   const key = business ? 'business' : 'personal';
-  if (_cachedIosVersion[key]) return _cachedIosVersion[key];
+  const hit = _cachedVersion(_cachedIosVersion, key);
+  if (hit) return hit;
   const bundleId = business ? IOS_BUSINESS_BUNDLE_ID : IOS_BUNDLE_ID;
   return new Promise((resolve) => {
     const req = https.get(
@@ -647,7 +682,7 @@ async function fetchIosVersion(business) {
             const json = JSON.parse(Buffer.concat(chunks).toString('utf8'));
             let ver = (json.results && json.results[0] && json.results[0].version) || IOS_VERSION_FALLBACK;
             if (!ver.startsWith('2.')) ver = '2.' + ver;
-            _cachedIosVersion[key] = ver;
+            _cacheVersion(_cachedIosVersion, key, ver);
             resolve(ver);
           } catch (_) {
             resolve(IOS_VERSION_FALLBACK);
@@ -665,7 +700,8 @@ async function fetchIosVersion(business) {
 // Falls back to ANDROID_VERSION_FALLBACK on any error.
 async function fetchAndroidVersion(business) {
   const key = business ? 'business' : 'personal';
-  if (_cachedAndroidVersion[key]) return _cachedAndroidVersion[key];
+  const hit = _cachedVersion(_cachedAndroidVersion, key);
+  if (hit) return hit;
   const packageName = business ? WHATSAPP_BUSINESS_PACKAGE : WHATSAPP_PACKAGE;
   try {
     const axios = require('axios');
@@ -698,15 +734,13 @@ async function fetchAndroidVersion(business) {
     // In Play Store JSON the current stable version appears first, before beta/history entries.
     const primary = html.match(/"(2\.\d+\.\d+\.\d+)"/);
     if (primary) {
-      _cachedAndroidVersion[key] = primary[1];
-      return primary[1];
+      return _cacheVersion(_cachedAndroidVersion, key, primary[1]);
     }
 
     // Secondary: unquoted version adjacent to "WhatsApp" text (catches alternate HTML structures).
     const secondary = html.match(/WhatsApp[^<"]{0,200}?(2\.\d+\.\d+\.\d+)/);
     if (secondary) {
-      _cachedAndroidVersion[key] = secondary[1];
-      return secondary[1];
+      return _cacheVersion(_cachedAndroidVersion, key, secondary[1]);
     }
 
     // Last resort: the highest 4-part version anywhere on the page. Play has
@@ -716,8 +750,7 @@ async function fetchAndroidVersion(business) {
     if (all && all.length) {
       const newest = all.sort(compareVersions).pop();
       _whaDbg('[DBG] ANDROID_VERSION scraped from an unrecognised page layout: ' + newest);
-      _cachedAndroidVersion[key] = newest;
-      return newest;
+      return _cacheVersion(_cachedAndroidVersion, key, newest);
     }
 
     _whaWarn('could not read the current WhatsApp version off the Play Store page — ' +
@@ -746,8 +779,8 @@ function compareVersions(a, b) {
 // Return the appropriate WhatsApp version for the active device.
 // If WA_VERSION is set in the environment, that value is always used.
 //
-// On Android the APK the token material came from decides it, the way Cobalt
-// announces the versionName of the APK it downloaded. The token is signed over
+// On Android the APK the token material came from decides it: the versionName
+// of the APK that was downloaded. The token is signed over
 // that build's classes.dex, so a version read from anywhere else describes a
 // different build than the one the token proves — which the server sees as a
 // token that does not belong to the client sending it. The live lookup stays as
@@ -1092,7 +1125,7 @@ function buildForm(pairs, extraPairs) {
 }
 
 // ---------- access_session_id ----------
-// Cobalt's newAccessSessionId(): 16 random bytes → URL-safe base64 without
+// 16 random bytes → URL-safe base64 without
 // padding (a 22-char token). Generated once per store/session and reused on
 // every attested endpoint, matching the native client.
 
@@ -1106,13 +1139,11 @@ function getAccessSessionId(store) {
   return store._accessSessionId;
 }
 
-// ---------- /code verification-code parameters (per platform, mirrors Cobalt) ----------
+// ---------- /code verification-code parameters (per platform) ----------
 // Returns the alternating name/value form fields the native client emits on a
 // /code request. Android sends the long device-fingerprint list; iOS sends the
-// short list. Values match AndroidClientRegistration / IosClientRegistration;
-// sim_mcc/sim_mnc/mcc/mnc keep whalibmob's real per-country values (better than
-// Cobalt's "000" placeholder), and advertising_id / backup_token come from the
-// store.
+// short list. sim_mcc/sim_mnc/mcc/mnc carry real per-country values rather than
+// a "000" placeholder, and advertising_id / backup_token come from the store.
 
 // How long the server said to wait, in seconds, or null when it did not say.
 //
@@ -1293,8 +1324,8 @@ async function buildPayload(store, waVersion, useToken, extraPairs) {
     ? store.fdid.toLowerCase()
     : store.fdid.toUpperCase();
 
-  // Device-attestation fields shipped on every attested endpoint (Cobalt
-  // attestationFields). Empty by default (NONE fallback); populated when a
+  // Device-attestation fields shipped on every attested endpoint.
+  // Empty by default (NONE fallback); populated when a
   // Frida attestation server is configured via WA_FRIDA_HOST. The Play
   // Integrity nonce is a stable per-session value derived from the store.
   const nonceB64 = attestation.toBase64Url(
@@ -2137,7 +2168,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, compareVersions, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
+module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, currentVersionFor, refreshSessionVersion, clearVersionCache, tryLoadAndroidMaterial, 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

@@ -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/lib/signal/SignalStore.js

@@ -41,7 +41,7 @@ const DEBOUNCE_MS = 300;
 // ─── Pre-key files ────────────────────────────────────────────────────────────
 //
 // One-time pre-keys do not live in the snapshot above. They get a file each,
-// named the way Baileys names them:
+// named one per id:
 //
 //   <base>/40756469325/40756469325.pre-key-1.json
 //   ...
@@ -60,8 +60,8 @@ const DEBOUNCE_MS = 300;
 // must — and a session still sitting in the old flat layout, where every
 // number shares one directory, does not collide with its neighbours either.
 //
-// A pre-key on disk is byte-for-byte what Baileys writes: BufferJSON, the raw
-// 32-byte public key with no type prefix.
+// A pre-key on disk is BufferJSON: the raw 32-byte public key with no type
+// prefix.
 //
 //   {"private":{"type":"Buffer","data":"…"},"public":{"type":"Buffer","data":"…"}}
 //
@@ -162,7 +162,7 @@ class SignalStore {
     this._pkTimer          = null;
     this._pkWriting        = false;
 
-    // The two counters Baileys keeps in creds. They live here instead because a
+    // The two pre-key counters. They live here rather than in creds because a
     // number's mobile and companion halves have a .signal.json each and must
     // never share a pre-key id space.
     //

package/package.json

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