whalibmob 5.23.1 → 5.23.3

package/README.md

@@ -1,5 +1,28 @@
-<div align='center'>whalibmob is a pure JavaScript Node.js library for interacting with the WhatsApp Mobile API.</div>
-<div align='center'>v5.1.14</div>
+<div align="center">
+
+# whalibmob
+
+**A Node.js library for WhatsApp that can register a phone number of its own.**
+
+Every other JavaScript library links to an account that already exists on someone's phone.
+whalibmob does that too — but it can also take a bare phone number, request the SMS or voice
+code, and bring the account into being. Both transports, one API.
+
+[![npm](https://img.shields.io/npm/v/whalibmob?style=for-the-badge&color=25D366&label=npm)](https://www.npmjs.com/package/whalibmob)
+[![node](https://img.shields.io/node/v/whalibmob?style=for-the-badge&color=339933&label=node)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/whalibmob?style=for-the-badge&color=555555)](LICENSE)
+
+### Start here
+
+[![Register a number](https://img.shields.io/badge/Register_a_number-SMS_or_voice-25D366?style=for-the-badge)](#register-a-new-number)
+[![Link an account](https://img.shields.io/badge/Link_an_account-QR_or_pairing_code-128C7E?style=for-the-badge)](#linking-to-an-existing-account-pairing-code-or-qr)
+[![Use the CLI](https://img.shields.io/badge/Use_the_CLI-no_code_needed-075E54?style=for-the-badge)](#cli--getting-started)
+
+[![Library API](https://img.shields.io/badge/Library_API-Node.js-34B7F1?style=for-the-badge)](#library-api)
+[![Send messages](https://img.shields.io/badge/Send_messages-text_media_polls-34B7F1?style=for-the-badge)](#sending-messages)
+[![Handle events](https://img.shields.io/badge/Handle_events-incoming_%26_receipts-34B7F1?style=for-the-badge)](#handling-events)
+
+</div>
 
 ##
 
@@ -7,9 +30,9 @@
 
 
 
-CONTACT ME ON TELEGRAM  IF YOU WANT TO WORK WITH ME AND IF YOU HAVE PROBLEM WITH WHALIBMOB : @brtyu545
 
-**Need test numbers to try whalibmob with?** Message me on Telegram at **@brtyu545** — I can provide phone numbers for receiving SMS verification codes, so you can register and test whalibmob without using your own number.
+
+
 
 If you want News about whalibmob enter this whalibmob channel: https://t.me/+sHN4MDCyB7U5OWY0
 
@@ -26,9 +49,10 @@ If you want News about whalibmob enter this whalibmob channel: https://t.me/+sHN
 > [!IMPORTANT]
 > This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or affiliates. "WhatsApp" and related names are registered trademarks of their respective owners. Use at your own discretion.
 
-- whalibmob does not require a browser, Selenium, or any other external runtime — it communicates directly with WhatsApp using a **TCP socket** and the **Noise Protocol** handshake.
-- The library operates as a real **iOS mobile device**, using the Mobile API endpoint, which behaves differently from the Web API.
-- It **also speaks WhatsApp Web over a WebSocket**. When a number cannot receive an SMS, or is already in use on a phone, whalibmob can link itself to that existing account with an **8-character pairing code** and run as one of its linked devices — with full message history and the account's address book. See [Linking to an Existing Account](#linking-to-an-existing-account-pairing-code-or-qr). The API is identical in both modes.
+- **It registers numbers.** Give it a phone number that has never been on WhatsApp, request the code over SMS, voice call, flash call or an old WhatsApp account, confirm it, and the account exists — as an **Android or iOS device**, on the Mobile API. No phone, no scanning, no existing account to borrow. See [Register a New Number](#register-a-new-number).
+- **It also speaks WhatsApp Web**, over a WebSocket. When a number cannot receive an SMS, or is already live on a phone, whalibmob links itself to that account by **QR code** or an **8-character pairing code** and runs as one of its linked devices — with the full message history and the account's address book. See [Linking to an Existing Account](#linking-to-an-existing-account-pairing-code-or-qr).
+- **The API is identical in both modes.** Everything below — sending, media, groups, events — reads the same whichever way the session was created.
+- No browser, no Selenium, no external runtime. It talks to WhatsApp directly over a **TCP socket** with the **Noise Protocol** handshake.
 - Signal Protocol encryption is **fully inlined** in pure JavaScript — no native binaries, no node-gyp, runs anywhere Node.js runs.
 
 ## Install
@@ -1689,7 +1713,7 @@ if (result.status === 'ok') {
 }
 ```
 
-**Optional — let the code arrive by itself.** The two steps above are the whole flow, and nothing about them changes if you do nothing else. But because registration now sends a Firebase push token (see [The Push Token](#the-push-token)), WhatsApp *may* also deliver the six-digit code as a silent push. Open a listener for it before requesting the code, and the code can come back with nothing typed:
+**Optional — let the code arrive by itself.** The two steps above are the whole flow, and nothing about them changes if you do nothing else. But because an Android registration sends a Firebase push token (see [The Push Token](#the-push-token)), WhatsApp *may* also deliver the six-digit code as a silent push. Open a listener for it before requesting the code, and the code can come back with nothing typed — on an `WA_OS=android` profile; on iOS it resolves `null` straight away, since only Firebase is implemented:
 
 ```js
 const { receivePushCode } = require('whalibmob')
@@ -2579,7 +2603,9 @@ If that is refused too, the number has to go through the real app once, on a pho
 
 ## The Push Token
 
-Every WhatsApp on a real phone holds a Firebase push token. It is the address Google uses to wake the app, and no install exists without one — so a registration that ships no `push_token` describes a WhatsApp that cannot be notified, which is a device that does not exist.
+Every WhatsApp on a real phone holds a push token. It is the address the push network uses to wake the app, and no install exists without one — so a registration that ships no `push_token` describes a WhatsApp that cannot be notified, which is a device that does not exist.
+
+**This is an Android-profile feature.** Which push network an install uses follows from its platform: Android holds a *Firebase* token and keeps a stream open to Google, iOS holds an *APNs* token and keeps one open to Apple. They are not interchangeable, and the registration server sees both the token and the User-Agent naming the platform that sent it — an iPhone presenting a Firebase token describes a device nobody ships. Only the Firebase side is implemented here, so everything in this section applies when `WA_OS=android`. An iOS registration sends no `push_token` at all, which is the correct thing for a client with no push line, and every other part of the flow is unaffected.
 
 The token does two distinct jobs, and it is easy to conflate them:
 
@@ -2613,6 +2639,8 @@ Turn it off with `WA_FCM_PUSH=0`.
 
 This is the receiving end of job 2 above. When WhatsApp sends the code as a silent push, something has to be listening on the Firebase line to catch it — the same long-lived connection every Android phone keeps open to Google. `receivePushCode(store, device)` opens it: a TLS stream to `mtalk.google.com:5228` speaking the MCS protocol, logged in with the Firebase identity, resolving with the code the moment a push carrying it arrives.
 
+Like the token itself, this is Android-only. On an iOS profile `receivePushCode` resolves `null` immediately rather than holding a listener open on a line no push can reach, and `/reg push` says so and stops instead of waiting out its timeout. Check with `supportsPush(store.device)` if you want to branch on it.
+
 The order matters. Open the listener **first**, so the line is live before the code is requested; then request the code by whatever method; then await it.
 
 ```js

package/cli.js

@@ -2431,7 +2431,7 @@ async function handleLine(line) {
             break;
           }
           const method = (p[3] && !p[3].startsWith('--')) ? p[3] : 'sms';
-          const { receivePushCode } = require('./lib/fcm');
+          const { pushClientFor } = require('./lib/PushClient');
 
           sessionDirFor(_sessDir, ph, { create: true });
           const sessFile = storeFileFor(_sessDir, ph);
@@ -2439,6 +2439,23 @@ async function handleLine(line) {
           if (!store) { store = initAuthCreds(ph, { name: regName }); saveStore(store, sessFile); }
           if (!store.device) store.device = getDeviceConfig();
 
+          // Push verification needs a push line, and only Android has one here.
+          // An iOS session holds no Firebase identity, so the listener would sit
+          // for three minutes on a push that can never be routed to it. Say so
+          // now instead, and point at the two things that do work.
+          const pushClient = pushClientFor(store.device);
+          if (!pushClient.supportsPush) {
+            fail('push verification is not available for this device profile (' +
+                 (store.device.os || 'unknown') + ')');
+            out('  the code arrives over the push line of the platform being announced,');
+            out('  and only Android has one implemented (Firebase). iOS needs APNs.');
+            out('  either register this number on an Android profile:');
+            out('    WA_OS=android  (see /device) and re-run /reg push ' + ph);
+            out('  or use the ordinary path:  /reg code ' + ph + '  then  /reg confirm ' + ph + ' <code>');
+            break;
+          }
+          const receivePushCode = (s, d, o) => pushClient.receivePushCode(s, d, o);
+
           out('opening Firebase push listener (this can take a moment)...');
           // Open the listener first so the push has somewhere to land. onReady
           // fires once MCS is logged in — only then is it safe to ask for the

package/index.js

@@ -61,10 +61,21 @@ module.exports = {
   checkIfRegistered,
   requestSmsCode,
   verifyCode,
-  // Receive the verification code as a silent Firebase push, without an SMS —
-  // opens the MCS listener the native client keeps to Google. See "Receiving
-  // the code over push" in the README.
-  receivePushCode: (store, device, opts) => require('./lib/fcm').receivePushCode(store, device, opts),
+  // Receive the verification code as a silent push, without an SMS — opens the
+  // listener the native client of that platform keeps open. See "Receiving the
+  // code over push" in the README.
+  //
+  // Routed through the push client for the device's platform: Android opens the
+  // Firebase MCS stream, iOS resolves null because APNs is not implemented and
+  // an iOS session holds no Firebase identity to listen with.
+  receivePushCode: (store, device, opts) => {
+    const dev = device || (store && store.device);
+    return require('./lib/PushClient')
+      .pushClientFor(dev)
+      .receivePushCode(store, dev, opts);
+  },
+  // Whether the device profile can do push verification at all.
+  supportsPush: (device) => require('./lib/PushClient').supportsPush(device),
   assertRegistrationKeys,
   // Version fetch — use fetchWaVersion for device-aware (iOS or Android) fetching.
   // fetchIosVersion is kept for backward compatibility.

package/lib/PushClient.js

@@ -0,0 +1,106 @@
+'use strict';
+
+// ─── Push clients ─────────────────────────────────────────────────────────────
+//
+// Every real WhatsApp install can be woken by the server, and which line it is
+// woken on follows from the platform it runs on. An Android install holds a
+// Firebase token and keeps an MCS stream open to Google. An iOS install holds
+// an APNs token and keeps a courier stream open to Apple. The two are not
+// interchangeable, and the registration server sees both halves: the push token
+// in the body, and the User-Agent that says which platform sent it. An iPhone
+// presenting a Firebase token describes a device that does not exist.
+//
+// This module is the seam. `pushClientFor(device)` returns the client that
+// matches the device profile, so no caller has to reach for a transport by
+// name. Two implementations exist today:
+//
+//   android → ./fcm  (checkin → FIS install → register3, then MCS for the code)
+//   ios     → NONE   (APNs is not implemented; every push field is omitted)
+//
+// The NONE client is not a failure path — it is the correct answer for a
+// platform we cannot speak push for. It supplies nothing, `buildForm` drops the
+// null, and the registration body goes out without a push token rather than
+// with somebody else's.
+
+const { dbg: _whaDbg } = require('./logger');
+
+/**
+ * The push client for a platform we have no transport for.
+ *
+ * Supplies nothing and never performs I/O. Registration proceeds without any
+ * push field, which is what an install with no push line should send.
+ */
+const NONE_PUSH_CLIENT = {
+  platform: 'none',
+  supportsPush: false,
+
+  async getPushToken() {
+    return null;
+  },
+
+  async receivePushCode() {
+    return null;
+  }
+};
+
+/**
+ * The push client backed by Firebase Cloud Messaging, for Android profiles.
+ *
+ * Delegates to ./fcm, which owns the Google handshake and the MCS stream. The
+ * requires are lazy so that loading this module does not pull in the whole FCM
+ * stack for a session that never registers.
+ */
+const FCM_PUSH_CLIENT = {
+  platform: 'android',
+  supportsPush: true,
+
+  async getPushToken(store, device) {
+    return require('./fcm').getPushToken(store, device);
+  },
+
+  async receivePushCode(store, device, opts) {
+    return require('./fcm').receivePushCode(store, device, opts);
+  }
+};
+
+/**
+ * The push client matching a device profile.
+ *
+ * Android profiles get the Firebase client; everything else gets NONE. The
+ * choice is made on the device rather than on a global setting, because a
+ * process can register an Android session and an iOS session in turn and each
+ * has to present its own platform's push line — or none at all.
+ *
+ * @param {object} device  a device config; only `device.os` is read
+ * @returns {{platform: string, supportsPush: boolean,
+ *            getPushToken: function, receivePushCode: function}}
+ */
+function pushClientFor(device) {
+  if (device && device.os === 'android') return FCM_PUSH_CLIENT;
+
+  if (device && device.os) {
+    _whaDbg('[DBG] no push transport for ' + device.os + ' — push fields omitted');
+  }
+  return NONE_PUSH_CLIENT;
+}
+
+/**
+ * Whether this device profile can send and receive push at all.
+ *
+ * Callers that want to offer push verification check this first, so they can
+ * say why it is unavailable instead of opening a listener that nothing will
+ * ever reach.
+ *
+ * @param {object} device  a device config; only `device.os` is read
+ * @returns {boolean}
+ */
+function supportsPush(device) {
+  return pushClientFor(device).supportsPush;
+}
+
+module.exports = {
+  pushClientFor,
+  supportsPush,
+  NONE_PUSH_CLIENT,
+  FCM_PUSH_CLIENT
+};

package/lib/Registration.js

@@ -11,6 +11,7 @@ const { v4: uuidv4 } = require('uuid');
 const { getDeviceConfig } = require('./DeviceConfig');
 const AndroidApk  = require('./AndroidApk');
 const attestation = require('./Attestation');
+const { pushClientFor } = require('./PushClient');
 const { dbg: _whaDbg, warn: _whaWarn } = require('./logger');
 
 // ---------- Request envelope ----------
@@ -1207,6 +1208,20 @@ function buildClientMetrics(attempt) {
   return encodeURIComponent(json);
 }
 
+// A note on `push_code`, because it looks like an omission and is not.
+//
+// It is not the field that makes silent push verification work. The code
+// arrives over the push line *after* /code has been sent — that is the whole
+// point of it — so a code cannot be in the request that asks for it. Filling
+// this field by waiting for a push would hang /code forever on the push it is
+// itself supposed to trigger. The working flow is the other shape entirely:
+// open the MCS listener first, send /code, then await the push and hand what
+// arrives to /register. That is what `receivePushCode` and `/reg push` do.
+//
+// So the field stays absent. An empty value is worse than no value: the server
+// validates the shape of what it receives and answers a blank push_code with
+// bad_param/bad_format naming that field, while a field that is not there is
+// not validated at all. buildForm drops nulls, which is exactly what we want.
 function getRequestVerificationCodeParameters(store, method, meta, device, attempt) {
   if (device && device.os === 'android') {
     // Flash call is the one method whose delivery the server only routes when
@@ -1245,8 +1260,7 @@ function getRequestVerificationCodeParameters(store, method, meta, device, attem
       'manage_call_permission',     wantsFlash ? 'true' : 'false',
       'clicked_education_link',     'false',
       'aid',                        '',
-      // Omitted unless a push client supplies a real code — an empty value is
-      // rejected as bad_format, an absent field is not validated at all.
+      // Always absent — see the note above the function.
       'push_code',                  null
     ];
   }
@@ -1257,7 +1271,7 @@ function getRequestVerificationCodeParameters(store, method, meta, device, attem
     'sim_mcc',           meta.mcc,
     'sim_mnc',           meta.mnc,
     'jailbroken',        '0',
-    // Omitted unless a push client supplies a real code (see above).
+    // Always absent — see the note above the function.
     'push_code',         null,
     'cellular_strength', '1'
   ];
@@ -1357,11 +1371,17 @@ async function buildPayload(store, waVersion, useToken, extraPairs) {
       .update(Buffer.concat([store.identityId, stripKeyPrefix(store.noiseKeyPair.public)]))
       .digest()
   );
-  // The push token a real install always has. Acquired from Google once and
-  // then cached on the store, so the two registration steps share one. Returns
-  // null on any failure, which drops the field and leaves the body exactly as
-  // it was before push tokens were wired up.
-  const pushToken = await require('./fcm').getPushToken(store, device);
+  // The push token a real install always has, taken from the transport that
+  // matches this device's platform: Firebase for Android, nothing for iOS until
+  // APNs exists. Asking ./fcm directly would have put a Google token in an
+  // iPhone's registration body — a device that keeps an MCS stream to Google
+  // and announces itself as iOS is not a device anyone ships.
+  //
+  // Acquired once and cached on the store, so the two registration steps share
+  // one. Returns null on any failure or on a platform with no transport, which
+  // drops the field and leaves the body exactly as it was before push tokens
+  // were wired up.
+  const pushToken = await pushClientFor(device).getPushToken(store, device);
 
   const attestFields = await attestation.attestationFields(device, nonceB64, { pushToken });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.23.1",
+  "version": "5.23.3",
   "description": "Node.js library for WhatsApp — register a number over SMS, or link as a companion by QR. Signal E2E encryption, media, groups, channels.",
   "author": "Kunboruto20",
   "main": "index.js",