whalibmob 5.19.4 → 5.21.0

package/README.md

@@ -28,7 +28,7 @@ If you want News about whalibmob enter this whalibmob channel: https://t.me/+sHN
 
 - 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). The API is identical in both modes.
+- 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.
 - Signal Protocol encryption is **fully inlined** in pure JavaScript — no native binaries, no node-gyp, runs anywhere Node.js runs.
 
 ## Install
@@ -130,7 +130,7 @@ npm install -g whalibmob
     - [Device Attestation with Frida (optional)](#device-attestation-with-frida-optional)
     - [Connect](#connect)
       - [Client Options](#client-options)
-  - [Linking to an Existing Account (Pairing Code)](#linking-to-an-existing-account-pairing-code)
+  - [Linking to an Existing Account (Pairing Code or QR)](#linking-to-an-existing-account-pairing-code-or-qr)
     - [Requesting a Pairing Code](#requesting-a-pairing-code)
     - [Reconnecting a Linked Session](#reconnecting-a-linked-session)
     - [Choosing Your Own Code](#choosing-your-own-code)
@@ -1477,6 +1477,9 @@ wa> /connect 919634847671 pair
 # link to an existing account by 8-digit pairing code
 wa> /pair 919634847671
 
+# or link by scanning a QR drawn in the terminal
+wa> /qrcode 919634847671
+
 # with a code you chose yourself (exactly 8 characters)
 wa> /pair 919634847671 MYCODE12
 
@@ -1602,6 +1605,7 @@ wa> /quit
 | **Connection** | |
 | `/connect <phone> [sms\|pair]` | Connect to WhatsApp — picks the method from the session files when unset |
 | `/pair <phone> [code]` | Link to an existing account by 8-digit pairing code |
+| `/qrcode <phone>` | Link to an existing account by scanning a QR drawn in the terminal |
 | `/disconnect` | Disconnect current session |
 | `/reconnect` | Force reconnection |
 | `/session` | Show session info |
@@ -1668,6 +1672,27 @@ 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:
+
+```js
+const { receivePushCode } = require('whalibmob')
+
+// open the listener FIRST, so the push has somewhere to land
+const codePromise = receivePushCode(store, store.device, { timeoutMs: 180000 })
+
+await requestSmsCode(store, 'sms')        // any method; the push is a copy of the code
+const code = await codePromise            // the six digits, or null if no push came
+
+if (code) {
+  const result = await verifyCode(store, code)
+  if (result.status === 'ok') saveStore(result.store, sessFile)
+} else {
+  // no push this time — read the code the ordinary way and call verifyCode(store, code)
+}
+```
+
+This is purely additive: `receivePushCode` resolves `null` on a timeout or any failure, so the plain `requestSmsCode` / `verifyCode` path always stands behind it. Whether WhatsApp sends the silent push is the server's decision — see [Receiving the code over push](#receiving-the-code-over-push-without-typing-it) for what governs it. From the CLI the same thing is one command, `/reg push <phone>`.
+
 **When the code is not the end of it.** The server can answer a submitted code with a CAPTCHA, or with a demand for the account's two-step verification PIN. Neither is something the library can work out on its own, so both come back to you through optional handlers:
 
 ```js
@@ -2032,11 +2057,16 @@ The defaults cover an ordinary sender. Raise `sentCacheSize` if you push message
 
 If you see it, the cache is smaller than your in-flight window. An entry holds the encoded message, not the media it points at, so entries are small and raising the bound costs little memory.
 
-## Linking to an Existing Account (Pairing Code)
+## Linking to an Existing Account (Pairing Code or QR)
 
 Registering a number over SMS makes whalibmob that number's **own device**. Sometimes that is not what you want — the number is already in use on a phone, or the verification SMS never arrives. For those cases whalibmob can instead connect over a **WebSocket** and link itself to an account that already exists, exactly the way the WhatsApp Web and desktop clients do.
 
-You get an 8-character pairing code, the account owner types it into their phone, and from then on whalibmob is one of the account's linked devices. The whole library works the same afterwards — same client, same methods, same events.
+There are two ways to link, and they reach the same place:
+
+- **Pairing code** — whalibmob gives you an 8-character code, the owner types it into their phone.
+- **QR code** — whalibmob draws a QR, the owner scans it with the phone's camera.
+
+Both link the number as a companion device, both leave the whole library working the same afterwards — same client, same methods, same events. The only difference is what the owner does: type a code, or scan a square.
 
 > [!IMPORTANT]
 > The two modes are independent. SMS registration is unchanged and still the default; nothing about it is affected by linking. A single number can even have both a registered session and a linked session — they are stored in separate files and never share state.
@@ -2075,7 +2105,45 @@ On the phone that owns the number:
 
 **WhatsApp → Settings → Linked Devices → Link a device → Link with phone number instead**, then type the code.
 
-A few seconds after the code is accepted you will see `paired`, the server restarts the stream, and `connected` fires on the new connection. From that point on everything else in this document applies unchanged:
+### Linking by QR Code
+
+The QR path is the scan-to-connect alternative. You **do not** request a pairing code — you just connect and listen for the `qr` event. Because no code is asked for, the server volunteers a QR instead, and whalibmob turns it into a ready-to-render string:
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const qrcode = require('qrcode-terminal')          // npm install qrcode-terminal
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// a fresh QR string arrives here, and again each time the previous one expires
+client.on('qr', ({ qr, remaining }) => {
+  qrcode.generate(qr, { small: true })             // draw it in the terminal
+  console.log('scan it — refreshes on its own,', remaining, 'left before it expires')
+})
+
+client.on('qr_timeout', () => console.log('QR set expired — reconnect for a fresh one'))
+
+client.on('paired',    (p)  => console.log('scanned — linked as', p.jid))
+client.on('connected', ()   => console.log('ready'))
+
+// connect as a companion — and DO NOT request a pairing code
+await client.connectWeb('919634847671', { syncFullHistory: true })
+```
+
+On the phone that owns the number:
+
+**WhatsApp → Settings → Linked Devices → Link a device**, then point the camera at the QR.
+
+The `qr` string is what a WhatsApp camera reads: `ref,noise,identity,advSecret,platformId` — a one-time ref plus this client's public keys, comma-joined, the same fields WhatsApp Web itself renders. It rotates on its own (about a minute for the first, then shorter) until the account is scanned or the refs run out. `qrcode-terminal` is optional — without it you get the raw string on `qr` and can render it however you like (a PNG, a web page, an image in a chat). To emit the QR as a `wa.me/settings/linked_devices#…` link instead of the bare fields, pass `{ qrWrapUrl: true }` to `connectWeb`.
+
+Everything after the scan is identical to the pairing-code path: `paired`, a stream restart, then `connected`.
+
+### After the link — same for both paths
+
+A few seconds after the code is accepted (or the QR is scanned) you will see `paired`, the server restarts the stream, and `connected` fires on the new connection. From that point on everything else in this document applies unchanged:
 
 ```js
 await client.sendText('919876543210@s.whatsapp.net', 'sent from a linked device')
@@ -2119,9 +2187,11 @@ await client.connectWeb(phone, {
 | Event | Fires when |
 |---|---|
 | `pairing_code` | a code has been requested — `{ code, phoneNumber }` |
-| `paired` | the owner accepted the code — `{ jid, lid, deviceIndex, platform }` |
+| `qr` | a QR is ready to render — `{ qr, ref, ttlMs, remaining }`; fires again on each rotation |
+| `qr_timeout` | the QR refs ran out — reconnect for a fresh set |
+| `paired` | the owner accepted the code or scanned the QR — `{ jid, lid, deviceIndex, platform }` |
 | `restart_required` | the server is restarting the stream after pairing (normal; the reconnect is automatic) |
-| `pair_device` | the QR path produced reference strings — `{ refs }` |
+| `pair_device` | the raw QR reference strings, before they are turned into `qr` — `{ refs }` |
 | `history_sync` | a chunk of history arrived from the phone |
 
 ### Getting the History and the Address Book
@@ -2491,9 +2561,21 @@ 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 when a message arrives, and no install exists without one — so a registration that ships no `push_token` describes a WhatsApp that cannot be notified.
+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.
+
+The token does two distinct jobs, and it is easy to conflate them:
+
+1. **It makes the registration look real — always.** Every `/code` request now carries the token, whichever delivery method you ask for. The server sees an install that can be reached, not a headless client. This is the reason the token matters, and it applies to `sms`, `voice`, `wa_old` — all of them.
+2. **It can carry the code itself — sometimes.** Because you handed WhatsApp a direct line, WhatsApp *may* also push the six-digit code silently down it, so the app fills the code in on its own. This is why the code auto-completes on a real phone before you have read the SMS. It happens *alongside* the method you chose, not instead of it.
 
-Registration fetches a real one and sends it, in three plain HTTPS calls to Google:
+The delivery method and the push are not alternatives. You still choose how a human receives the code (`sms`, `voice`, `wa_old`); the push, when it comes, is a second silent copy of that same code sent straight to the app.
+
+```
+request a code ─┬─ method you chose  →  reaches a human   (SMS, a call, the existing WhatsApp)
+                └─ push_token line   →  reaches the app    (silent, auto-filled — if WhatsApp sends it)
+```
+
+Registration fetches a real token and sends it, in three plain HTTPS calls to Google:
 
 | Step | Endpoint | Yields |
 |---|---|---|
@@ -2509,6 +2591,40 @@ It runs once per number. The Firebase identity is cached on the session, because
 
 Turn it off with `WA_FCM_PUSH=0`.
 
+### Receiving the code over push, without typing it
+
+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.
+
+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
+const { receivePushCode, requestSmsCode, verifyCode } = require('whalibmob')
+
+// 1. open the listener first, so the push has somewhere to land
+const codePromise = receivePushCode(store, store.device, { timeoutMs: 180000 })
+
+// 2. request the code — any method. The push, if it comes, is a copy of it.
+await requestSmsCode(store, 'sms')          // or 'voice', 'wa_old', …
+
+// 3. if the push arrives, the code is here with nothing typed
+const code = await codePromise
+if (code) await verifyCode(store, code)
+else      { /* no push — read the code from SMS / the existing WhatsApp, then verifyCode */ }
+```
+
+From the CLI the whole sequence is one command:
+
+```
+/reg push <phone> [sms|voice]
+```
+
+It opens the listener, waits until it is logged in, requests the code, and confirms automatically if the push arrives — falling back to `/reg confirm <phone> <code>` when it does not.
+
+The connection carries a heartbeat and remembers the message ids it has seen, so a reconnect does not re-read a delivered code, the way the native client does. It resolves `null` on timeout, a refused login, or any failure — at which point you simply read the code the ordinary way and verify it. Like the token, it routes through the configured SOCKS proxy.
+
+> [!IMPORTANT]
+> Receiving the push is not the same as making WhatsApp send it. Whether WhatsApp pushes the code for a given request is the server's decision, and on a client shipping empty attestation it will often send the code only by the method you asked for (SMS, `wa_old`, a call) and no silent push. This listener catches the push correctly **when one is sent**; it cannot force that channel, and it never replaces the chosen method — it runs beside it. With a valid Play Integrity attestation in the request (`WA_FRIDA_HOST`), the server is more likely to include the silent push.
+
 ## Routing Traffic Through a Proxy
 
 Two reasons to want this. Registration is the part of the protocol most likely to be refused from a datacenter IP, so a residential exit helps with security blocks and undeterminable number statuses. And on a network that cannot reach WhatsApp at all, nothing works without one.

package/cli.js

@@ -663,11 +663,13 @@ const HELP = `
     /reg check   <phone>                              check if number has WhatsApp
     /reg code    <phone> [sms|voice|wa_old]           request verification code
     /reg code    <phone> email <address>              request code via email
+    /reg push    <phone> [sms|voice]                  request code and receive it over Firebase push
     /reg confirm <phone> <code>                       complete registration
 
   Connection
     /connect    <phone> [sms|pair]           connect to WhatsApp (asks which if unset)
     /pair       <phone> [code]               link to an existing account by 8-digit code
+    /qrcode     <phone>                       link to an existing account by scanning a QR
     /fixnumber                               re-file a session under the number WhatsApp uses
     /disconnect                              disconnect
     /reconnect                              force reconnection
@@ -1091,6 +1093,75 @@ async function doConnectWeb(phone, opts) {
   }
 }
 
+// Link by QR instead of a pairing code. Same companion connection, but nothing
+// asks for a code — the server volunteers a pair-device, the client turns each
+// ref into a QR, and this draws it in the terminal for the phone to scan.
+async function doConnectWebQr(phone) {
+  phone = normalizePhone(phone);
+  const client = new WhalibmobClient({ sessionDir: _sessDir });
+  attachEvents(client);
+
+  let renderQr = null;
+  try {
+    const qrcode = require('qrcode-terminal');
+    renderQr = (text) => qrcode.generate(text, { small: true }, (art) => out('\n' + art));
+  } catch (_) {
+    out('  (qrcode-terminal is not installed — printing the raw QR string instead)');
+    out('  install it for a scannable image:  npm install qrcode-terminal');
+    renderQr = (text) => { out(''); out(text); out(''); };
+  }
+
+  client.on('qr', ({ qr, remaining }) => {
+    out('');
+    hr();
+    out('  scan this from the phone that owns +' + phone + ':');
+    out('    WhatsApp → Settings → Linked Devices → Link a device');
+    hr();
+    renderQr(qr);
+    out('  the code refreshes on its own' +
+        (remaining ? ' (' + remaining + ' more before it expires)' : '') + '; waiting...');
+  });
+
+  client.on('qr_timeout', () => {
+    out('  the QR set expired — run /qrcode ' + phone + ' again for a fresh one');
+  });
+
+  client.once('paired', (pp) => {
+    out('');
+    out('  scanned — linked as ' + pp.jid + (pp.lid ? '  (' + pp.lid + ')' : ''));
+    out('  device slot ' + pp.deviceIndex + (pp.platform ? '  ·  primary is ' + pp.platform : ''));
+    out('  finishing handshake...');
+  });
+
+  client.on('history_sync', (r) => {
+    out('  history  ' + r.syncTypeName +
+        '  chats=' + r.chats.length + '  contacts=' + r.contacts.length);
+  });
+
+  client.once('connected', () => {
+    _client = client;
+    _phone  = phone;
+    out('connected as +' + phone + '  (web / companion)');
+    _rl.setPrompt('wa +' + phone + '> ');
+    _rl.prompt();
+  });
+
+  const alreadyLinked = hasWebSession(phone);
+  try {
+    // connectWeb WITHOUT requestPairingCode — that is what makes the server
+    // offer the QR pair-device instead of waiting on a code.
+    await client.connectWeb(phone, { syncFullHistory: true });
+    if (alreadyLinked) out('session already linked — reconnecting');
+
+    const keepAlive = setInterval(() => {}, 10000);
+    client.once('connected',    () => clearInterval(keepAlive));
+    client.once('auth_failure', () => clearInterval(keepAlive));
+  } catch (e) {
+    fail(e.message);
+    notConnected();
+  }
+}
+
 async function doConnect(phone) {
   phone = normalizePhone(phone);
 
@@ -1323,6 +1394,23 @@ async function handleLine(line) {
         break;
       }
 
+      case '/qrcode':
+      case '/qr': {
+        const ph = p[1] || _phone;
+        if (!ph) {
+          fail('usage: /qrcode <phone>');
+          out('  links the number as a companion by QR instead of a pairing code');
+          out('  a QR is drawn in the terminal — scan it from the phone that owns');
+          out('  the number:  WhatsApp → Linked Devices → Link a device');
+          out('  example: /qrcode 40756469325');
+          break;
+        }
+        if (_client && _client.connected) { fail('already connected — /disconnect first'); break; }
+        out('connecting...');
+        await doConnectWebQr(ph);
+        break;
+      }
+
       case '/disconnect':
         if (_client) { _client.disconnect(); _client = null; _phone = null; }
         _rl.setPrompt('wa> ');
@@ -2329,8 +2417,76 @@ async function handleLine(line) {
             fail('verification failed  ' + JSON.stringify(r));
           }
         }
+        else if (sub === 'push') {
+          // Full push flow: open the MCS listener, request the code, and wait
+          // for it to arrive over Firebase instead of by SMS. Falls back to the
+          // ordinary code path automatically when no push comes.
+          const ph = normalizePhone(p[2]);
+          if (!ph) {
+            fail('usage: /reg push <phone> [sms|voice] [--name "Your Name"]');
+            out('  opens the Firebase push listener, requests a code, and waits for');
+            out('  it to arrive over push. If it does, registration is confirmed');
+            out('  automatically. If no push comes, request the code normally with');
+            out('  /reg code and confirm it with /reg confirm.');
+            break;
+          }
+          const method = (p[3] && !p[3].startsWith('--')) ? p[3] : 'sms';
+          const { receivePushCode } = require('./lib/fcm');
+
+          sessionDirFor(_sessDir, ph, { create: true });
+          const sessFile = storeFileFor(_sessDir, ph);
+          let store = loadStore(sessFile);
+          if (!store) { store = initAuthCreds(ph, { name: regName }); saveStore(store, sessFile); }
+          if (!store.device) store.device = getDeviceConfig();
+
+          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
+          // code.
+          let ready = false;
+          const codePromise = receivePushCode(store, store.device, {
+            timeoutMs: 180000,
+            onReady: () => { ready = true; out('  push listener ready — requesting code'); }
+          });
+
+          // Give the listener a few seconds to log in before requesting. If it
+          // has not, request anyway — SMS still works, and the push may yet come.
+          const waitReady = async () => {
+            for (let i = 0; i < 40 && !ready; i++) await new Promise(r => setTimeout(r, 250));
+          };
+          await waitReady();
+          if (!ready) out('  listener not ready yet — requesting code anyway (SMS fallback stands)');
+
+          out('requesting ' + method + ' code for +' + ph + '...');
+          const r = await requestSmsCode(store, method, { onProgress: out, name: regName });
+          store.codePending = true;
+          saveStore(store, sessFile);
+          out('  status  ' + (r && r.status));
+
+          out('waiting for the code over push (up to 3 min; Ctrl-C to stop and use /reg confirm)...');
+          const code = await codePromise;
+          if (!code) {
+            out('no code arrived over push — WhatsApp likely sent it by SMS.');
+            out('  read the SMS and run:  /reg confirm ' + ph + ' <code>');
+            saveStore(store, sessFile);
+            break;
+          }
+          out('code received over push: ' + code + ' — confirming...');
+          const v = await verifyCode(store, code,
+            Object.assign(registrationPrompts(), { onProgress: out, name: regName }));
+          if (v && (v.status === 'ok' || v.status === 'sent' || v.status === 'verified')) {
+            const finalStore = v.store || store;
+            finalStore.registered = true; finalStore.codePending = false;
+            const savedPhone = String(finalStore.phoneNumber || ph);
+            saveStore(finalStore, storeFileFor(_sessDir, savedPhone));
+            out('registered via push  session saved');
+            out('now run: /connect ' + savedPhone);
+          } else {
+            fail('verification failed  ' + JSON.stringify(v));
+          }
+        }
         else {
-          fail('usage: /reg check|code|confirm ...');
+          fail('usage: /reg check|code|push|confirm ...');
         }
         break;
       }

package/index.js

@@ -61,6 +61,10 @@ 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),
   assertRegistrationKeys,
   // Version fetch — use fetchWaVersion for device-aware (iOS or Android) fetching.
   // fetchIosVersion is kept for backward compatibility.

package/lib/Client.js

@@ -840,6 +840,10 @@ class WhalibmobClient extends EventEmitter {
 
     if (opts.syncFullHistory !== undefined) this._store.syncFullHistory = !!opts.syncFullHistory;
     if (opts.browser) this._store.browser = opts.browser;
+    // Emit the QR as a wa.me/settings/linked_devices# link rather than the bare
+    // comma-joined fields. Off by default — the bare form is what WhatsApp Web
+    // itself renders and the most widely scannable.
+    if (opts.qrWrapUrl) this._qrWrapUrl = true;
 
     // Announce the revision the web client is actually on.
     //
@@ -1177,6 +1181,8 @@ class WhalibmobClient extends EventEmitter {
    * that is when history starts arriving.
    */
   _handlePairSuccess(node) {
+    // The phone accepted a scan (or a code) — no more QRs to show.
+    this._stopQrRotation();
     const { configureSuccessfulPairing } = require('./CompanionPairing');
     try {
       const result = configureSuccessfulPairing(node, {
@@ -1222,9 +1228,15 @@ class WhalibmobClient extends EventEmitter {
   /**
    * <iq><pair-device> — the QR path.
    *
-   * We do not display QR codes, but the node still has to be acknowledged or
-   * the server keeps re-sending refs. The refs are surfaced as an event so a
-   * caller that wants to render a QR can.
+   * The server volunteers this to an unpaired companion that has not asked for
+   * a pairing code. It carries a list of one-time refs; each pairs with our
+   * keys to form one QR string. The node has to be acknowledged or the server
+   * keeps resending it.
+   *
+   * The refs are surfaced raw on `pair_device` for anything that wants them,
+   * and turned into ready-to-render QR strings on `qr` — one now, then a fresh
+   * one each time the current ref expires, until the list runs out. Scanning
+   * any of them links the device.
    */
   _handlePairDevice(node) {
     const id = node.attrs && node.attrs.id;
@@ -1240,6 +1252,65 @@ class WhalibmobClient extends EventEmitter {
           .map(c => (Buffer.isBuffer(c.content) ? c.content.toString('utf8') : String(c.content)))
       : [];
     this.emit('pair_device', { refs });
+
+    this._startQrRotation(refs);
+  }
+
+  // Turn the server's refs into QR strings and emit them one at a time.
+  //
+  // A ref is single-use and short-lived, so the first is shown at once and each
+  // later one only when the current has aged out — mirroring the phone-facing
+  // client, which shows a QR for ~60s and then rotates. When the refs run out
+  // the account has to reconnect for a fresh set, which is surfaced as
+  // `qr_timeout` rather than left hanging.
+  _startQrRotation(refs) {
+    this._stopQrRotation();
+    if (!Array.isArray(refs) || refs.length === 0) return;
+
+    const { buildQrData } = require('./QrPairing');
+    const crypto = require('crypto');
+
+    // The adv secret rides inside the QR and is what the phone signs the
+    // account proof with; pair-success verifies against it. The pairing-code
+    // path derives its own, but the QR path has none until here, so mint a
+    // random 32 bytes once and keep it for the whole attempt.
+    if (!this._store.advSecretKey) {
+      this._store.advSecretKey = crypto.randomBytes(32).toString('base64');
+      this._saveWebStore();
+    }
+
+    const { WEB_BROWSER } = require('./constants');
+    const noiseB64    = stripKeyPrefix(this._store.noiseKeyPair.public).toString('base64');
+    const identityB64 = stripKeyPrefix(this._store.identityKeyPair.public).toString('base64');
+    const advB64      = this._store.advSecretKey;
+    const browser     = this._store.browser || WEB_BROWSER;
+    const wrap        = !!this._qrWrapUrl;
+
+    const queue = refs.slice();
+    let first = true;
+
+    const showNext = () => {
+      const ref = queue.shift();
+      if (!ref) {
+        _whaDbg('[DBG] QR refs exhausted — reconnect for a fresh set');
+        this._stopQrRotation();
+        this.emit('qr_timeout');
+        return;
+      }
+      const qr = buildQrData(ref, noiseB64, identityB64, advB64, browser, { wrap });
+      // 60s for the first, 20s for each after — the reference client's cadence.
+      const ttlMs = first ? 60000 : 20000;
+      first = false;
+      _whaDbg('[DBG] QR emitted (ref …' + ref.slice(-6) + ', ' + queue.length + ' left)');
+      this.emit('qr', { qr, ref, ttlMs, remaining: queue.length });
+      this._qrTimer = setTimeout(showNext, ttlMs);
+    };
+
+    showNext();
+  }
+
+  _stopQrRotation() {
+    if (this._qrTimer) { clearTimeout(this._qrTimer); this._qrTimer = null; }
   }
 
   /**
@@ -1325,6 +1396,7 @@ class WhalibmobClient extends EventEmitter {
     if (!(opts && opts.reconnect)) this._closing = true;
     this._reconnecting = false;
     this._reconnectTry = 0;
+    this._stopQrRotation();
     this._stopTimers();
     if (this._socket) {
       try { this._socket.close(); } catch (_) {}

package/lib/QrPairing.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// QR-code companion login, the scan-to-connect alternative to the pairing code.
+//
+// Both paths link the same way — as a companion device on the web transport —
+// and diverge only in how the primary phone is told to trust this client:
+//
+//   pairing code   the client asks for an 8-character code, the user types it
+//                  into WhatsApp → Linked devices → Link with phone number
+//   QR code        the server volunteers a set of refs, the client renders one
+//                  as a QR, the user points the phone's camera at it
+//
+// The QR is a short string the WhatsApp camera reads. It carries everything the
+// phone needs to authorise this device: a one-time ref, this client's public
+// noise and identity keys, and the adv secret it will sign the account proof
+// with. The phone does the linking; the client only has to present the string.
+//
+// The wire format is the one the native web client and every maintained web
+// library produce:
+//
+//   ref,<noise pub b64>,<identity pub b64>,<adv secret b64>,<platform id>
+//
+// The platform id is the companion "web client type": Chrome is 1, Edge 2,
+// Firefox 3, and so on. WhatsApp Web itself renders exactly these comma-joined
+// fields, so that is the default; some clients wrap them in a
+// wa.me/settings/linked_devices# link, which is offered as an option.
+
+// Companion web-client type, keyed by browser name. Matches the ids the phone
+// expects; anything unknown is "other web client".
+const COMPANION_WEB_CLIENT = {
+  CHROME: 1, EDGE: 2, FIREFOX: 3, IE: 4, OPERA: 5, SAFARI: 6,
+  ELECTRON: 7, UWP: 8, OTHER: 9
+};
+
+// A [os, browserName] description → the numeric platform id in the QR.
+function companionPlatformId(browser) {
+  const os   = browser && browser[0];
+  const name = String((browser && browser[1]) || 'Chrome');
+  if (name === 'Desktop') return os === 'Windows' ? COMPANION_WEB_CLIENT.UWP : COMPANION_WEB_CLIENT.ELECTRON;
+  const key = name.toUpperCase();
+  return COMPANION_WEB_CLIENT[key] !== undefined ? COMPANION_WEB_CLIENT[key] : COMPANION_WEB_CLIENT.OTHER;
+}
+
+/**
+ * Build the string a WhatsApp camera scans to link this device.
+ *
+ * @param {string} ref            one ref from the server's pair-device node
+ * @param {string} noisePubB64    base64 of the 32-byte noise public key
+ * @param {string} identityPubB64 base64 of the 32-byte signed-identity public key
+ * @param {string} advB64         base64 of the 32-byte adv secret
+ * @param {Array}  browser        [os, browserName, version]
+ * @param {object} [opts]         { wrap } — prefix the wa.me linked-devices URL
+ * @returns {string}
+ */
+function buildQrData(ref, noisePubB64, identityPubB64, advB64, browser, opts) {
+  const fields = [ref, noisePubB64, identityPubB64, advB64, String(companionPlatformId(browser))].join(',');
+  return (opts && opts.wrap) ? 'https://wa.me/settings/linked_devices#' + fields : fields;
+}
+
+module.exports = { buildQrData, companionPlatformId, COMPANION_WEB_CLIENT };

package/lib/fcm-mcs.js

@@ -0,0 +1,360 @@
+'use strict';
+
+// MCS — the long-lived Firebase connection that carries WhatsApp's verification
+// code as a silent push, so a number can be registered without an SMS.
+//
+// The push token from lib/fcm.js is the address; this is the mailbox. WhatsApp
+// sends the six-digit code as a data message over Firebase Cloud Messaging, and
+// the only way to receive it is to hold a connection open to Google's MCS
+// endpoint and speak its binary protocol — the same one every Android phone
+// keeps running in the background.
+//
+// The wire format, tag for tag, is WhatsApp's own client's:
+//
+//   connect TLS to mtalk.google.com:5228
+//   → write one version byte (41), then a LoginRequest frame
+//   ← read one version byte, then a LoginResponse frame
+//   then frames both ways: [tag:1][length:varint][protobuf payload]
+//
+//   tags: 0 heartbeat-ping  1 heartbeat-ack  2 login-request
+//         3 login-response  4 close          7 iq  8 data-message
+//
+// The code rides on a data-message whose appData carries a
+// key="registration_code". Everything else — heartbeats, iqs, acks — is
+// bookkeeping that keeps the stream alive long enough to receive it.
+//
+// The codec is hand-written for the handful of messages involved and driven off
+// the event loop; the bytes on the wire are the ones the native Android client
+// produces.
+//
+// Nothing here is reachable without a push token, and the whole path is
+// optional: registration falls back to SMS whenever any of it fails.
+
+const tls    = require('tls');
+const { dbg: _whaDbg } = require('./logger');
+
+const MCS_HOST = 'mtalk.google.com';
+const MCS_PORT = 5228;
+const MCS_VERSION = 41;
+
+const TAG_HEARTBEAT_PING   = 0;
+const TAG_HEARTBEAT_ACK    = 1;
+const TAG_LOGIN_REQUEST    = 2;
+const TAG_LOGIN_RESPONSE   = 3;
+const TAG_CLOSE            = 4;
+const TAG_IQ_STANZA        = 7;
+const TAG_DATA_MESSAGE     = 8;
+
+// Ten minutes, matching the native client. Google closes an idle stream, and a
+// ping well inside its window keeps it open without chattering.
+const HEARTBEAT_INTERVAL_MS = 10 * 60 * 1000;
+
+// The last N persistent ids are echoed on the next login so the server does not
+// redeliver messages already seen. A short buffer is enough for a code fetch.
+const PERSISTENT_ID_BUFFER = 50;
+
+// The appData key WhatsApp files the verification code under.
+const PUSH_CODE_APP_DATA_KEY = 'registration_code';
+
+// ─── minimal protobuf codec ──────────────────────────────────────────────────
+
+function encodeVarint(value) {
+  let v = typeof value === 'bigint' ? value : BigInt(Math.trunc(value));
+  if (v < 0n) v += 1n << 64n;
+  const out = [];
+  do {
+    let b = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) b |= 0x80;
+    out.push(b);
+  } while (v > 0n);
+  return Buffer.from(out);
+}
+
+const pbTag  = (field, wire) => encodeVarint((field << 3) | wire);
+const pbInt  = (field, n) => Buffer.concat([pbTag(field, 0), encodeVarint(n)]);
+function pbStr(field, s) {
+  const b = Buffer.from(String(s), 'utf8');
+  return Buffer.concat([pbTag(field, 2), encodeVarint(b.length), b]);
+}
+function pbMsg(field, buf) {
+  return Buffer.concat([pbTag(field, 2), encodeVarint(buf.length), buf]);
+}
+
+// Read a protobuf message into { field: value | [values] }. Length-delimited
+// fields come back as Buffers, varints as BigInt, so a 64-bit id never loses
+// precision. Repeated fields collect into arrays.
+function pbDecode(buf) {
+  const out = {};
+  let i = 0;
+  const put = (f, v) => {
+    if (out[f] === undefined) out[f] = v;
+    else if (Array.isArray(out[f])) out[f].push(v);
+    else out[f] = [out[f], v];
+  };
+  const varint = () => {
+    let r = 0n, s = 0n;
+    while (i < buf.length) { const b = buf[i++]; r |= BigInt(b & 0x7f) << s; s += 7n; if (!(b & 0x80)) break; }
+    return r;
+  };
+  while (i < buf.length) {
+    const key = Number(varint()), field = key >> 3, wire = key & 7;
+    if (wire === 0) put(field, varint());
+    else if (wire === 2) { const n = Number(varint()); put(field, buf.slice(i, i + n)); i += n; }
+    else if (wire === 1) { i += 8; }
+    else if (wire === 5) { i += 4; }
+    else break;
+  }
+  return out;
+}
+
+// ─── message builders ────────────────────────────────────────────────────────
+
+function buildLoginRequest(session) {
+  const androidId = String(session.androidId);
+  const setting = Buffer.concat([pbStr(1, 'new_vc'), pbStr(2, '1')]);
+
+  const parts = [
+    pbStr(1, 'android-30'),                            // id
+    pbStr(2, 'mcs.android.com'),                       // domain
+    pbStr(3, androidId),                               // user
+    pbStr(4, androidId),                               // resource
+    pbStr(5, String(session.securityToken)),           // authToken
+    pbStr(6, 'android-' + BigInt(androidId).toString(16)), // deviceId
+    pbMsg(8, setting)                                   // settings[0]
+  ];
+  for (const pid of (session.persistentIds || [])) parts.push(pbStr(10, pid));
+  // adaptiveHeartbeat (12) is false → omitted. Then:
+  parts.push(pbInt(14, 1));   // useRmq2 = true
+  parts.push(pbInt(16, 2));   // authService = 2
+  parts.push(pbInt(17, 1));   // networkType = 1
+  return Buffer.concat(parts);
+}
+
+const buildHeartbeatAck  = streamId => pbInt(2, streamId);          // lastStreamIdReceived
+const buildHeartbeatPing = streamId => pbInt(2, streamId);
+
+function frame(tag, payload) {
+  const len = encodeVarint(payload.length);
+  return Buffer.concat([Buffer.from([tag]), len, payload]);
+}
+
+// ─── connection ──────────────────────────────────────────────────────────────
+
+/**
+ * Open MCS, log in, and resolve with the verification code the moment it
+ * arrives — or null on timeout or any failure. Never throws.
+ *
+ * The connection must be established before the /code request is sent, or the
+ * push can arrive with nowhere to land; callers open this first and request the
+ * code once `onReady` has fired.
+ *
+ * @param {object} session   { androidId, securityToken, persistentIds? } from lib/fcm
+ * @param {object} [opts]    { timeoutMs=180000, onReady, signal }
+ * @returns {Promise<string|null>}
+ */
+function receivePushCode(session, opts) {
+  opts = opts || {};
+  const timeoutMs = opts.timeoutMs > 0 ? opts.timeoutMs : 180000;
+
+  return new Promise((resolve) => {
+    if (!session || !session.androidId || !session.securityToken) {
+      _whaDbg('[DBG] MCS no android id — cannot receive push code');
+      return resolve(null);
+    }
+
+    let settled = false;
+    let socket = null;
+    let heartbeat = null;
+    let deadline = null;
+    let rx = Buffer.alloc(0);
+    let sawVersion = false;
+    let loggedIn = false;
+    let streamId = 0;
+    const persistentIds = Array.isArray(session.persistentIds) ? session.persistentIds : [];
+
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      if (heartbeat) clearInterval(heartbeat);
+      if (deadline)  clearTimeout(deadline);
+      try { if (socket) socket.destroy(); } catch (_) {}
+      resolve(code);
+    };
+
+    deadline = setTimeout(() => {
+      if (!settled) { _whaDbg('[DBG] MCS timed out after ' + timeoutMs + 'ms'); finish(null); }
+    }, timeoutMs);
+
+    if (opts.signal) {
+      if (opts.signal.aborted) return finish(null);
+      opts.signal.addEventListener('abort', () => finish(null), { once: true });
+    }
+
+    const write = (tag, payload) => {
+      try { socket.write(frame(tag, payload)); } catch (e) {
+        _whaDbg('[DBG] MCS write failed: ' + (e && e.message)); finish(null);
+      }
+    };
+
+    // Route MCS through the SOCKS agent's dialer when one is set, so a proxied
+    // process reaches Google here too. Loaded lazily to avoid a cycle.
+    const { socksProxyUrl, socksConnect } = require('./socks');
+    const proxyUrl = socksProxyUrl();
+
+    const onRaw = (rawSocket) => {
+      socket = tls.connect({
+        socket:     rawSocket || undefined,
+        host:       MCS_HOST,
+        port:       MCS_PORT,
+        servername: MCS_HOST
+      }, () => {
+        // version byte first, then the login frame
+        try {
+          socket.write(Buffer.from([MCS_VERSION]));
+          socket.write(frame(TAG_LOGIN_REQUEST, buildLoginRequest({
+            androidId: session.androidId, securityToken: session.securityToken, persistentIds
+          })));
+          _whaDbg('[DBG] MCS connected, login sent');
+        } catch (e) { _whaDbg('[DBG] MCS login write failed: ' + (e && e.message)); finish(null); }
+      });
+
+      socket.setNoDelay(true);
+      socket.on('data', onData);
+      socket.on('error', (e) => { _whaDbg('[DBG] MCS socket error: ' + (e && e.message)); finish(null); });
+      socket.on('close', () => { if (!settled) { _whaDbg('[DBG] MCS closed'); finish(null); } });
+    };
+
+    if (proxyUrl) {
+      _whaDbg('[DBG] MCS dialing via SOCKS proxy');
+      socksConnect(proxyUrl, MCS_HOST, MCS_PORT)
+        .then(onRaw)
+        .catch(e => { _whaDbg('[DBG] MCS proxy dial failed: ' + (e && e.message)); finish(null); });
+    } else {
+      onRaw(null);
+    }
+
+    function onData(chunk) {
+      rx = Buffer.concat([rx, chunk]);
+
+      // The server's first byte is its protocol version, once, before any frame.
+      if (!sawVersion) {
+        if (rx.length < 1) return;
+        _whaDbg('[DBG] MCS server version=' + rx[0]);
+        rx = rx.slice(1);
+        sawVersion = true;
+      }
+
+      // Drain whole frames. A varint length that runs past the buffer means the
+      // rest is still in flight — wait for more.
+      for (;;) {
+        if (rx.length < 1) return;
+        const tag = rx[0];
+
+        let len = 0, shift = 0n, p = 1, complete = false;
+        for (; p < rx.length && p <= 10; p++) {
+          const b = rx[p];
+          len |= (b & 0x7f) << Number(shift);
+          shift += 7n;
+          if (!(b & 0x80)) { p++; complete = true; break; }
+        }
+        if (!complete) return;                 // length varint not fully here yet
+        if (rx.length < p + len) return;       // payload not fully here yet
+
+        const payload = rx.slice(p, p + len);
+        rx = rx.slice(p + len);
+        handleFrame(tag, payload);
+        if (settled) return;
+      }
+    }
+
+    function handleFrame(tag, payload) {
+      if (!loggedIn) {
+        if (tag !== TAG_LOGIN_RESPONSE) {
+          _whaDbg('[DBG] MCS expected login response, got tag=' + tag); return finish(null);
+        }
+        const resp = pbDecode(payload);
+        if (resp[3]) {                                    // error info present
+          const err = pbDecode(resp[3]);
+          _whaDbg('[DBG] MCS login refused code=' + (err[1] && err[1].toString()));
+          return finish(null);
+        }
+        loggedIn = true;
+        streamId = 1;
+        _whaDbg('[DBG] MCS logged in — waiting for push code');
+        heartbeat = setInterval(() => write(TAG_HEARTBEAT_PING, buildHeartbeatPing(streamId)),
+          HEARTBEAT_INTERVAL_MS);
+        if (typeof opts.onReady === 'function') { try { opts.onReady(); } catch (_) {} }
+        return;
+      }
+
+      streamId++;
+
+      switch (tag) {
+        case TAG_DATA_MESSAGE: {
+          const code = extractCode(payload, persistentIds);
+          if (code) { _whaDbg('[DBG] MCS push code received'); return finish(code); }
+          break;
+        }
+        case TAG_HEARTBEAT_PING:
+          write(TAG_HEARTBEAT_ACK, buildHeartbeatAck(streamId));
+          break;
+        case TAG_HEARTBEAT_ACK:
+        case TAG_IQ_STANZA:
+          break;
+        case TAG_CLOSE:
+          _whaDbg('[DBG] MCS server requested close'); return finish(null);
+        default:
+          _whaDbg('[DBG] MCS unknown tag ' + tag + ' (' + payload.length + 'b)');
+      }
+    }
+  });
+}
+
+// Pull the verification code out of a data-message stanza, and remember its
+// persistent id so a reconnect does not ask for it again.
+//
+//   field 9  persistentId (string)
+//   field 7  appData, repeated { 1: key, 2: value }
+function extractCode(payload, persistentIds) {
+  const stanza = pbDecode(payload);
+
+  const pid = stanza[9];
+  if (pid && pid.length) {
+    persistentIds.push(pid.toString('utf8'));
+    if (persistentIds.length > PERSISTENT_ID_BUFFER) {
+      persistentIds.splice(0, persistentIds.length - PERSISTENT_ID_BUFFER);
+    }
+  }
+
+  let appData = stanza[7];
+  if (!appData) return null;
+  if (!Array.isArray(appData)) appData = [appData];
+
+  for (const entry of appData) {
+    const kv = pbDecode(entry);
+    const key = kv[1] ? kv[1].toString('utf8') : '';
+    if (key === PUSH_CODE_APP_DATA_KEY) {
+      return kv[2] ? kv[2].toString('utf8') : null;
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  receivePushCode,
+  MCS_HOST,
+  MCS_PORT,
+  MCS_VERSION,
+  PUSH_CODE_APP_DATA_KEY,
+  // exported for tests
+  buildLoginRequest,
+  frame,
+  pbDecode,
+  extractCode,
+  encodeVarint,
+  TAG_LOGIN_RESPONSE,
+  TAG_DATA_MESSAGE,
+  TAG_HEARTBEAT_PING,
+  TAG_HEARTBEAT_ACK
+};

package/lib/fcm.js

@@ -512,8 +512,48 @@ async function getPushToken(store, device) {
   }
 }
 
+/**
+ * Open the MCS listener that receives the verification code as a push, using
+ * the Firebase identity already established for this account.
+ *
+ * The token has to exist first — getPushToken establishes the android id and
+ * security token MCS logs in with — so this calls it when the store has none.
+ * The returned promise resolves with the code when it arrives, or null on any
+ * failure, so the caller can fall back to SMS.
+ *
+ * @param {object} store    the account store; the Firebase session is on store.fcm
+ * @param {object} device   device config
+ * @param {object} [opts]   { timeoutMs, onReady, signal }
+ * @returns {Promise<string|null>}
+ */
+async function receivePushCode(store, device, opts) {
+  if (!enabled() || !store) return null;
+
+  // Make sure we hold an android id / security token before opening MCS.
+  if (!store.fcm || !store.fcm.androidId || !store.fcm.securityToken) {
+    await getPushToken(store, device);
+  }
+  const s = store.fcm;
+  if (!s || !s.androidId || !s.securityToken) {
+    _whaDbg('[DBG] FCM no identity for MCS — cannot receive push code');
+    return null;
+  }
+
+  const { receivePushCode: mcsReceive } = require('./fcm-mcs');
+  const session = {
+    androidId:     s.androidId,
+    securityToken: s.securityToken,
+    persistentIds: Array.isArray(s.persistentIds) ? s.persistentIds : []
+  };
+  const code = await mcsReceive(session, opts);
+  // Persist the persistent-id buffer so a later listen does not re-see messages.
+  store.fcm = Object.assign({}, store.fcm, { persistentIds: session.persistentIds });
+  return code;
+}
+
 module.exports = {
   getPushToken,
+  receivePushCode,
   enabled,
   FCM_CONFIG,
   // exported for tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.19.4",
+  "version": "5.21.0",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API and web ",
   "author": "Kunboruto20",
   "main": "index.js",
@@ -53,6 +53,7 @@
   },
   "optionalDependencies": {
     "jimp": "^1.6.0",
-    "socks": "^2.8.9"
+    "socks": "^2.8.9",
+    "qrcode-terminal": "^0.12.0"
   }
 }