whalibmob 5.6.3 → 5.6.8

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,7 +576,8 @@ function attachEvents(client) {
       ? 'link again with /pair'
       : 're-register with /reg code';
     fail('session revoked: ' + f.reason + ' — ' + how);
-    _rl && (_rl.resume(), _rl.prompt(true));
+    _rl && _rl.resume();
+    notConnected();
   });
 
   // The server declined the client, not the session. Nothing to re-register.
@@ -585,7 +586,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 +717,7 @@ async function doConnectWeb(phone, opts) {
     client.once('auth_failure', () => clearInterval(keepAlive));
   } catch (e) {
     fail(e.message);
-    _rl.prompt();
+    notConnected();
   }
 }
 
@@ -735,7 +737,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 +747,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 +2078,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 +2096,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() {
@@ -2140,10 +2175,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/DeviceManager.js

@@ -901,7 +901,10 @@ class DeviceManager {
       }
     }
 
-    const deviceIds  = (this._dcGet(cacheKey) || []).filter(d => d !== 0);
+    // Same rule as the phone-addressed path: skip the device we are, not the
+    // device that happens to be numbered zero.
+    const selfDevice = this._ownDeviceIndex();
+    const deviceIds  = (this._dcGet(cacheKey) || []).filter(d => d !== selfDevice);
     const deviceJids = deviceIds.map(d => makeDeviceJid(lidUser, d, 'lid'));
     if (deviceJids.length === 0) return [];
 
@@ -1085,10 +1088,30 @@ class DeviceManager {
   //   On the first call we query usync, on all subsequent calls we return
   //   from cache — zero extra network round-trips.
   //
+  // Which device index this client occupies.
+  //
+  // A device registered over SMS is the account's primary and is always 0. A
+  // companion linked by pairing code occupies a numbered slot — and then
+  // device 0 is the owner's phone, which is a recipient like any other.
+  _ownDeviceIndex() {
+    const store = this._client && this._client._store;
+    return (store && store.deviceIndex) || 0;
+  }
+
   async ensureOwnDeviceSessions(ownPhone, signalProto, allowPkmsg = true) {
+    // Everything the account owns except the device doing the sending.
+    //
+    // This used to drop device 0 unconditionally, which is right only while we
+    // are device 0. As a companion it silently excluded the owner's own phone
+    // from every message we sent: the recipient got it, the phone did not, and
+    // it sat there showing "waiting for this message" forever. It also put our
+    // participant list out of step with the server's, which is what the phash
+    // mismatch on the ack was reporting.
+    const selfDevice = this._ownDeviceIndex();
+
     // Use cached own device list if it hasn't expired (5-min TTL matches _deviceCache)
     if (this._ownDeviceJids !== null && Date.now() < this._ownDeviceExpiry) {
-      const others = this._ownDeviceJids.filter(j => stripUser(j).device !== 0);
+      const others = this._ownDeviceJids.filter(j => stripUser(j).device !== selfDevice);
       return this._ensureSessions(others, signalProto, allowPkmsg);
     }
 
@@ -1097,7 +1120,7 @@ class DeviceManager {
     this._ownDeviceJids   = deviceJids;
     this._ownDeviceExpiry = Date.now() + 5 * 60 * 1000;
 
-    const others = deviceJids.filter(j => stripUser(j).device !== 0);
+    const others = deviceJids.filter(j => stripUser(j).device !== selfDevice);
     return this._ensureSessions(others, signalProto, allowPkmsg);
   }
 

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/messages/MessageSender.js

@@ -1259,8 +1259,8 @@ class MessageSender {
         : Promise.resolve([]),
       // Our own linked devices, in the address family the stanza is routed with.
       // ensureOwnDeviceSessions hands back @s.whatsapp.net JIDs, which cannot go
-      // into a stanza carrying addressing_mode='lid'; both helpers already leave
-      // out device 0.
+      // into a stanza carrying addressing_mode='lid'; both helpers leave out the
+      // device we are, which is device 0 only while we are the primary.
       useLid
         ? this._devMgr.ensureOwnLidDeviceSessions(myLidUser, ownPhone, this._signal)
         : this._devMgr.ensureOwnDeviceSessions(ownPhone, this._signal)
@@ -1275,8 +1275,17 @@ class MessageSender {
       const s = String(jid);
       return s.endsWith('@hosted') || s.endsWith('@hosted.lid');
     };
+    // The sending device counts in the enumeration even though it is not a
+    // recipient — and that is *this* device, not device 0. On a companion link
+    // the bare JID names the owner's phone, which arrives through ownTargets
+    // like every other device; adding it here again while leaving our own slot
+    // out would hash a set the server never computes.
+    const ownSelfJid = (useLid
+      ? this._client._ownDeviceLidJid()
+      : this._client._ownDeviceJid()) || selfJid;
+
     const enumeratedDevices = [...new Set(
-      [...memberDevices, ...lidDevices, ...ownTargets, selfJid]
+      [...memberDevices, ...lidDevices, ...ownTargets, ownSelfJid]
     )].filter(jid => !isHostedJid(jid));
 
     // The participant hash the server checks the fan-out against. whatsmeow puts

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.3",
+  "version": "5.6.8",
   "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"
   }
 }