whalibmob 5.6.4 → 5.6.9

package/.env.example

@@ -61,11 +61,23 @@
 
 
 # ─── Proxy ───────────────────────────────────────────────────────────────────
-# Route registration traffic through a SOCKS5 proxy, given as host:port.
-# TOR_PROXY takes precedence over SOCKS_PROXY when both are set.
-# Default Tor SOCKS port is 9050.
+# Route registration traffic through a SOCKS proxy. 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.
+#
+#   TOR_PROXY takes precedence over SOCKS_PROXY when both are set.
+#   The default Tor SOCKS port is 9050; the SOCKS default is 1080.
+#
 # TOR_PROXY=127.0.0.1:9050
-# SOCKS_PROXY=127.0.0.1:1080
+# TOR_PROXY=socks5://127.0.0.1:9050
+# SOCKS_PROXY=socks5://user:pass@proxy.example.com:1080
+# SOCKS_PROXY=socks5h://proxy.example.com:1080
+# SOCKS_PROXY=socks4://proxy.example.com:1080
+#
+# Only if `socks` lives somewhere require() cannot find it:
+# WA_SOCKS_LIB=/absolute/path/to/socks/build/index.js
 
 
 # ─── Frida attestation bridge ────────────────────────────────────────────────

package/README.md

@@ -150,6 +150,7 @@ npm install -g whalibmob
     - [Handling Reconnects](#handling-reconnects)
     - [Knowing Which Mode You Are In](#knowing-which-mode-you-are-in)
     - [Two Sessions on One Number](#two-sessions-on-one-number)
+  - [Routing Registration Through a Proxy](#routing-registration-through-a-proxy)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
   - [Signal Store Utilities](#signal-store-utilities)
     - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
@@ -806,6 +807,40 @@ await client.connectWeb(PHONE)  // web / companion, over WebSocket
 
 Use two `WhalibmobClient` instances if you want both at once.
 
+## Routing Registration 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.
+
+Install the optional dependency and set one environment variable:
+
+```sh
+npm install socks
+```
+
+```sh
+# Tor
+export TOR_PROXY=socks5://127.0.0.1:9050
+
+# a residential proxy that needs credentials
+export SOCKS_PROXY=socks5://user:pass@proxy.example.com:1080
+```
+
+A bare `host:port` is assumed to be SOCKS5, so `TOR_PROXY=127.0.0.1:9050` works too. `socks5`, `socks5h`, `socks4` and `socks4a` are all accepted, and `TOR_PROXY` wins if both variables are set.
+
+If the password contains an `@` or a `:`, percent-encode it — `p@ss:word` becomes `p%40ss%3Aword`. whalibmob decodes it before handing it to the proxy.
+
+```js
+// or from code, before you call any registration function
+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.
+
+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.
+
 ## Saving & Restoring Sessions
 
 Sessions are automatically persisted to disk as JSON files under the `sessionDir` you provide. The file is named `<phone>.json`. On the next `client.init()` call the session is restored and no re-registration is needed.

package/cli.js

@@ -576,6 +576,24 @@ function attachEvents(client) {
       ? 'link again with /pair'
       : 're-register with /reg code';
     fail('session revoked: ' + f.reason + ' — ' + how);
+    _rl && _rl.resume();
+    notConnected();
+  });
+
+  // Someone else opened a session for this number. Reconnecting would fight
+  // them for it, so the client stands down and says so.
+  client.on('connection_replaced', (r) => {
+    _rl && _rl.pause();
+    fail('connection replaced');
+    out('  ' + r.message);
+    _rl && _rl.resume();
+    notConnected();
+  });
+
+  // A stanza whose shape we mishandled. Not fatal — the connection kept going.
+  client.on('node_error', (e) => {
+    _rl && _rl.pause();
+    fail('could not handle a <' + e.tag + '>: ' + (e.err && e.err.message));
     _rl && (_rl.resume(), _rl.prompt(true));
   });
 
@@ -585,7 +603,8 @@ function attachEvents(client) {
     fail('rejected by WhatsApp (' + r.reason +
          (r.location ? ', edge ' + r.location : '') + ')');
     out('  ' + r.message);
-    _rl && (_rl.resume(), _rl.prompt(true));
+    _rl && _rl.resume();
+    notConnected();
   });
 
   client.on('error', (e) => {
@@ -715,7 +734,7 @@ async function doConnectWeb(phone, opts) {
     client.once('auth_failure', () => clearInterval(keepAlive));
   } catch (e) {
     fail(e.message);
-    _rl.prompt();
+    notConnected();
   }
 }
 
@@ -735,7 +754,7 @@ async function doConnect(phone) {
   client.once('auth_failure', () => {
     fail('auth failed — session revoked');
     out('use /reg code ' + phone + ' to re-register');
-    _rl.prompt();
+    notConnected();
   });
 
   try {
@@ -745,11 +764,48 @@ async function doConnect(phone) {
     client.once('auth_failure', () => clearInterval(keepAlive));
   } catch (e) {
     fail(e.message);
-    out('register first with: /reg code ' + phone);
-    _rl.prompt();
+    if (/No (primary )?session for/i.test(e.message)) {
+      if (hasWebSession(phone)) {
+        out('  this number is linked as a companion — use:  /pair ' + phone);
+      } else {
+        out('  register it:  /reg code ' + phone + '   then  /reg confirm ' + phone + ' <code>');
+        out('  or link it to an account already on a phone:  /pair ' + phone);
+      }
+    } else if (e.code === '401' || /auth failure 401/i.test(e.message)) {
+      // 401 says the credentials were refused; it does not say whether the
+      // number itself is still registered. Ask, so the next step is obvious.
+      out('  checking whether the number is still registered...');
+      try {
+        const probe = await client.checkSessionAlive();
+        if (probe.alive) {
+          out('  the number IS still registered, but this device was logged out.');
+          out('  register it again:  /reg code ' + phone);
+        } else if (probe.error) {
+          out('  could not reach the registration endpoint: ' + probe.error);
+        } else {
+          out('  the registration is gone server-side (' + (probe.status || 'no status') + ').');
+          out('  register it again:  /reg code ' + phone);
+        }
+      } catch (probeErr) {
+        out('  status check failed: ' + probeErr.message);
+      }
+    }
+    notConnected();
   }
 }
 
+// Put the shell back in its disconnected state.
+//
+// The prompt is the only standing indication of whether there is a session, so
+// it has to be right after a failure: a prompt reading "wa +<number>>" under an
+// error saying there is no session for that number is the shell contradicting
+// itself.
+function notConnected() {
+  _client = null;
+  _phone  = null;
+  if (_rl) { _rl.setPrompt('wa> '); _rl.prompt(); }
+}
+
 // ─── guard ────────────────────────────────────────────────────────────────────
 
 function requireConn() {
@@ -2039,7 +2095,11 @@ async function main() {
     const method = flags.pair || forced === 'pair' || forced === 'pairing' ? 'pairing'
                  : flags.sms  || forced === 'sms'                          ? 'sms'
                  : await askLoginMethod(phone);
-    openShell('wa +' + phone + '> ');
+    // Plain `wa>` until the connection actually opens. Naming the number in the
+    // prompt before that says "connected as this number" while the line above
+    // it says there is no session, which is the opposite of what happened —
+    // doConnect sets the real prompt from the 'connected' event.
+    openShell();
     out('connecting to +' + phone + '...');
     if (method === 'pairing') await doConnectWeb(phone);
     else                      await doConnect(phone);
@@ -2053,7 +2113,7 @@ async function main() {
     if (!phone) { fail('phone number required'); process.exit(1); }
     const custom = (sub ? pos[0] : pos[1]) ||
                    (typeof flags.code === 'string' ? flags.code : undefined);
-    openShell('wa +' + phone + '> ');
+    openShell();
     out('linking +' + phone + ' to an existing WhatsApp account...');
     await doConnectWeb(phone, { customCode: custom });
     return;

package/lib/Client.js

@@ -4,6 +4,7 @@ const { dbg: _whaDbg, configureLogger: _whaConfigLogger } = require('./logger');
 
 const EventEmitter  = require('events');
 const path          = require('path');
+const fs            = require('fs');
 const crypto        = require('crypto');
 const { NoiseSocket }     = require('./noise');
 const { MessageSender, generateMessageId, makeJid, buildOrGetAdvIdentity } = require('./messages/MessageSender');
@@ -278,7 +279,19 @@ class WhalibmobClient extends EventEmitter {
     const sessionFile = path.join(this._sessionDir, `${phoneNumber}.json`);
     this._store = loadStore(sessionFile);
     if (!this._store) {
-      throw new Error(`No session for ${phoneNumber}. Run 'wa registration -R <code>' first.`);
+      // Say what is missing, and say it accurately. The old text pointed at
+      // 'wa registration -R', a flag this CLI has never accepted, so anyone who
+      // followed it got a second error instead of a registered number. A
+      // library has no business teaching CLI syntax either — the caller knows
+      // which interface it is; this only has to name the state.
+      const hasWeb = fs.existsSync(path.join(this._sessionDir, `${phoneNumber}.web.json`));
+      throw new Error(
+        hasWeb
+          ? `No primary session for ${phoneNumber}, but it is linked as a ` +
+            'companion device — use connectWeb() rather than init().'
+          : `No session for ${phoneNumber} — register the number first, or ` +
+            'link it to an existing account with connectWeb().'
+      );
     }
 
     const signalFile  = path.join(this._sessionDir, `${phoneNumber}.signal.json`);
@@ -766,6 +779,28 @@ class WhalibmobClient extends EventEmitter {
     this._closing = false;
   }
 
+  /**
+   * Ask the server whether this session's registration is still alive.
+   *
+   * The read-only /exist probe, run with the credentials already on disk. It
+   * answers the question a 401 leaves open: whether the number is still
+   * registered and only this device was cut loose, or whether the registration
+   * is gone entirely. Sends nothing to the phone and requests no code, so it
+   * is safe to run on a failure.
+   *
+   * @returns {Promise<{alive: boolean, status: string|null, raw: object|null, error?: string}>}
+   */
+  async checkSessionAlive() {
+    if (!this._store) throw new Error('No session loaded');
+    try {
+      const res    = await checkIfRegistered(this._store);
+      const status = (res && (res.status || res.reason)) || null;
+      return { alive: status === 'ok', status, raw: res };
+    } catch (err) {
+      return { alive: false, status: null, raw: null, error: err.message };
+    }
+  }
+
   // ─── Reconnection ─────────────────────────────────────────────────────────
 
   _scheduleReconnect() {
@@ -984,6 +1019,29 @@ class WhalibmobClient extends EventEmitter {
   // We do NOT decrypt the patches — that requires the full LTHASH machinery.
   // We DO update our version counters from the server response so that we
   // never re-request the same snapshot twice.
+  /**
+   * Acknowledge a dirty bit so the server stops announcing it.
+   *
+   * `<ib><dirty type="..."/></ib>` is the server saying something changed while
+   * we were away. Whatever the client does about it, the bit has to be cleared
+   * or the same announcement arrives on every connection.
+   *
+   * @param {string} type            the dirty type, e.g. 'groups'
+   * @param {number|string} [fromTs] the timestamp the announcement carried
+   */
+  _cleanDirtyBits(type, fromTs) {
+    if (!this._socket || !this._connected) return;
+    const attrs = { type: String(type) };
+    if (fromTs) attrs.timestamp = String(fromTs);
+    _whaDbg('[DBG] CLEAN_DIRTY type=' + type + (fromTs ? ' t=' + fromTs : ''));
+    this._socket.sendNode(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'set',
+      xmlns: 'urn:xmpp:whatsapp:dirty'
+    }, [new BinaryNode('clean', attrs, null)]));
+  }
+
   _sendAppStateSyncForTypes(dirtyTypes) {
     if (!this._socket || !this._connected) return;
 
@@ -1002,7 +1060,11 @@ class WhalibmobClient extends EventEmitter {
     for (const type of dirtyTypes) {
       const mapped = COLLECTION_MAP[type];
       if (!mapped) {
-        _whaDbg('[DBG] ignoring unknown dirty type: ' + type);
+        // "groups" is not an app-state collection, but it is still a dirty bit
+        // the server expects to be cleared. Ignoring it meant the server
+        // re-announced it on every single connection, forever.
+        _whaDbg('[DBG] DIRTY type=' + type + ' — not an app-state collection, clearing the bit');
+        this._cleanDirtyBits(type);
         continue;
       }
       for (const c of mapped) collections.add(c);
@@ -1099,18 +1161,31 @@ class WhalibmobClient extends EventEmitter {
       try { _whaDbg('[DBG] IQ_ERROR content=' + JSON.stringify(node.content)); } catch(_) {}
     }
 
-    if      (tag === 'iq')           this._handleIq(node);
-    else if (tag === 'message')      this._handleMessage(node);
-    else if (tag === 'receipt')      this._handleReceipt(node);
-    else if (tag === 'ack')          this._handleAck(node);
-    else if (tag === 'notification') this._handleNotification(node);
-    else if (tag === 'presence')     this._handlePresence(node);
-    else if (tag === 'call')         this._handleCall(node);
-    else if (tag === 'ib')           this._handleIb(node);
-    else if (tag === 'success')      this.emit('session_refresh', { node }); // late success (re-auth)
-    else if (tag === 'failure')      this._handleFailure(node);
-    else if (tag === 'stream:error') this._handleStreamError(node);
-    else                             this.emit('node', node);
+    // One malformed stanza must not take the connection down with it.
+    //
+    // A throw here propagates out through the socket's frame reader, which
+    // reports it as a socket error — so a single unhandled shape in one
+    // notification looked like the transport failing, and every stanza queued
+    // behind it in the same offline batch was lost. Contain it: log the stanza
+    // that did it, tell the caller, carry on reading.
+    try {
+      if      (tag === 'iq')           this._handleIq(node);
+      else if (tag === 'message')      this._handleMessage(node);
+      else if (tag === 'receipt')      this._handleReceipt(node);
+      else if (tag === 'ack')          this._handleAck(node);
+      else if (tag === 'notification') this._handleNotification(node);
+      else if (tag === 'presence')     this._handlePresence(node);
+      else if (tag === 'call')         this._handleCall(node);
+      else if (tag === 'ib')           this._handleIb(node);
+      else if (tag === 'success')      this.emit('session_refresh', { node }); // late success (re-auth)
+      else if (tag === 'failure')      this._handleFailure(node);
+      else if (tag === 'stream:error') this._handleStreamError(node);
+      else                             this.emit('node', node);
+    } catch (err) {
+      _whaDbg('[DBG] NODE_HANDLER_ERR tag=' + tag + ' err=' + (err && err.message) +
+        ' attrs=' + JSON.stringify(node.attrs || {}));
+      this.emit('node_error', { tag, node, err });
+    }
   }
 
   // A stream error ends the connection; the reconnect in _onClose picks it up.
@@ -1122,16 +1197,55 @@ class WhalibmobClient extends EventEmitter {
   _handleStreamError(node) {
     const attrs  = (node && node.attrs) || {};
     const code   = attrs.code ? String(attrs.code) : null;
-    const reason = attrs.reason || code || 'unknown';
 
     if (code === '515') {
       _whaDbg('[DBG] STREAM_ERROR 515 — restart required after pairing, reconnecting');
-      this.emit('restart_required', { reason });
+      this.emit('restart_required', { reason: '515' });
       return;
     }
 
-    _whaDbg('[DBG] STREAM_ERROR code=' + code + ' reason=' + reason);
-    this.emit('stream_error', { reason, code });
+    // Most stream errors carry no code at all — the reason is a child element,
+    // and for <conflict> the type attribute on it says which kind. Reading only
+    // the attributes reported every one of these as "code=null reason=unknown",
+    // which is the same message for a session someone else took over and a
+    // session that was deleted.
+    const child       = Array.isArray(node.content) && node.content[0] ? node.content[0] : null;
+    const childTag    = child && child.description ? child.description : null;
+    const conflictType = childTag === 'conflict' && child.attrs
+      ? String(child.attrs.type || '') : null;
+
+    if (conflictType === 'replaced') {
+      // Another client opened a session for this account and the server handed
+      // it over. Reconnecting immediately just takes it back, and the two ends
+      // trade the session until one of them is stopped — so this one stands
+      // down and says why.
+      _whaDbg('[DBG] STREAM_ERROR conflict/replaced — another client took the session');
+      this._fatal = true;
+      this.emit('connection_replaced', {
+        message: 'Another client connected with this number and took over the ' +
+                 'session. Reconnecting would take it back and the two would ' +
+                 'keep displacing each other, so this connection has stopped. ' +
+                 'Close the other client, then connect again.'
+      });
+      this.disconnect();
+      return;
+    }
+
+    if (conflictType === 'device_removed') {
+      // The companion was unlinked from the phone. Same meaning as a 401.
+      _whaDbg('[DBG] STREAM_ERROR conflict/device_removed — unlinked');
+      this._fatal = true;
+      this.emit('auth_failure', {
+        reason: '401', location: null, loggedOut: true, node
+      });
+      this.disconnect();
+      return;
+    }
+
+    const reason = attrs.reason || conflictType || childTag || code || 'unknown';
+    _whaDbg('[DBG] STREAM_ERROR code=' + code + ' child=' + childTag +
+      ' conflict=' + conflictType + ' reason=' + reason);
+    this.emit('stream_error', { reason, code, conflictType, childTag, node });
   }
 
   // ─── IQ handling ──────────────────────────────────────────────────────────
@@ -1921,7 +2035,13 @@ class WhalibmobClient extends EventEmitter {
       // Server push: a contact's linked device list changed (they linked or
       // unlinked a tablet, desktop, etc.).  Invalidate that phone's cache entry
       // so the next send triggers a fresh usync IQ and reaches all their devices.
-      const fromJid   = attrs.from || '';
+      // BinaryNode decodes an AD-encoded JID into an object, not a string, so
+      // this has to be stringified before it can be split. It was not, and a
+      // <notification type="devices"> from a LID-addressed contact threw
+      // "fromJid.split is not a function" out of the node handler — taking the
+      // whole dispatch down with it, so every notification behind it in the
+      // offline queue was dropped too.
+      const fromJid   = String(attrs.from || '');
       const fromPhone = fromJid.split('@')[0].split(':')[0];
       if (fromPhone && this._devMgr) {
         this._devMgr._dcDel([fromPhone]);
@@ -1945,7 +2065,7 @@ class WhalibmobClient extends EventEmitter {
       // Server push: a contact re-registered WhatsApp (new identity key / new phone).
       // Their old Signal sessions are no longer valid — clear them and the device
       // cache so the next send builds a fresh pkmsg session from scratch.
-      const fromJid   = attrs.from || '';
+      const fromJid   = String(attrs.from || '');
       const fromPhone = fromJid.split('@')[0].split(':')[0];
       if (fromPhone && this._devMgr) {
         this._devMgr._dcDel([fromPhone]);
@@ -2140,10 +2260,17 @@ class WhalibmobClient extends EventEmitter {
       return;
     }
 
-    _whaDbg('[DBG] FAILURE reason=' + reason + ' location=' + loc);
-    this.emit('auth_failure', { reason, location: loc, node });
-    // The session is no longer valid — stop reconnecting and disconnect
-    this._fatal = true;
+    // Not every failure kills the session. whatsmeow's IsLoggedOut() marks the
+    // ones that do — 401, 403, 405, 406, 409 — and treats the rest as worth
+    // another attempt. A 500 or a 503 is the server having a bad minute; giving
+    // up on the session for that would be throwing away a working registration.
+    const LOGGED_OUT = ['401', '403', '405', '406', '409'];
+    const spent = LOGGED_OUT.includes(reason);
+
+    _whaDbg('[DBG] FAILURE reason=' + reason + ' location=' + loc +
+      ' loggedOut=' + spent);
+    this.emit('auth_failure', { reason, location: loc, loggedOut: spent, node });
+    this._fatal = spent;
     this._reconnecting = false;
     this.disconnect();
   }

package/lib/Registration.js

@@ -7,23 +7,109 @@ const curveJs = require('curve25519-js');
 const { getDeviceConfig } = require('./DeviceConfig');
 const attestation = require('./Attestation');
 
-// ---------- SOCKS5 / Tor support ----------
-// Set TOR_PROXY=socks5://127.0.0.1:9050 (or any socks5 host) to route all
-// WhatsApp registration traffic through Tor / a residential proxy.
-const SOCKS_LIB = '/home/runner/workspace/.config/npm/node_global/lib/node_modules/socks/build/index.js';
+// ---------- 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 || '';
+}
 
 async function httpPostViaSocks(path, body, waVersion, proxyUrl, authHeader) {
-  const url     = new URL(proxyUrl);
-  const pHost   = url.hostname;
-  const pPort   = parseInt(url.port) || 1080;
-  const dHost   = 'v.whatsapp.net';
-  const dPort   = 443;
+  const proxy = parseSocksProxy(proxyUrl);
+  const dHost = 'v.whatsapp.net';
+  const dPort = 443;
 
-  const { SocksClient } = require(SOCKS_LIB);
+  const { SocksClient } = loadSocks();
   const { socket: rawSocket } = await SocksClient.createConnection({
-    proxy:       { host: pHost, port: pPort, type: 5 },
+    proxy,
     command:     'connect',
-    destination: { host: dHost, port: dPort }
+    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
   });
 
   const tlsSocket = tls.connect({
@@ -50,16 +136,25 @@ async function httpPostViaSocks(path, body, waVersion, proxyUrl, authHeader) {
     `Content-Length: ${Buffer.byteLength(body)}`
   ];
   if (authHeader) reqLines.push(`Authorization: ${authHeader}`);
-  reqLines.push(`Connection: keep-alive`, '', body);
+  // close, not keep-alive: the response is read by waiting for the server to
+  // end the stream. Asking it to keep the connection open means that never
+  // happens and the request hangs until something else times out.
+  reqLines.push(`Connection: close`, '', body);
   const req = reqLines.join('\r\n');
 
   tlsSocket.write(req);
 
   const chunks = [];
   await new Promise((res, rej) => {
-    tlsSocket.on('data', d => chunks.push(d));
-    tlsSocket.on('end', res);
-    tlsSocket.on('error', rej);
+    const timer = setTimeout(() => {
+      tlsSocket.destroy();
+      rej(new Error('SOCKS proxy timed out reading ' + path));
+    }, 30000);
+    const finish = (fn, arg) => { clearTimeout(timer); fn(arg); };
+    tlsSocket.on('data',  d  => chunks.push(d));
+    tlsSocket.on('end',   () => finish(res));
+    tlsSocket.on('close', () => finish(res));
+    tlsSocket.on('error', e  => finish(rej, e));
   });
 
   const raw        = Buffer.concat(chunks);
@@ -510,7 +605,7 @@ function encryptPayload(plaintext) {
 // ---------- HTTP ----------
 
 function httpPost(path, body, waVersion, authHeader) {
-  const proxy = process.env.TOR_PROXY || process.env.SOCKS_PROXY || '';
+  const proxy = socksProxyUrl();
   if (proxy) return httpPostViaSocks(path, body, waVersion, proxy, authHeader);
 
   return new Promise((resolve, reject) => {
@@ -841,4 +936,4 @@ async function verifyCode(store, code) {
   throw new Error(`Verification failed: ${reason || JSON.stringify(result)}`);
 }
 
-module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, parsePhone, getCountryMeta, assertRegistrationKeys };
+module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };

package/lib/noise.js

@@ -444,9 +444,44 @@ class NoiseSocket extends EventEmitter {
 
         if (tag === 'failure') {
           const attrs  = (node && node.attrs) || {};
-          const reason = attrs.reason || attrs.location || '401';
-          const err    = new Error('WhatsApp auth failure: ' + reason);
+          const reason = String(attrs.reason || attrs.location || '401');
+          // Say what the code means. "auth failure: 401" sends people looking
+          // for a bug in the client; the credentials were rejected by the
+          // server, which is a different thing and has different remedies.
+          //
+          // The names and numbers are whatsmeow's ConnectFailureReason, which
+          // is the only place they are written down — WhatsApp publishes none
+          // of this. Codes marked "wipe" are the ones its IsLoggedOut() covers:
+          // the session is finished and retrying with it is pointless.
+          const FAILURE = {
+            '400': { wipe: false, text: 'generic failure.' },
+            '401': { wipe: true,  text: 'logged out. The session was unpaired ' +
+                     'server-side — nothing in the session file can revive it. ' +
+                     'For a linked device this means it was removed under ' +
+                     'Linked Devices; for a registered number it means the ' +
+                     'registration was taken over, usually by verifying the ' +
+                     'same number on the official app.' },
+            '402': { wipe: false, text: 'temporarily banned.' },
+            '403': { wipe: true,  text: "the account's primary device is gone " +
+                     '— it is no longer a multi-device account.' },
+            '405': { wipe: true,  text: 'client outdated — the announced ' +
+                     'version is not one the server accepts.' },
+            '406': { wipe: true,  text: 'banned.' },
+            '409': { wipe: true,  text: 'bad user agent — the client identified ' +
+                     'itself in a way the server rejects.' },
+            '413': { wipe: false, text: 'auth token expired.' },
+            '414': { wipe: false, text: 'auth token invalid.' },
+            '415': { wipe: false, text: 'not found.' },
+            '500': { wipe: false, text: 'server error — worth retrying.' },
+            '503': { wipe: false, text: 'service unavailable — worth retrying.' }
+          };
+          const info = FAILURE[reason];
+          const err = new Error('WhatsApp auth failure ' + reason +
+            (info ? ' — ' + info.text : ''));
           err.code     = reason;
+          // True when the session is spent and the caller should register or
+          // link again rather than retry.
+          err.loggedOut = !!(info && info.wipe);
           if (this._connectReject) {
             this._connectReject(err);
             this._connectResolve = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.6.4",
+  "version": "5.6.9",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API no web",
   "author": "Kunboruto50",
   "main": "index.js",
@@ -51,6 +51,7 @@
     "ws": "^8.21.1"
   },
   "optionalDependencies": {
-    "jimp": "^1.6.0"
+    "jimp": "^1.6.0",
+    "socks": "^2.8.9"
   }
 }