whalibmob 5.19.0 → 5.19.2

package/.env.example

@@ -124,8 +124,10 @@
 
 
 # ─── Proxy ───────────────────────────────────────────────────────────────────
-# Route registration traffic through a SOCKS proxy. Requires the `socks`
-# package: npm install socks
+# Route every outbound connection through a SOCKS proxy: the message socket
+# (mobile TCP and web WSS alike), registration, the announced-version lookups,
+# the APK material download and media uploads. Requires the `socks` package:
+# npm install socks
 #
 # A bare host:port is assumed to be socks5. Add a scheme to be explicit, and
 # credentials if the proxy needs them. Percent-encode any @ or : in a password.

package/README.md

@@ -152,7 +152,7 @@ npm install -g whalibmob
     - [Two Sessions on One Number](#two-sessions-on-one-number)
   - [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under)
   - [When Registration Is Refused for Consent](#when-registration-is-refused-for-consent)
-  - [Routing Registration Through a Proxy](#routing-registration-through-a-proxy)
+  - [Routing Traffic Through a Proxy](#routing-traffic-through-a-proxy)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
   - [Signal Store Utilities](#signal-store-utilities)
     - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
@@ -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({
@@ -2487,9 +2488,9 @@ If that is refused too, the number has to go through the real app once, on a pho
 > [!NOTE]
 > The `login` field in that reply is worth reading. Brazilian mobiles gained a ninth digit that WhatsApp never adopted, so `+5571976034186` is filed as `+557176034186`. whalibmob adopts the server's form automatically on a successful registration and saves the session under it — the digit difference is not itself the failure.
 
-## Routing Registration Through a Proxy
+## Routing Traffic Through a Proxy
 
-Registration is the part of the protocol most likely to be refused from a datacenter IP. If you are seeing security blocks or an undeterminable number status, route it through a SOCKS proxy — Tor, or a residential provider.
+Two reasons to want this. Registration is the part of the protocol most likely to be refused from a datacenter IP, so a residential exit helps with security blocks and undeterminable number statuses. And on a network that cannot reach WhatsApp at all, nothing works without one.
 
 Install the optional dependency and set one environment variable:
 
@@ -2516,10 +2517,30 @@ process.env.SOCKS_PROXY = 'socks5://user:pass@proxy.example.com:1080'
 await requestSmsCode(phone, store)
 ```
 
-> [!NOTE]
-> This covers the registration traffic to `v.whatsapp.net`. The message socket and media transfers are not proxied — if you need those behind a proxy as well, open an issue describing the setup.
+### What goes through it
+
+Everything the library sends out:
+
+| Connection | Destination |
+|---|---|
+| Message socket, mobile | raw TCP to WhatsApp |
+| Message socket, web | `wss://web.whatsapp.com/ws/chat` |
+| Registration | `v.whatsapp.net` |
+| Announced version, iOS | App Store lookup |
+| Announced version, Android | Play Store listing |
+| Announced version, web | `web.whatsapp.com/sw.js` |
+| APK material for registration | Play Store download |
+| Media upload | WhatsApp's media hosts |
+
+Node's `http`/`https` modules ignore proxy environment variables entirely — a proxy has to be handed in as an agent, per call site. Only the registration POST used to do that, which produced a confusing failure: `curl -x socks5://…` reached WhatsApp while the library timed out on the same machine, falling back to a pinned version with only a debug line to show for it:
+
+```
+[DBG] WEB_VERSION 2.3000.1035194821 (pinned fallback: sw.js fetch timed out)
+```
+
+All eight paths now share one agent.
 
-If `socks` is not installed, or a proxy is unreachable, you get a message saying so rather than a silent failure. In the rare case the package lives somewhere `require()` cannot find it, `WA_SOCKS_LIB` takes an absolute path to it.
+If `socks` is not installed, or a proxy is unreachable, you get a message saying so rather than a silent failure. A proxy URL that cannot be parsed leaves the connection direct rather than throwing — a version lookup with a pinned fallback should not take a process down over its proxy. In the rare case the package lives somewhere `require()` cannot find it, `WA_SOCKS_LIB` takes an absolute path to it.
 
 ## Saving & Restoring Sessions
 
@@ -3278,8 +3299,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/MediaService.js

@@ -195,11 +195,17 @@ function _tryUpload(host, mediaPath, token, auth, encrypted, web) {
     const hostname = typeof host === 'string' ? host : host.hostname;
     const urlPath  = `/${mediaPath}/${token}?auth=${auth}&token=${token}`;
 
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     const options = {
       hostname,
       port:    443,
       path:    urlPath,
       method:  'POST',
+      // The media hosts are as unreachable as the rest of WhatsApp on a network
+      // that needs a proxy. Uploading direct while the socket is proxied leaves
+      // a session that connects and then cannot send a photo.
+      agent:   agent || undefined,
       headers: Object.assign({
         'Content-Type':   'application/octet-stream',
         'Content-Length': encrypted.length,
@@ -265,9 +271,15 @@ const MAX_REDIRECTS = 5;
 
 function _httpGet(url, opts, depth) {
   return new Promise((resolve, reject) => {
-    const lib = url.startsWith('https') ? https : http;
+    const isTls = url.startsWith('https');
+    const lib = isTls ? https : http;
     const web = !!(opts && opts.web);
-    lib.get(url, { headers: mediaHeaders(web) }, (res) => {
+    // The agent tunnels TLS, so it belongs on https only. A plain-http media
+    // URL is rare enough that leaving it direct is better than handing an
+    // https.Agent to the http module and getting an obscure failure.
+    const { proxyAgent } = require('./socks');
+    const agent = isTls ? proxyAgent() : null;
+    lib.get(url, { agent: agent || undefined, headers: mediaHeaders(web) }, (res) => {
       const status = res.statusCode || 0;
       if (status === 301 || status === 302) {
         res.resume();                                   // drop the redirect body

package/lib/PlayStore.js

@@ -124,12 +124,18 @@ function _request(url, opts) {
   opts = opts || {};
   return new Promise((resolve, reject) => {
     const u   = new URL(url);
+    // The APK material download is a Google endpoint, blocked on the same
+    // networks that block WhatsApp. Registration would otherwise fall back to
+    // stale certificate material with no way to refresh it.
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     const req = https.request({
       hostname: u.hostname,
       port:     u.port || 443,
       path:     u.pathname + u.search,
       method:   opts.method || 'GET',
       headers:  opts.headers || {},
+      agent:    agent || undefined,
       timeout:  REQUEST_TIMEOUT
     }, (res) => {
       // The CDN answers a signed URL with a redirect more often than not.

package/lib/Registration.js

@@ -56,108 +56,23 @@ function registrationHeaders(device, waVersion) {
 
 // ---------- SOCKS4 / SOCKS5 / Tor support ----------
 //
-// Set SOCKS_PROXY (or TOR_PROXY) to route registration traffic through a proxy:
-//
-//   socks5://127.0.0.1:9050              Tor
-//   socks5://user:pass@host:1080         authenticated residential proxy
-//   socks5h://host:1080                  resolve the destination at the proxy
-//   socks4://host:1080                   older proxies
-//
-// Requires the `socks` package: npm install socks
-
-const SOCKS_SCHEMES = {
-  'socks:':   5,
-  'socks5:':  5,
-  'socks5h:': 5,
-  'socks4:':  4,
-  'socks4a:': 4
-};
-
-// Resolve the library the way every other dependency is resolved.
-//
-// This used to be a hardcoded absolute path into one particular machine's
-// global npm directory. It resolved there and nowhere else, so proxy support
-// was dead for everybody who installed whalibmob normally — the require threw
-// MODULE_NOT_FOUND the moment a proxy was configured. WA_SOCKS_LIB stays as an
-// escape hatch for unusual layouts, but it is an override now, not the only
-// way in.
-function loadSocks() {
-  const override = process.env.WA_SOCKS_LIB;
-  if (override) {
-    try { return require(override); }
-    catch (err) {
-      throw new Error('WA_SOCKS_LIB points at ' + override +
-        ' but it could not be loaded: ' + err.message);
-    }
-  }
-  try {
-    return require('socks');
-  } catch (_) {
-    throw new Error(
-      "A SOCKS proxy is configured but the 'socks' package is not installed. " +
-      'Run: npm install socks'
-    );
-  }
-}
-
-/**
- * Parse a proxy URL into what SocksClient expects.
- *
- * Accepts the schemes above, with or without credentials, and defaults the
- * port to 1080 the way every SOCKS client does.
- */
-function parseSocksProxy(proxyUrl) {
-  let raw = String(proxyUrl || '').trim();
-  if (!raw) throw new Error('No SOCKS proxy configured');
-
-  // A bare host:port is what .env.example has always shown and what most people
-  // type. Without a scheme `new URL` reads "127.0.0.1:" as the protocol and the
-  // rest as the path, so it has to be filled in before parsing.
-  if (!/^[a-z0-9+.-]+:\/\//i.test(raw)) raw = 'socks5://' + raw;
-
-  let url;
-  try { url = new URL(raw); }
-  catch (_) { throw new Error('Invalid SOCKS proxy URL: ' + proxyUrl); }
-
-  const type = SOCKS_SCHEMES[url.protocol];
-  if (!type) {
-    throw new Error('Unsupported proxy scheme "' + url.protocol + '" — use ' +
-      Object.keys(SOCKS_SCHEMES).map(s => s.replace(':', '')).join(', '));
-  }
-  if (!url.hostname) throw new Error('SOCKS proxy URL has no host: ' + proxyUrl);
-
-  const proxy = {
-    host: url.hostname,
-    port: parseInt(url.port, 10) || 1080,
-    type
-  };
-  // Credentials may be percent-encoded in a URL; a password with an @ or a :
-  // in it is common enough on paid proxies to be worth decoding.
-  if (url.username) proxy.userId   = decodeURIComponent(url.username);
-  if (url.password) proxy.password = decodeURIComponent(url.password);
-  return proxy;
-}
-
-// TOR_PROXY wins when both are set — the precedence .env.example has always
-// documented.
-function socksProxyUrl() {
-  return process.env.TOR_PROXY || process.env.SOCKS_PROXY || '';
-}
+// The parsing, the dialer and the HTTPS agent all live in ./socks now, because
+// registration is no longer the only thing that needs them: the version
+// lookups below, the web sw.js probe, the WhatsApp Web socket and the mobile
+// TCP socket route through the same proxy. They are re-exported at the bottom
+// of this file so existing importers keep working.
+const {
+  parseSocksProxy, socksProxyUrl, socksConnect, proxyAgent
+} = require('./socks');
 
 async function httpPostViaSocks(path, body, waVersion, proxyUrl, authHeader, device) {
-  const proxy = parseSocksProxy(proxyUrl);
   const dHost = 'v.whatsapp.net';
   const dPort = 443;
 
-  const { SocksClient } = loadSocks();
-  const { socket: rawSocket } = await SocksClient.createConnection({
-    proxy,
-    command:     'connect',
-    destination: { host: dHost, port: dPort },
-    // Without this a proxy that accepts the TCP connection and then says
-    // nothing leaves the whole registration hanging with no error.
-    timeout: 20000
-  });
+  // socksConnect carries the same 20s handshake timeout this used to set
+  // inline: without one, a proxy that accepts the TCP connection and then says
+  // nothing leaves the whole registration hanging with no error.
+  const rawSocket = await socksConnect(proxyUrl, dHost, dPort);
 
   const tlsSocket = tls.connect({
     socket:             rawSocket,
@@ -671,9 +586,10 @@ async function fetchIosVersion(business) {
   if (hit) return hit;
   const bundleId = business ? IOS_BUSINESS_BUNDLE_ID : IOS_BUNDLE_ID;
   return new Promise((resolve) => {
+    const agent = proxyAgent();
     const req = https.get(
       'https://itunes.apple.com/lookup?bundleId=' + bundleId,
-      { headers: { 'User-Agent': IOS_USER_AGENT } },
+      { agent: agent || undefined, headers: { 'User-Agent': IOS_USER_AGENT } },
       (res) => {
         const chunks = [];
         res.on('data', d => chunks.push(d));
@@ -705,6 +621,10 @@ async function fetchAndroidVersion(business) {
   const packageName = business ? WHATSAPP_BUSINESS_PACKAGE : WHATSAPP_PACKAGE;
   try {
     const axios = require('axios');
+    // Unlike https.get, axios reads HTTP_PROXY/HTTPS_PROXY on its own. That
+    // stays untouched when no SOCKS proxy is configured; `proxy: false` is set
+    // only alongside our own agent, so the two never fight over the socket.
+    const socksAgent = proxyAgent();
     const resp = await axios.get(
       'https://play.google.com/store/apps/details?id=' + packageName + '&hl=en&gl=us',
       {
@@ -719,7 +639,11 @@ async function fetchAndroidVersion(business) {
         },
         responseType: 'text',
         decompress:   true,
-        timeout: 12000
+        timeout: 12000,
+        // axios takes an agent under a different key than https.get does, but
+        // drives it identically. Omitted, this lookup ignores SOCKS_PROXY and
+        // silently falls back to a pinned version on a blocked network.
+        ...(socksAgent ? { httpsAgent: socksAgent, proxy: false } : {})
       }
     );
     // Buffer when the response was compressed and axios handed the bytes back

package/lib/WebSocketStream.js

@@ -38,8 +38,15 @@ class WebSocketStream extends EventEmitter {
 
   connect() {
     const WebSocket = loadWs();
+    // ws drives an agent exactly the way https.request does, so the same SOCKS
+    // agent that carries the version probe carries the socket. Without it the
+    // upgrade request goes out directly while everything else in the process
+    // is proxied, which fails in the one situation a proxy is set for.
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     this._ws = new WebSocket(this._url, {
       origin:  this._origin,
+      agent:   agent || undefined,
       headers: {
         'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
                       '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'

package/lib/WebVersion.js

@@ -18,6 +18,7 @@
 
 const https = require('https');
 const { WEB_VERSION_FALLBACK } = require('./constants');
+const { proxyAgent } = require('./socks');
 
 const SW_URL   = 'https://web.whatsapp.com/sw.js';
 const CACHE_MS = 60 * 60 * 1000;   // an hour; the revision changes far slower
@@ -27,7 +28,13 @@ let _cachedAt = 0;
 
 function fetchText(url, timeoutMs) {
   return new Promise((resolve, reject) => {
+    // Without this the request ignores SOCKS_PROXY and goes out directly —
+    // which on a network that cannot reach web.whatsapp.com means a ten-second
+    // stall and a fall back to the pinned revision, while curl through the very
+    // same proxy answers instantly.
+    const agent = proxyAgent();
     const req = https.get(url, {
+      agent: agent || undefined,
       headers: {
         // The minimum that gets past the anti-bot check on this path.
         'sec-fetch-site': 'none',

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/noise.js

@@ -370,15 +370,8 @@ class NoiseSocket extends EventEmitter {
       this._connectResolve = resolve;
       this._connectReject  = reject;
 
-      if (this.transport === 'web') {
-        const { WebSocketStream } = require('./WebSocketStream');
-        this.socket = new WebSocketStream().connect();
-      } else {
-        this.socket = net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT });
-      }
-      // OS-level TCP keepalive: detects silently-dead NAT connections that never send FIN/RST
-      this.socket.setKeepAlive(true, 15000);
-      // Connect-phase watchdog: abort if TCP handshake takes >20s
+      // Armed before the socket exists so it covers a SOCKS handshake that
+      // never completes, not just a TCP one.
       this._connectTimeoutTimer = setTimeout(() => {
         if (this._connectReject) {
           const err = new Error('WA TCP connect timeout (20s)');
@@ -386,16 +379,55 @@ class NoiseSocket extends EventEmitter {
           this._connectResolve = null;
           this._connectReject  = null;
         }
-        try { this.socket.destroy(); } catch (_) {}
+        try { if (this.socket) this.socket.destroy(); } catch (_) {}
       }, 20000);
-      this.socket.on('connect', () => {
-        clearTimeout(this._connectTimeoutTimer);
-        this._connectTimeoutTimer = null;
-        this._onTcpConnect();
-      });
-      this.socket.on('data',    (data) => this._onData(data));
-      this.socket.on('error',   (err)  => this._onTcpError(err));
-      this.socket.on('close',   ()     => this._onTcpClose());
+
+      // `alreadyConnected` is the SOCKS case: the proxy hands back a socket
+      // whose handshake is finished, so no 'connect' event will ever fire on
+      // it and waiting for one would stall until the watchdog fires.
+      const attach = (sock, alreadyConnected) => {
+        this.socket = sock;
+        // OS-level TCP keepalive: detects silently-dead NAT connections that
+        // never send FIN/RST.
+        sock.setKeepAlive(true, 15000);
+
+        sock.on('data',  (data) => this._onData(data));
+        sock.on('error', (err)  => this._onTcpError(err));
+        sock.on('close', ()     => this._onTcpClose());
+
+        const onUp = () => {
+          clearTimeout(this._connectTimeoutTimer);
+          this._connectTimeoutTimer = null;
+          this._onTcpConnect();
+        };
+        if (alreadyConnected) onUp();
+        else sock.on('connect', onUp);
+      };
+
+      if (this.transport === 'web') {
+        const { WebSocketStream } = require('./WebSocketStream');
+        attach(new WebSocketStream().connect(), false);
+        return;
+      }
+
+      // Mobile is a raw TCP socket, and net.createConnection has no notion of
+      // a proxy. Dial through SOCKS when one is configured so the mobile
+      // transport is reachable from the same networks the web one is.
+      const { socksProxyUrl, socksConnect } = require('./socks');
+      const proxyUrl = socksProxyUrl();
+      if (!proxyUrl) {
+        attach(net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT }), false);
+        return;
+      }
+
+      _whaDbg('[DBG] TCP via SOCKS proxy → ' + WHATSAPP_HOST + ':' + WHATSAPP_PORT);
+      socksConnect(proxyUrl, WHATSAPP_HOST, WHATSAPP_PORT)
+        .then(sock => attach(sock, true))
+        .catch(err => {
+          clearTimeout(this._connectTimeoutTimer);
+          this._connectTimeoutTimer = null;
+          this._onTcpError(err);
+        });
     });
   }
 

package/lib/socks.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// SOCKS4 / SOCKS5 / Tor support for every outbound connection the library makes.
+//
+// Set SOCKS_PROXY (or TOR_PROXY) and everything goes through it:
+//
+//   socks5://127.0.0.1:9050              Tor
+//   socks5://user:pass@host:1080         authenticated residential proxy
+//   socks5h://host:1080                  resolve the destination at the proxy
+//   socks4://host:1080                   older proxies
+//
+// Requires the `socks` package, which ships as an optional dependency.
+//
+// Why this module exists at all: the proxy used to be honoured by exactly one
+// call site, the registration POST. Everything else — the App Store and Play
+// Store version lookups, the web client's sw.js revision probe, the WhatsApp
+// Web socket and the mobile TCP socket — went out through `https.get`,
+// `axios` and `net.createConnection`, none of which look at proxy environment
+// variables. Node has no built-in proxy support; an agent has to be handed in.
+//
+// The visible symptom was a connection that "worked" in curl and timed out in
+// the library:
+//
+//   [DBG] WEB_VERSION 2.3000.1035194821 (pinned fallback: sw.js fetch timed out)
+//
+// curl honours SOCKS_PROXY, https.get does not. Same machine, same proxy,
+// opposite results.
+
+const https = require('https');
+const tls   = require('tls');
+
+const SOCKS_SCHEMES = {
+  'socks:':   5,
+  'socks5:':  5,
+  'socks5h:': 5,
+  'socks4:':  4,
+  'socks4a:': 4
+};
+
+// How long a SOCKS handshake may take before it is treated as dead. A proxy
+// that accepts the TCP connection and then says nothing would otherwise hang
+// whatever asked for the connection.
+const SOCKS_TIMEOUT_MS = 20000;
+
+// Resolve the library the way every other dependency is resolved.
+//
+// WA_SOCKS_LIB stays as an escape hatch for unusual layouts, but it is an
+// override, not the only way in.
+function loadSocks() {
+  const override = process.env.WA_SOCKS_LIB;
+  if (override) {
+    try { return require(override); }
+    catch (err) {
+      throw new Error('WA_SOCKS_LIB points at ' + override +
+        ' but it could not be loaded: ' + err.message);
+    }
+  }
+  try {
+    return require('socks');
+  } catch (_) {
+    throw new Error(
+      "A SOCKS proxy is configured but the 'socks' package is not installed. " +
+      'Run: npm install socks'
+    );
+  }
+}
+
+/**
+ * Parse a proxy URL into what SocksClient expects.
+ *
+ * Accepts the schemes above, with or without credentials, and defaults the
+ * port to 1080 the way every SOCKS client does.
+ */
+function parseSocksProxy(proxyUrl) {
+  let raw = String(proxyUrl || '').trim();
+  if (!raw) throw new Error('No SOCKS proxy configured');
+
+  // A bare host:port is what .env.example has always shown and what most people
+  // type. Without a scheme `new URL` reads "127.0.0.1:" as the protocol and the
+  // rest as the path, so it has to be filled in before parsing.
+  if (!/^[a-z0-9+.-]+:\/\//i.test(raw)) raw = 'socks5://' + raw;
+
+  let url;
+  try { url = new URL(raw); }
+  catch (_) { throw new Error('Invalid SOCKS proxy URL: ' + proxyUrl); }
+
+  const type = SOCKS_SCHEMES[url.protocol];
+  if (!type) {
+    throw new Error('Unsupported proxy scheme "' + url.protocol + '" — use ' +
+      Object.keys(SOCKS_SCHEMES).map(s => s.replace(':', '')).join(', '));
+  }
+  if (!url.hostname) throw new Error('SOCKS proxy URL has no host: ' + proxyUrl);
+
+  const proxy = {
+    host: url.hostname,
+    port: parseInt(url.port, 10) || 1080,
+    type
+  };
+  // Credentials may be percent-encoded in a URL; a password with an @ or a :
+  // in it is common enough on paid proxies to be worth decoding.
+  if (url.username) proxy.userId   = decodeURIComponent(url.username);
+  if (url.password) proxy.password = decodeURIComponent(url.password);
+  return proxy;
+}
+
+// TOR_PROXY wins when both are set — the precedence .env.example has always
+// documented. Read from the environment on every call rather than cached at
+// require time, so a process that sets it late still gets it.
+function socksProxyUrl() {
+  return process.env.TOR_PROXY || process.env.SOCKS_PROXY || '';
+}
+
+/** Whether a proxy is configured at all. Cheap, and never throws. */
+function hasProxy() {
+  return !!socksProxyUrl();
+}
+
+/**
+ * Open a raw TCP connection to host:port through the configured proxy.
+ *
+ * Resolves with a connected socket — the SOCKS handshake is already done, so
+ * no 'connect' event will fire on it. Callers that key off 'connect' have to
+ * account for that.
+ */
+async function socksConnect(proxyUrl, host, port, timeoutMs) {
+  const proxy = parseSocksProxy(proxyUrl);
+  const { SocksClient } = loadSocks();
+  const { socket } = await SocksClient.createConnection({
+    proxy,
+    command:     'connect',
+    destination: { host, port },
+    timeout:     timeoutMs > 0 ? timeoutMs : SOCKS_TIMEOUT_MS
+  });
+  return socket;
+}
+
+/**
+ * An https.Agent that tunnels through SOCKS.
+ *
+ * `https.get`, `axios` and `ws` all accept an agent and all drive it the same
+ * way, so one of these covers every HTTPS and WSS call site in the library.
+ *
+ * The base agent's createConnection calls tls.connect on a fresh TCP socket;
+ * this one gets the TCP socket from the proxy first and layers TLS on top of
+ * it. Everything else — pooling, keep-alive, timeouts — is inherited.
+ */
+class SocksHttpsAgent extends https.Agent {
+  constructor(proxyUrl, opts) {
+    super(opts);
+    this._proxyUrl = proxyUrl;
+    // Fail fast on a malformed URL, at construction rather than on first use,
+    // so a typo surfaces as a clear error instead of a stalled request.
+    this._proxy = parseSocksProxy(proxyUrl);
+  }
+
+  createConnection(options, callback) {
+    const { SocksClient } = loadSocks();
+    const host = options.host || options.hostname;
+    const port = Number(options.port) || 443;
+
+    SocksClient.createConnection({
+      proxy:       this._proxy,
+      command:     'connect',
+      destination: { host, port },
+      timeout:     SOCKS_TIMEOUT_MS
+    }).then(({ socket }) => {
+      // servername has to be set explicitly: the TLS socket is built on a
+      // socket that was never given a hostname, so without it SNI goes out
+      // empty and WhatsApp's edge answers with the wrong certificate.
+      const tlsSocket = tls.connect(Object.assign({}, options, {
+        socket,
+        host,
+        port,
+        servername: options.servername || (typeof host === 'string' ? host : undefined)
+      }));
+      callback(null, tlsSocket);
+    }).catch(err => callback(err));
+  }
+}
+
+// One agent per proxy URL. Agents pool sockets, so building a fresh one per
+// request would throw the pool away every time.
+const _agentCache = new Map();
+
+/**
+ * The agent for a given proxy URL, or null when none is configured.
+ *
+ * Never throws: a proxy that cannot be parsed, or a missing `socks` package,
+ * returns null and leaves the caller on a direct connection. A version lookup
+ * that has a pinned fallback must not take the process down over its proxy.
+ */
+function socksAgent(proxyUrl) {
+  const url = proxyUrl || socksProxyUrl();
+  if (!url) return null;
+  if (_agentCache.has(url)) return _agentCache.get(url);
+
+  let agent = null;
+  try {
+    agent = new SocksHttpsAgent(url, { keepAlive: false });
+  } catch (_) {
+    agent = null;
+  }
+  _agentCache.set(url, agent);
+  return agent;
+}
+
+/** The agent for the environment's proxy, or null. */
+function proxyAgent() {
+  return socksAgent(socksProxyUrl());
+}
+
+/** Drop cached agents. For tests, and for a process that swaps proxies. */
+function clearAgentCache() {
+  for (const agent of _agentCache.values()) {
+    if (agent && typeof agent.destroy === 'function') {
+      try { agent.destroy(); } catch (_) {}
+    }
+  }
+  _agentCache.clear();
+}
+
+module.exports = {
+  SOCKS_SCHEMES,
+  SOCKS_TIMEOUT_MS,
+  loadSocks,
+  parseSocksProxy,
+  socksProxyUrl,
+  hasProxy,
+  socksConnect,
+  socksAgent,
+  proxyAgent,
+  clearAgentCache,
+  SocksHttpsAgent
+};

package/package.json

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