whalibmob 5.12.15 → 5.12.16

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,7 @@ 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)
 
 ---
 
@@ -291,14 +292,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
@@ -4308,12 +4331,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 +4467,46 @@ 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. |
+| `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 version this session
+announces is not one the server accepts.
+```
+
+**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 one it no
+longer 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.
+
+Announce a current version instead:
+
+```sh
+WA_VERSION=2.26.30.3 wa connect 919634847671
+```
+
+Or put `WA_VERSION` in the `.env` file, where it applies to every command.
+
+**Where the stale version comes from.** Each platform learns its version
+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 token material came from | `wa apk-material --download` fetches the current one |
+
+So this is mostly an iOS story: a lookup that times out or is rate limited leaves
+a months-old fallback version 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
+```
 
 ## License
 

package/lib/Registration.js

@@ -575,6 +575,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 +1366,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 +1488,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 +1584,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/noise.js

@@ -375,7 +375,12 @@ class NoiseSocket extends EventEmitter {
         oc:                 false,
         userAgent: {
           platform:        (this.store.device && this.store.device.platform) || 1,
-          version:         this.store.version,
+          // 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.
+          version:         process.env.WA_VERSION || this.store.version,
           mcc:             _phoneMeta.mcc,
           mnc:             _phoneMeta.mnc,
           osVersion:       this.store.device.osVersion,
@@ -463,8 +468,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.
+            '405': { wipe: false, text: 'client outdated — the version this ' +
+                     'session announces is not one the server accepts. The ' +
+                     'session itself is fine: set WA_VERSION to a current ' +
+                     'WhatsApp version and connect again. On Android, ' +
+                     '`wa apk-material --download` picks the current one up on ' +
+                     'its own.' },
             '406': { wipe: true,  text: 'banned.' },
             '409': { wipe: true,  text: 'bad user agent — the client identified ' +
                      'itself in a way the server rejects.' },

package/package.json

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