whalibmob 5.12.15 → 5.12.17

package/.env.example

@@ -52,11 +52,13 @@
 
 # ─── WhatsApp version ────────────────────────────────────────────────────────
 # Pin the WhatsApp client version. When set, the live version lookup is skipped
-# entirely. Leave unset to fetch the current version automatically (recommended).
+# entirely, and this is what is announced on connect in place of the version
+# stored in the session. Leave unset to fetch the current version automatically.
 #
-# On Android this is normally not needed either way: the version is taken from
-# the APK the token material came from, since the token is signed over that
-# build. Setting this still overrides it.
+# On Android this is normally not needed: the version comes from the APK the
+# token material was read from. On iOS it is looked up on the App Store, and a
+# lookup that fails leaves a built-in fallback version in the session — which
+# the server refuses at connect with a 405. That is what this is for.
 # WA_VERSION=2.24.10.75
 
 # Override the static registration token. iOS only — Android has no static token

package/README.md

@@ -254,6 +254,8 @@ npm install -g whalibmob
   - [Android Profiles](#android-profiles)
   - [Custom Device Fields](#custom-device-fields)
   - [Version & Token Overrides](#version--token-overrides)
+  - [When the server answers 405 on connect](#when-the-server-answers-405-on-connect)
+  - [Finding out what a 405 objects to](#finding-out-what-a-405-objects-to)
 
 ---
 
@@ -291,14 +293,36 @@ wa registration --request-code 919634847671 --method wa_old
 ```
 
 **Registering as Android** is the same command with the platform named. Nothing
-else to prepare — see [what it does behind that one command](#registering-as-android):
+else to prepare — see [what it does behind that one command](#registering-as-android).
+
+Linux, macOS, Termux:
 
 ```sh
 WA_OS=android WA_DEVICE=samsung-s24-ultra wa registration --request-code 919634847671 --debug
 ```
 
-Set `WA_OS=android` in a `.env` file instead and the plain command is enough.
-`--debug` prints every request and reply, which is worth having the first time.
+Windows, Command Prompt — `set` on its own line, because `VAR=value` in front of
+a command is Unix syntax and Windows refuses it:
+
+```bat
+set WA_OS=android
+set WA_DEVICE=samsung-s24-ultra
+wa registration --request-code 919634847671 --debug
+```
+
+Windows, PowerShell:
+
+```powershell
+$env:WA_OS = "android"
+$env:WA_DEVICE = "samsung-s24-ultra"
+wa registration --request-code 919634847671 --debug
+```
+
+A `.env` file in the directory you run from works the same everywhere and saves
+repeating it — see [Device Quick Start](#device-quick-start). `--debug` prints
+every request and reply, which is worth having the first time: its first line
+names the platform that actually went out, so you can see whether the variables
+arrived.
 
 The variables only matter for the command that *creates* the session. What a
 session registered as is written into it, so the confirmation step and every
@@ -376,6 +400,14 @@ Use a custom session directory with `--session`:
 wa connect 919634847671 --session /data/my-sessions
 ```
 
+> [!IMPORTANT]
+> **If this is refused with `405`, do not re-register the number.** The account
+> is fine; the server declined the version the connect announced. Check for a
+> `WA_VERSION` in your shell or in a `.env` file in the directory you ran the
+> command from — it overrides the version the session registered with, and a
+> stale one left there refuses every connect from that directory. See
+> [When the server answers 405 on connect](#when-the-server-answers-405-on-connect).
+
 ### CLI Pairing Code
 
 If the number is already in use on a phone, or the verification SMS never arrives, link to the existing account instead. When it is not obvious which way you mean, `wa connect` asks:
@@ -2140,7 +2172,7 @@ Every event from the SMS primary API fires here too — `message`, `receipt`, `p
 | `pair_device` | `{ refs }` | the QR path produced reference strings |
 | `history_sync` | `{ syncTypeName, chats, contacts, pushNames, merged }` | a chunk of history arrived |
 | `history_sync_error` | `{ err, notification }` | a chunk could not be fetched or decrypted |
-| `client_rejected` | `{ reason, location, message }` | the server refused the client itself, not the session — `405` means the announced version is not accepted. Distinct from `auth_failure`, and there is nothing to re-pair. |
+| `client_rejected` | `{ reason, location, message }` | the server refused the client itself, not the session — `405` means the announced version is not accepted. Fires whether the refusal arrives during the handshake or once the stream is open, and the client stops retrying either way. Distinct from `auth_failure`, and there is nothing to re-pair. |
 
 ### Reading What the Phone Sent
 
@@ -4308,12 +4340,56 @@ Copy `.env.example` to `.env` in your project root and set the variables you nee
 
 ### Device Quick Start
 
-Emulate an Android Pixel 8 Pro:
+Emulate an Android Pixel 8 Pro. **The syntax for setting a variable differs per
+shell**, and getting it wrong is the most common reason a device profile appears
+to be ignored:
+
+**Linux, macOS, Termux** — set them for the one command:
 
 ```sh
 WA_OS=android WA_DEVICE=pixel_8_pro node your-app.js
+WA_OS=android WA_DEVICE=pixel_8_pro wa registration --request-code 919634847671
 ```
 
+**Windows, Command Prompt** — `set` first, one per line. `VAR=value` in front of
+a command is Unix syntax and Windows answers it with
+`'WA_OS' is not recognized as an internal or external command`:
+
+```bat
+set WA_OS=android
+set WA_DEVICE=pixel_8_pro
+wa registration --request-code 919634847671
+```
+
+Keep them on separate lines. Chaining with `&&` puts the space before the `&&`
+inside the value.
+
+**Windows, PowerShell**:
+
+```powershell
+$env:WA_OS = "android"
+$env:WA_DEVICE = "pixel_8_pro"
+wa registration --request-code 919634847671
+```
+
+**Anywhere, and the one worth preferring** — a `.env` file in the directory you
+run from, which behaves identically on every platform:
+
+```dotenv
+WA_OS=android
+WA_DEVICE=pixel_8_pro
+```
+
+```sh
+wa registration --request-code 919634847671
+```
+
+The CLI reads `.env` from the **current directory**, not from where whalibmob is
+installed, so `cd` to the directory holding it before running. Whichever way you
+choose, the first line of `--debug` output tells you whether it took:
+`User-Agent: WhatsApp/… Android/14 Device/Google-Pixel 8 Pro`. An `iOS/…` there
+means the variables never arrived.
+
 Or put the variables in a `.env` file. When using the **CLI** (`wa` command) the file is loaded automatically. When using the **library directly**, load it before `require('whalibmob')`:
 
 ```js
@@ -4400,8 +4476,137 @@ These variables override individual fields on top of the selected profile:
 
 | Variable | Description |
 |---|---|
-| `WA_VERSION` | Pin the WhatsApp version (e.g. `2.24.13.80`). Skips the live store fetch. |
-| `WA_STATIC_TOKEN` | Override the static token used in registration token computation. |
+| `WA_VERSION` | Pin the WhatsApp version (e.g. `2.24.13.80`). Skips the live store fetch, and is announced on connect **in place of the version stored in the session**. The CLI also reads it from a `.env` file in the working directory, so one left there is announced by every connect from that directory — which is how a working session starts being refused with [405](#when-the-server-answers-405-on-connect). Pin it deliberately, unset it when done. |
+| `WA_STATIC_TOKEN` | Override the static token used in registration token computation. iOS only — Android has no static token. |
+
+### When the server answers 405 on connect
+
+```
+WhatsApp auth failure 405 — client outdated. The server refused the version
+this connect announced, which was 2.24.10.75. That value came from WA_VERSION
+in the environment — the CLI also reads it out of a .env file in the directory
+it runs from — while the session itself holds 2.26.29.73.
+```
+
+**The session is fine and the number is still registered.** 405 is the server
+declining the *client*, not the account: the version being announced is not one
+it accepts. Registering the number again is the one move that cannot help — the
+same version would go out and be refused identically, at the cost of a real
+phone number and a code request.
+
+Connecting announces exactly one version, and there are only two places it can
+come from:
+
+| order | where the announced version comes from |
+|---|---|
+| 1 | `WA_VERSION`, from the shell **or from a `.env` file in the directory the command runs in** |
+| 2 | the version stored in the session file — what the number was registered with |
+
+Almost every 405 is the first line winning when nobody meant it to.
+
+#### Check `WA_VERSION` before anything else
+
+The CLI loads `.env` from the working directory before it does anything else, so
+a `WA_VERSION` left in that file is announced by *every* connect started from
+that directory — in place of the version the session registered with, which the
+server would have accepted. Nothing about the session changes, so the failure
+looks like a dead account and is not one.
+
+```sh
+grep -i wa_version .env ~/.env
+env | grep WA_VERSION
+```
+
+Remove or comment the line, then connect again. Since 5.12.17 you do not have to
+go looking: the CLI says so before it connects,
+
+```
+warning: WA_VERSION=2.24.10.75 is pinned (shell or .env in /home/you) —
+connecting announces it instead of the version stored in the session.
+```
+
+and a 405 names the version that went out and which of the two places it came
+from, because that decides the remedy — unset the override, or pin a newer one.
+
+Pin `WA_VERSION` deliberately and temporarily, to force one specific build:
+
+```sh
+WA_VERSION=2.26.30.3 wa connect 919634847671
+```
+
+Leaving it in `.env` means every session on that machine announces it until the
+day it goes stale, wherever those sessions came from.
+
+#### Keeping the session's own version current
+
+With no override, the session announces the version it was registered with, and
+each platform learns that differently:
+
+| | how the version is found | what happens when that fails |
+|---|---|---|
+| iOS | looked up on the App Store | falls back to a version compiled into the library, which goes stale |
+| Android | read from the APK the registration token material came from | `wa apk-material --download` fetches the current one |
+
+So a genuinely stale session version is mostly an iOS story: a lookup that times
+out or is rate limited leaves an old fallback in the session, and nothing says so
+until the handshake is refused. On Android the version travels with the APK, and
+refreshing the material refreshes the version with it:
+
+```sh
+wa apk-material --download
+```
+
+#### If every Android session is refused, whatever the version
+
+Then it is the library, not the version — update it. Until 5.12.15 the Android
+device profiles announced platform `3`, which is BlackBerry, a client WhatsApp
+stopped building in 2017. The server validates the announced app version
+*against the platform it was announced with*, so a current Android build arrived
+looking like an impossible BlackBerry one, and nothing in the failure named the
+platform. iOS announced `1` and was never affected.
+
+Sessions written before the fix repair themselves the next time they are loaded
+— the platform is derived from the profile's `os` rather than trusted from the
+file — so nothing has to be registered again.
+
+5.12.16 also brought the rest of the Android handshake in line with what a
+native Android client announces: no carrier (`mcc` and `mnc` are `000`), `en`
+and `US` as the locale, no `osBuildNumber`, the model rather than the model id
+as the device name, an uppercase `phoneId`, and `shortConnect`, `connectType`,
+`connectReason` and `connectAttemptCount` fixed at the values a real client
+sends on every connect — `connectType` had been sending `3`, which is not in the
+enum at all. iOS announces the real carrier and locale, which it has always been
+accepted with, and is unchanged.
+
+### Finding out what a 405 objects to
+
+When the version is right and the connect is still refused, stop guessing:
+`tools/diagnose-405.js` runs the login once per payload variation and prints
+what the server answered each time.
+
+```sh
+node tools/diagnose-405.js 5568936182750
+
+# installed globally:
+node $(npm root -g)/whalibmob/tools/diagnose-405.js 5568936182750
+```
+
+```
+reference shape, as-is            ok — LOGIN ACCEPTED
+  + the real carrier (mcc/mnc)    ok — LOGIN ACCEPTED
+  + the real locale               405   {"reason":"405"}
+```
+
+`405` means that row was refused, `401` means the client was accepted and only
+the credentials failed, `ok` means the login went through — so the first row
+that stops saying `ok` names the field the server objected to. Every row uses
+the session already on disk: nothing is registered, no code is requested, and
+the session is never written to. `--dry-run` prints the payload sizes without
+opening a socket.
+
+If *every* row is accepted while `wa connect` is refused, the payload is not the
+problem and the difference is in the environment the CLI reads and the tool does
+not — which is `WA_VERSION`, and the top of this section.
 
 ## License
 

package/cli.js

@@ -957,6 +957,17 @@ async function doConnectWeb(phone, opts) {
 
 async function doConnect(phone) {
   phone = normalizePhone(phone);
+
+  // A WA_VERSION left in .env is announced by every connect from this
+  // directory, in place of the version the session was registered with, and a
+  // stale one is refused with a 405 that says nothing about where the value
+  // came from. Say it out loud before connecting rather than after failing.
+  if (process.env.WA_VERSION) {
+    warn('WA_VERSION=' + process.env.WA_VERSION + ' is pinned (shell or .env in ' +
+         process.cwd() + ') — connecting announces it instead of the version ' +
+         'stored in the session. Unset it to use the session\'s own.');
+  }
+
   const client = new WhalibmobClient({ sessionDir: _sessDir });
   attachEvents(client);
 

package/lib/Client.js

@@ -705,6 +705,26 @@ class WhalibmobClient extends EventEmitter {
    * Anything the handshake marked as a spent session stops the loop here.
    */
   _onSocketError(err) {
+    // The server declined the client, not the session. The next attempt
+    // announces exactly the same thing and is refused exactly the same way, so
+    // this stops here instead of retrying once a second forever. _handleFailure
+    // already reads a 405 this way, but it only runs once a stream is open — a
+    // 405 during the handshake never reached it, which is why a refused client
+    // reconnected in a loop.
+    if (err && String(err.code) === '405') {
+      _whaDbg('[DBG] HANDSHAKE_REJECTED code=405 — client refused, not a dead session');
+      this._fatal       = true;
+      this._reconnecting = false;
+      this.emit('client_rejected', {
+        reason:   '405',
+        location: null,
+        message:  err.message,
+        node:     null
+      });
+      this.emit('error', err);
+      return;
+    }
+
     if (err && err.loggedOut) {
       _whaDbg('[DBG] HANDSHAKE_REJECTED code=' + err.code + ' — not retrying');
       this._fatal = true;

package/lib/DeviceConfig.js

@@ -3,7 +3,8 @@
 const {
   IOS_DEVICE,
   IOS_DEVICE_PROFILES,
-  ANDROID_DEVICE_PROFILES
+  ANDROID_DEVICE_PROFILES,
+  PLATFORM
 } = require('./constants');
 
 // Pre-build normalised lookup tables so that user-supplied profile keys in any
@@ -49,7 +50,7 @@ function getDeviceConfig() {
 
     return {
       os:              'android',
-      platform:        3,
+      platform:        PLATFORM.ANDROID,
       model:           process.env.WA_DEVICE_MODEL        || 'Samsung Galaxy S24 Ultra',
       manufacturer:    process.env.WA_DEVICE_MANUFACTURER || 'Samsung',
       osVersion:       process.env.WA_DEVICE_OS_VERSION   || '14',
@@ -68,7 +69,7 @@ function getDeviceConfig() {
 
   return {
     os:              'ios',
-    platform:        1,
+    platform:        PLATFORM.IOS,
     model:           process.env.WA_DEVICE_MODEL        || IOS_DEVICE.model,
     manufacturer:    process.env.WA_DEVICE_MANUFACTURER || IOS_DEVICE.manufacturer,
     osVersion:       process.env.WA_DEVICE_OS_VERSION   || IOS_DEVICE.osVersion,

package/lib/Registration.js

@@ -11,7 +11,7 @@ const { v4: uuidv4 } = require('uuid');
 const { getDeviceConfig } = require('./DeviceConfig');
 const AndroidApk  = require('./AndroidApk');
 const attestation = require('./Attestation');
-const { dbg: _whaDbg } = require('./logger');
+const { dbg: _whaDbg, warn: _whaWarn } = require('./logger');
 
 // ---------- Request envelope ----------
 //
@@ -499,12 +499,25 @@ async function fetchAndroidVersion() {
       {
         headers: {
           'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
-          'Accept-Language': 'en-US,en;q=0.9'
+          'Accept': 'text/html,application/xhtml+xml',
+          'Accept-Language': 'en-US,en;q=0.9',
+          // Only what every axios build decompresses. A default that asks for
+          // brotli and then gets bytes back undecoded is a page that parses to
+          // nothing.
+          'Accept-Encoding': 'gzip, deflate'
         },
+        responseType: 'text',
+        decompress:   true,
         timeout: 12000
       }
     );
-    const html = String(resp.data);
+    // Buffer when the response was compressed and axios handed the bytes back
+    // as-is. String() on a Buffer of gzip is a page no regex will ever match,
+    // which is how this came to fall through to a two-year-old fallback without
+    // saying a word.
+    const html = Buffer.isBuffer(resp.data)
+      ? resp.data.toString('utf8')
+      : String(resp.data);
 
     // Primary: first quoted 4-part version string matching WhatsApp's "2.x.x.x" scheme.
     // In Play Store JSON the current stable version appears first, before beta/history entries.
@@ -520,10 +533,41 @@ async function fetchAndroidVersion() {
       _cachedAndroidVersion = secondary[1];
       return secondary[1];
     }
-  } catch (_) {}
+
+    // Last resort: the highest 4-part version anywhere on the page. Play has
+    // rearranged this page before, and a version read from the wrong element
+    // still beats announcing one from two years ago.
+    const all = html.match(/2\.\d+\.\d+\.\d+/g);
+    if (all && all.length) {
+      const newest = all.sort(compareVersions).pop();
+      _whaDbg('[DBG] ANDROID_VERSION scraped from an unrecognised page layout: ' + newest);
+      _cachedAndroidVersion = newest;
+      return newest;
+    }
+
+    _whaWarn('could not read the current WhatsApp version off the Play Store page — ' +
+      'falling back to ' + ANDROID_VERSION_FALLBACK + '. If the server refuses the ' +
+      'client with 405, set WA_VERSION to a current version.');
+    return ANDROID_VERSION_FALLBACK;
+  } catch (err) {
+    _whaWarn('could not reach the Play Store to read the current WhatsApp version (' +
+      err.message + ') — falling back to ' + ANDROID_VERSION_FALLBACK + '.');
+  }
   return ANDROID_VERSION_FALLBACK;
 }
 
+// Numeric, part by part: '2.26.9.75' is older than '2.26.29.73', which a
+// lexicographic sort gets backwards.
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
 // Return the appropriate WhatsApp version for the active device.
 // If WA_VERSION is set in the environment, that value is always used.
 //
@@ -575,6 +619,39 @@ function tryLoadAndroidMaterial() {
   try { return loadAndroidMaterial(); } catch (_) { return null; }
 }
 
+/**
+ * Which platform a registration speaks.
+ *
+ * Once a session has an account behind it, or has a code outstanding, its
+ * platform is settled: the account was created as that, the token and the
+ * User-Agent have to keep saying so, and re-reading WA_OS could only break it.
+ * A confirmation run from a shell without the variables must not flip to iOS
+ * halfway through.
+ *
+ * Before that, a session holds nothing but keys. Re-running the code request is
+ * how you start it over, and the environment is how you say what to start it
+ * over as — so the environment decides, and this stops being consulted the
+ * moment a code goes out.
+ *
+ * When the two disagree on a session that is settled, that is said out loud.
+ * Silently ignoring WA_OS is how you end up watching an Android registration go
+ * out under an iOS User-Agent and not knowing why.
+ */
+function deviceForRegistration(store, opts) {
+  const env    = getDeviceConfig();
+  const stored = store && store.device;
+  const settled = !!(store && (store.registered || store.codePending));
+  if (!settled || !stored) return env;
+
+  if (stored.os !== env.os) {
+    const say = (opts && opts.onProgress) || (m => _whaDbg('[DBG] REG ' + m));
+    say('note: this session was started as ' + stored.os + ', so it stays ' + stored.os +
+        ' — WA_OS=' + env.os + ' does not apply to a number that is already part-way ' +
+        'through registering. Delete the session file to start it over as ' + env.os + '.');
+  }
+  return stored;
+}
+
 /**
  * Have the Android token material ready, fetching the APK if it is not.
  *
@@ -1333,11 +1410,7 @@ async function requestSmsCode(store, method, opts) {
   opts   = opts   || {};
   // Before the version is read, since on Android the version comes out of the
   // APK this fetches.
-  // What a session registered as is settled when it is created, so it is the
-  // store that decides — not whatever WA_OS the shell happens to carry now. A
-  // confirmation run from a shell without the variables would otherwise sign an
-  // Android registration with an iOS token.
-  const _device   = store.device || getDeviceConfig();
+  const _device   = deviceForRegistration(store, opts);
   await ensureAndroidMaterial(opts, _device);
   const waVersion = await fetchWaVersion(_device);
   store.version = waVersion;
@@ -1459,11 +1532,7 @@ async function verifyCode(store, code, opts) {
   opts = opts || {};
   // Normally already there from the code request, but a confirmation can be run
   // from a fresh shell that never made one.
-  // What a session registered as is settled when it is created, so it is the
-  // store that decides — not whatever WA_OS the shell happens to carry now. A
-  // confirmation run from a shell without the variables would otherwise sign an
-  // Android registration with an iOS token.
-  const _device   = store.device || getDeviceConfig();
+  const _device   = deviceForRegistration(store, opts);
   await ensureAndroidMaterial(opts, _device);
   const waVersion = await fetchWaVersion(_device);
   store.version = waVersion;
@@ -1559,7 +1628,7 @@ module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyC
 module.exports._http = { readHttpResponse, parseHttpResponse, decodeChunkedBody };
 
 // Token computation, exposed for tests. Not part of the public API.
-module.exports._token = { computeToken, androidMaterialPath, registrationHeaders, ensureAndroidMaterial };
+module.exports._token = { computeToken, androidMaterialPath, registrationHeaders, ensureAndroidMaterial, deviceForRegistration };
 
 // Challenge / two-factor internals, exposed for tests. Not part of the public API.
 module.exports._verify = {

package/lib/Store.js

@@ -1,13 +1,14 @@
 'use strict';
 
-const { warn: _whaWarn } = require('./logger');
+const { warn: _whaWarn, dbg: _whaDbg } = require('./logger');
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const curveJs = require('curve25519-js');
 const { v4: uuidv4 } = require('uuid');
-const { IOS_DEVICE, IOS_VERSION_FALLBACK, ANDROID_VERSION_FALLBACK } = require('./constants');
+const { IOS_DEVICE, IOS_VERSION_FALLBACK, ANDROID_VERSION_FALLBACK,
+        platformForOs } = require('./constants');
 const { getDeviceConfig } = require('./DeviceConfig');
 
 // ─────────────────────────────────────────────────────────
@@ -101,6 +102,25 @@ function createNewStore(phoneNumber) {
 // Serialisation / deserialisation
 // ─────────────────────────────────────────────────────────
 
+// The device profile as it should be announced, whatever a session file happens
+// to hold.
+//
+// `platform` is the number that goes into the handshake, and Android sessions
+// written before it was corrected carry 3 — BlackBerry — which the server
+// refuses with 405 on every connect. `os` is the part that was ever chosen
+// deliberately, so it decides, and a stale number is repaired the moment the
+// session is read. Nothing has to be registered again over it.
+function normaliseDevice(device) {
+  const merged   = Object.assign({}, IOS_DEVICE, device || null);
+  const expected = platformForOs(merged.os);
+  if (merged.platform !== expected) {
+    _whaDbg('[DBG] DEVICE_PLATFORM_FIXED os=' + merged.os +
+      ' ' + merged.platform + ' → ' + expected);
+    merged.platform = expected;
+  }
+  return merged;
+}
+
 function storeToJson(store) {
   if (!store) {
     throw new Error('storeToJson: store is undefined or null');
@@ -112,7 +132,7 @@ function storeToJson(store) {
 
   const name    = store.name || 'User';
   const version = store.version || IOS_VERSION_FALLBACK;
-  const device  = store.device ? Object.assign({}, IOS_DEVICE, store.device) : IOS_DEVICE;
+  const device  = normaliseDevice(store.device);
 
   const advIdentity = store.advIdentity
     ? store.advIdentity.toString('base64')
@@ -156,7 +176,7 @@ function storeFromJson(obj) {
 
   const name    = obj.name || 'User';
   const version = obj.version || IOS_VERSION_FALLBACK;
-  const device  = obj.device ? Object.assign({}, IOS_DEVICE, obj.device) : IOS_DEVICE;
+  const device  = normaliseDevice(obj.device);
 
   return {
     phoneNumber:    obj.phoneNumber,

package/lib/constants.js

@@ -42,17 +42,54 @@ const IOS_STATIC_TOKEN          = '0a1mLfGUIBVrMKF1RdvLI5lkRBvof6vn0fD2QRSM';
 const IOS_BUSINESS_STATIC_TOKEN = 'USUDuDYDeQhY4RF2fCSp5m3F6kJ1M2J8wS7bbNA2';
 
 // WhatsApp version fallbacks — used when live fetch fails.
+//
+// These are announced to the server, which refuses a build it does not
+// recognise, so a fallback that has gone stale is a connection that fails for a
+// reason nothing in the error names. Keep them within a few releases of what
+// the stores are actually serving; the live lookup is what normally decides.
 const IOS_VERSION_FALLBACK     = '2.26.9.75';
-const ANDROID_VERSION_FALLBACK = '2.24.13.80';
+const ANDROID_VERSION_FALLBACK = '2.26.29.73';
 
 // Safari UA for the iTunes lookup only.
 const IOS_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1';
 
+// ─── ClientPayload.UserAgent.Platform ────────────────────────────────────────
+//
+// The enum the handshake announces the client with, straight off the schema:
+//
+//   ANDROID = 0   IOS = 1   WINDOWS_PHONE = 2   BLACKBERRY = 3   ...   WEB = 14
+//
+// The server validates the announced app version *against this platform*, so a
+// wrong value here does not read as a wrong platform — it reads as an
+// impossible version and comes back as <failure reason="405"> ("client
+// outdated") before a single stanza is exchanged. Android sat on 3 (BlackBerry,
+// a client WhatsApp stopped building in 2017) and every Android session was
+// refused on connect with a version that was two weeks old, while iOS on 1 was
+// correct and never saw a 405. Nothing in the failure says which field was
+// wrong, which is what made it worth this many words.
+//
+// Anything that needs a platform number takes it from here.
+const PLATFORM = {
+  ANDROID: 0,
+  IOS:     1,
+  WEB:     14
+};
+
+// The platform an `os` string announces itself as. Unknown values fall back to
+// iOS, which is what a session with no device profile has always been.
+function platformForOs(os) {
+  return String(os).toLowerCase() === 'android' ? PLATFORM.ANDROID : PLATFORM.IOS;
+}
+
+// A note on the `deviceModelType` numbers in the profiles below: nothing reads
+// them. The proto's deviceModelType (field 16) is a string and is filled from
+// `modelId`; the proto's deviceType (field 15) is the DeviceType enum, which is
+// PHONE for every profile here. The numbers are left as they were found.
+
 // Default iOS device (iPhone 15 Pro, iOS 17.4.1).
-// platform 1 = iOS in WhatsApp's ClientPayload.UserAgent proto enum.
 const IOS_DEVICE = {
   os:              'ios',
-  platform:        1,
+  platform:        PLATFORM.IOS,
   model:           'iPhone 15 Pro',
   manufacturer:    'Apple',
   osVersion:       '17.4.1',
@@ -65,37 +102,37 @@ const IOS_DEVICE = {
 // Set WA_OS=ios  WA_DEVICE=<key>  in .env to select one.
 const IOS_DEVICE_PROFILES = {
   'iphone15pro': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 15 Pro', manufacturer: 'Apple',
     osVersion: '17.4.1', osBuildNumber: '21E236',
     modelId: 'iPhone16,1', deviceModelType: 2
   },
   'iphone15': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 15', manufacturer: 'Apple',
     osVersion: '17.4.1', osBuildNumber: '21E236',
     modelId: 'iPhone15,4', deviceModelType: 2
   },
   'iphone14': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 14', manufacturer: 'Apple',
     osVersion: '17.4.1', osBuildNumber: '21E236',
     modelId: 'iPhone14,2', deviceModelType: 2
   },
   'iphone14pro': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 14 Pro', manufacturer: 'Apple',
     osVersion: '17.4.1', osBuildNumber: '21E236',
     modelId: 'iPhone15,2', deviceModelType: 2
   },
   'iphone13': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 13', manufacturer: 'Apple',
     osVersion: '16.7.8', osBuildNumber: '20H343',
     modelId: 'iPhone14,5', deviceModelType: 2
   },
   'iphone12': {
-    os: 'ios', platform: 1,
+    os: 'ios', platform: PLATFORM.IOS,
     model: 'iPhone 12', manufacturer: 'Apple',
     osVersion: '15.8.3', osBuildNumber: '19H384',
     modelId: 'iPhone13,2', deviceModelType: 1
@@ -104,94 +141,93 @@ const IOS_DEVICE_PROFILES = {
 
 // ─── Android device profiles ───────────────────────────────────────────────
 // Set WA_OS=android  WA_DEVICE=<key>  in .env to select one.
-// platform 3 = ANDROID in WhatsApp's ClientPayload.UserAgent proto enum.
 const ANDROID_DEVICE_PROFILES = {
   'samsung-s24-ultra': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Samsung Galaxy S24 Ultra', manufacturer: 'Samsung',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'SM-S928B', deviceModelType: 2
   },
   'samsung-s24': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Samsung Galaxy S24', manufacturer: 'Samsung',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'SM-S921B', deviceModelType: 2
   },
   'samsung-s23': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Samsung Galaxy S23', manufacturer: 'Samsung',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'SM-S911B', deviceModelType: 2
   },
   'samsung-s23-ultra': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Samsung Galaxy S23 Ultra', manufacturer: 'Samsung',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'SM-S918B', deviceModelType: 2
   },
   'samsung-a55': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Samsung Galaxy A55', manufacturer: 'Samsung',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'SM-A556B', deviceModelType: 1
   },
   'pixel8pro': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Pixel 8 Pro', manufacturer: 'Google',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'Pixel 8 Pro', deviceModelType: 2
   },
   'pixel8': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Pixel 8', manufacturer: 'Google',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'Pixel 8', deviceModelType: 2
   },
   'pixel7': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Pixel 7', manufacturer: 'Google',
     osVersion: '14', osBuildNumber: 'TP1A.221005.002',
     modelId: 'Pixel 7', deviceModelType: 2
   },
   'pixel7a': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Pixel 7a', manufacturer: 'Google',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'Pixel 7a', deviceModelType: 1
   },
   'xiaomi14': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Xiaomi 14', manufacturer: 'Xiaomi',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: '23127PN0CG', deviceModelType: 2
   },
   'xiaomi13': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'Xiaomi 13', manufacturer: 'Xiaomi',
     osVersion: '13', osBuildNumber: 'TQ3A.230901.001',
     modelId: '2211133G', deviceModelType: 2
   },
   'oneplus12': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'OnePlus 12', manufacturer: 'OnePlus',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'CPH2573', deviceModelType: 2
   },
   'oneplus11': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'OnePlus 11', manufacturer: 'OnePlus',
     osVersion: '13', osBuildNumber: 'TQ3A.230901.001',
     modelId: 'CPH2449', deviceModelType: 2
   },
   'oppo-find-x7': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'OPPO Find X7', manufacturer: 'OPPO',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'CPH2599', deviceModelType: 2
   },
   'realme-gt5': {
-    os: 'android', platform: 3,
+    os: 'android', platform: PLATFORM.ANDROID,
     model: 'realme GT 5 Pro', manufacturer: 'realme',
     osVersion: '14', osBuildNumber: 'UP1A.231005.007',
     modelId: 'RMX3888', deviceModelType: 2
@@ -235,6 +271,8 @@ module.exports = {
   IOS_VERSION_FALLBACK,
   ANDROID_VERSION_FALLBACK,
   IOS_USER_AGENT,
+  PLATFORM,
+  platformForOs,
   IOS_DEVICE,
   IOS_DEVICE_PROFILES,
   ANDROID_DEVICE_PROFILES,

package/lib/noise.js

@@ -6,9 +6,11 @@ const EventEmitter = require('events');
 const curveJs      = require('curve25519-js');
 const { sha256 }   = require('@noble/hashes/sha256');
 const { hkdf }     = require('@noble/hashes/hkdf');
-const { MOBILE_PROLOGUE, WEB_PROLOGUE, WHATSAPP_HOST, WHATSAPP_PORT } = require('./constants');
+const { MOBILE_PROLOGUE, WEB_PROLOGUE, WHATSAPP_HOST, WHATSAPP_PORT,
+        platformForOs } = require('./constants');
 const { encodeHandshakeClientHello, encodeHandshakeClientFinish,
         decodeServerHello, encodeClientPayload } = require('./proto');
+const { dbg: _whaDbg } = require('./logger');
 const { parsePhone, getCountryMeta } = require('./Registration');
 
 // ─── CertChain validator ────────
@@ -66,6 +68,16 @@ function validateServerCert(payloadBuf) {
   }
 }
 
+// ─── ClientPayload enum values ───────────────────────────────────────────────
+//
+// ClientPayload.ConnectType, ClientPayload.ConnectReason and
+// ClientPayload.UserAgent.DeviceType. Named here because a bare number in the
+// payload is exactly how this file came to announce a connect type that is not
+// in the enum at all.
+const CONNECT_TYPE_WIFI               = 1;  // WIFI_UNKNOWN
+const CONNECT_REASON_USER_ACTIVATED   = 1;
+const DEVICE_TYPE_PHONE               = 0;
+
 // ─── Curve25519 DH helpers ───────────────────────────────────────────────────
 
 function stripKeyPrefix(pub) {
@@ -362,32 +374,79 @@ class NoiseSocket extends EventEmitter {
       // Auto-derive MCC/MNC and locale from the registered phone number so the
       // ClientPayload userAgent is never sent with the telltale '000'/'000' values.
       const _phoneMeta  = getCountryMeta(parsePhone(this.store.phoneNumber).cc);
+      const _device     = this.store.device || {};
+      const _isAndroid  = String(_device.os).toLowerCase() === 'android';
+      const _version    = process.env.WA_VERSION || this.store.version;
+
+      this._announcedVersion    = _version;
+      this._versionFromEnv      = !!process.env.WA_VERSION;
+      this._sessionVersion      = this.store.version;
+      _whaDbg('[DBG] ANNOUNCING version=' + _version +
+        (this._versionFromEnv ? ' (from WA_VERSION, session holds ' +
+          this.store.version + ')' : ' (from the session)') +
+        ' platform=' + platformForOs(_device.os));
 
       const payload = encodeClientPayload({
         username:           BigInt(this.store.phoneNumber),
         passive:            false,
         pushName:           this.store.registered ? (this.store.name || null) : null,
-        shortConnect:       (this.store.connectAttemptCount || 0) > 0,
-        connectType:        (this.store.connectAttemptCount || 0) > 0 ? 3 : 1,
-        connectReason:      1,
-        connectAttemptCount: (this.store.connectAttemptCount || 0),
+        // The next four are constants in the reference client: it announces
+        // shortConnect, WIFI_UNKNOWN, USER_ACTIVATED and attempt 0 on every
+        // connect, retries included. ConnectType is a closed set — 0
+        // CELLULAR_UNKNOWN, 1 WIFI_UNKNOWN, 100-112 for the named cellular
+        // radios — and a reconnect used to send 3, which is not in it.
+        shortConnect:       true,
+        connectType:        CONNECT_TYPE_WIFI,
+        connectReason:      CONNECT_REASON_USER_ACTIVATED,
+        connectAttemptCount: 0,
         device:             0,
         oc:                 false,
         userAgent: {
-          platform:        (this.store.device && this.store.device.platform) || 1,
-          version:         this.store.version,
-          mcc:             _phoneMeta.mcc,
-          mnc:             _phoneMeta.mnc,
-          osVersion:       this.store.device.osVersion,
-          manufacturer:    this.store.device.manufacturer,
-          device:          this.store.device.model,
-          osBuildNumber:   this.store.device.osBuildNumber,
+          // Which client this says it is. The server checks the announced
+          // version against *this* platform, so a wrong number here comes back
+          // as 405 "client outdated" and never mentions the platform at all —
+          // see PLATFORM in constants.js. Derived from `os` rather than read
+          // out of the session, so a session file written before this was
+          // corrected cannot keep announcing BlackBerry. ANDROID is 0, so the
+          // old `|| 1` fallback would also have quietly turned every Android
+          // session into an iOS one.
+          platform:        platformForOs(_device.os),
+          // The version the session was registered with, unless WA_VERSION says
+          // otherwise. Without that override there is no way out of a 405: the
+          // version lives in the session file, the server refuses it, and the
+          // only remaining move is to register the number again — which is the
+          // one thing that should never be the answer to a client-side problem.
+          //
+          // The override is also a way *into* a 405, and a quiet one: the CLI
+          // reads .env before anything else, so a WA_VERSION left in that file
+          // is announced by every connect from that directory while the session
+          // file still holds a version the server would have accepted. Both are
+          // remembered here so the failure can say which one went out.
+          version:         _version,
+          // Android announces no carrier and no locale of its own: the
+          // reference client sends 000/000 and en/US on this platform and is
+          // accepted, and this is the half that was being refused. iOS is
+          // accepted as it is and keeps sending the real values.
+          mcc:             _isAndroid ? '000' : _phoneMeta.mcc,
+          mnc:             _isAndroid ? '000' : _phoneMeta.mnc,
+          osVersion:       _device.osVersion,
+          manufacturer:    _device.manufacturer,
+          device:          _device.model,
+          // Not sent on Android by the reference client, which describes the
+          // handset with manufacturer and model alone. iOS does send it.
+          osBuildNumber:   _isAndroid ? null : _device.osBuildNumber,
+          // Uppercase on both platforms, even though the Android registration
+          // sends the same id lowercase — that asymmetry is the reference
+          // client's, not an oversight.
           phoneId:         this.store.fdid.toUpperCase(),
           releaseChannel:  0,
-          localeLanguage:  _phoneMeta.lg,
-          localeCountry:   _phoneMeta.lc,
-          deviceType:      0,
-          deviceModelType: this.store.device.modelId
+          localeLanguage:  _isAndroid ? 'en' : _phoneMeta.lg,
+          localeCountry:   _isAndroid ? 'US' : _phoneMeta.lc,
+          // DeviceType enum (field 15): PHONE. Every profile shipped here is a
+          // phone — the numeric `deviceModelType` on the profiles is unrelated
+          // to this and is read by nothing.
+          deviceType:      DEVICE_TYPE_PHONE,
+          deviceModelType: _device.modelId
         }
       });
 
@@ -463,8 +522,20 @@ class NoiseSocket extends EventEmitter {
             '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.' },
+            // Not a spent session, however much it looks like one. The server
+            // declined the *client*: the version we announced is not one it
+            // accepts. The registration behind the session is untouched, and
+            // telling people to register again over this costs them a real
+            // phone number for nothing — the same version would be announced
+            // and refused identically. _handleFailure already reads it this way
+            // once a session is up; this is the same code arriving during the
+            // handshake, and it was the one path still calling it revoked.
+            // Filled in below, where the version that actually went out is
+            // known. Telling everyone to set WA_VERSION was wrong exactly when
+            // it mattered most: a stale WA_VERSION is itself a way to get a 405,
+            // and the advice then read as "fix it by doing more of the thing
+            // that broke it".
+            '405': { wipe: false, text: 'client outdated.' },
             '406': { wipe: true,  text: 'banned.' },
             '409': { wipe: true,  text: 'bad user agent — the client identified ' +
                      'itself in a way the server rejects.' },
@@ -475,8 +546,32 @@ class NoiseSocket extends EventEmitter {
             '503': { wipe: false, text: 'service unavailable — worth retrying.' }
           };
           const info = FAILURE[reason];
+          let detail = info ? info.text : '';
+
+          // A refused client is a refused *version*, so name the one that went
+          // out and say where it came from. Which of the two it was decides the
+          // whole remedy, and the failure itself says neither.
+          // The companion path builds its own payload and never sets these, so
+          // it gets the short form rather than a sentence about undefined.
+          if (reason === '405' && !this._announcedVersion) {
+            detail += ' The server refused the version this connect announced.';
+          } else if (reason === '405') {
+            detail += ' The server refused the version this connect announced, ' +
+              'which was ' + this._announcedVersion + '.';
+            detail += this._versionFromEnv
+              ? ' That value came from WA_VERSION in the environment — the CLI ' +
+                'also reads it out of a .env file in the directory it runs from ' +
+                '— while the session itself holds ' + this._sessionVersion +
+                '. Unset WA_VERSION to announce the session\'s own version again.'
+              : ' It came from the session file. Announce a current one with ' +
+                'WA_VERSION, or on Android re-read it from the store with ' +
+                '`wa apk-material --download`.';
+            detail += ' Nothing about the session is wrong and there is nothing ' +
+              'to re-register.';
+          }
+
           const err = new Error('WhatsApp auth failure ' + reason +
-            (info ? ' — ' + info.text : ''));
+            (detail ? ' — ' + detail : ''));
           err.code     = reason;
           // True when the session is spent and the caller should register or
           // link again rather than retry.

package/lib/webproto.js

@@ -137,8 +137,11 @@ function encodeDeviceProps(opts) {
 // device id, no phone id. That absence is part of what marks the connection as
 // a companion rather than a primary.
 
-const PLATFORM_WEB     = 14;
-const PLATFORM_ANDROID = 0;
+// From the one table that holds them, so the mobile and web halves can never
+// drift apart on what a platform number means again.
+const { PLATFORM } = require('./constants');
+const PLATFORM_WEB     = PLATFORM.WEB;
+const PLATFORM_ANDROID = PLATFORM.ANDROID;
 
 function encodeAppVersion(v) {
   return Buffer.concat([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.12.15",
+  "version": "5.12.17",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API and web ",
   "author": "Kunboruto20",
   "main": "index.js",
@@ -11,6 +11,7 @@
     "index.js",
     "cli.js",
     "lib/**/*.js",
+    "tools/**/*.js",
     "README.md",
     "LICENSE",
     ".env.example"

package/tools/diagnose-405.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+'use strict';
+//
+// Asks the server which part of the login it objects to.
+//
+//   node tools/diagnose-405.js <phone> [--session <dir>]
+//
+// A 405 says "client outdated" and names nothing else, so the only way to find
+// out what it actually dislikes is to vary one thing at a time and read the
+// answer. Each row below is one login attempt with the session already on disk:
+// nothing is registered, no code is requested, and the session is never
+// written to. The verdict per row is what the server replied.
+//
+//   405  the client was refused — that row's combination is not accepted
+//   401  the client was accepted and only the credentials were rejected
+//   ok   the login succeeded
+//
+// Read it by comparing rows: the first row that stops saying 405 names the
+// field that was the problem.
+
+const path = require('path');
+const os   = require('os');
+
+const LIB = path.join(__dirname, '..', 'lib');
+const { loadStore }              = require(path.join(LIB, 'Store.js'));
+const { encodeClientPayload }    = require(path.join(LIB, 'proto.js'));
+const { NoiseSocket }            = require(path.join(LIB, 'noise.js'));
+const { parsePhone, getCountryMeta } = require(path.join(LIB, 'Registration.js'));
+const { platformForOs, PLATFORM }    = require(path.join(LIB, 'constants.js'));
+
+// Keep the whole <failure> node, not just the reason the library keeps.
+const BinaryNode = require(path.join(LIB, 'BinaryNode.js'));
+const decodeNode = BinaryNode.decodeNode;
+let lastNode = null;
+BinaryNode.decodeNode = function () {
+  lastNode = decodeNode.apply(this, arguments);
+  return lastNode;
+};
+
+const args    = process.argv.slice(2);
+const phone   = String(args[0] || '').replace(/\D/g, '');
+const sessArg = args.indexOf('--session');
+const sessDir = sessArg !== -1 ? args[sessArg + 1] : path.join(os.homedir(), '.waSession');
+
+if (!phone) {
+  console.error('usage: node tools/diagnose-405.js <phone> [--session <dir>]');
+  process.exit(2);
+}
+
+const store = loadStore(path.join(sessDir, phone + '.json'));
+if (!store) {
+  console.error('no session for ' + phone + ' in ' + sessDir);
+  process.exit(2);
+}
+
+const meta   = getCountryMeta(parsePhone(store.phoneNumber).cc);
+const device = store.device || {};
+const isAndroid = String(device.os).toLowerCase() === 'android';
+
+// What the reference client announces on Android, and the knobs that differ
+// between it and what this library used to send.
+function payloadFor(over) {
+  over = over || {};
+  const ua = {
+    platform:        over.platform !== undefined ? over.platform : platformForOs(device.os),
+    version:         over.version  || store.version,
+    mcc:             over.realCarrier ? meta.mcc : '000',
+    mnc:             over.realCarrier ? meta.mnc : '000',
+    osVersion:       device.osVersion,
+    manufacturer:    device.manufacturer,
+    device:          over.useModelId ? device.modelId : device.model,
+    osBuildNumber:   over.withBuild ? device.osBuildNumber : null,
+    phoneId:         over.lowerPhoneId ? store.fdid.toLowerCase() : store.fdid.toUpperCase(),
+    releaseChannel:  0,
+    localeLanguage:  over.realLocale ? meta.lg : 'en',
+    localeCountry:   over.realLocale ? meta.lc : 'US',
+    deviceType:      0,
+    deviceModelType: device.modelId
+  };
+  return encodeClientPayload({
+    username:            BigInt(store.phoneNumber),
+    passive:             false,
+    pushName:            store.registered ? (store.name || null) : null,
+    shortConnect:        true,
+    connectType:         1,
+    connectReason:       1,
+    connectAttemptCount: 0,
+    device:              0,
+    oc:                  false,
+    userAgent:           ua
+  });
+}
+
+function attempt(over) {
+  return new Promise(resolve => {
+    lastNode = null;
+    const sock = new NoiseSocket(store, { buildPayload: () => payloadFor(over) });
+    let settled = false;
+    const finish = (verdict) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { sock.close(); } catch (_) {}
+      const attrs = lastNode && lastNode.description === 'failure' && lastNode.attrs;
+      resolve(verdict + (attrs ? '   ' + JSON.stringify(attrs) : ''));
+    };
+    const timer = setTimeout(() => finish('timeout'), 30000);
+    sock.on('open',  () => finish('ok — LOGIN ACCEPTED'));
+    sock.on('error', e  => finish(e.code ? String(e.code) : e.message));
+    sock.connect().catch(() => {});
+  });
+}
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+// One variable at a time, starting from the reference client's exact shape.
+const ROWS = [
+  ['reference client, as-is',        {}],
+  ['  + the real carrier (mcc/mnc)', { realCarrier: true }],
+  ['  + the real locale',            { realLocale: true }],
+  ['  + osBuildNumber',              { withBuild: true }],
+  ['  + model id as the device',     { useModelId: true }],
+  ['  + lowercase phoneId',          { lowerPhoneId: true }],
+  ['everything the old code sent',   { realCarrier: true, realLocale: true, withBuild: true }],
+  ['announced as iOS',               { platform: PLATFORM.IOS }]
+];
+
+// --dry-run builds every row's payload and prints its size without opening a
+// socket, so the tool itself can be checked without talking to the server.
+if (args.includes('--dry-run')) {
+  console.log('session   +' + store.phoneNumber + '   (dry run — nothing is sent)\n');
+  for (const [label, over] of ROWS) {
+    console.log(label.padEnd(34) + payloadFor(over).length + ' bytes');
+  }
+  process.exit(0);
+}
+
+(async () => {
+  console.log('session   +' + store.phoneNumber);
+  console.log('platform  ' + (isAndroid ? 'android' : 'ios') + '  (' + platformForOs(device.os) + ')');
+  console.log('version   ' + store.version);
+  console.log('device    ' + device.manufacturer + ' / ' + device.model + ' / ' + device.modelId);
+  console.log('build     ' + (device.osBuildNumber || '—'));
+  console.log('');
+  for (const [label, over] of ROWS) {
+    process.stdout.write(label.padEnd(34));
+    const verdict = await attempt(over);
+    console.log(verdict);
+    await sleep(4000);
+  }
+  console.log('\nthe first row that is not 405 names what the server objected to.');
+  process.exit(0);
+})();