whalibmob 5.19.1 → 5.19.3

package/.env.example

@@ -124,8 +124,10 @@
 
 
 # ─── Proxy ───────────────────────────────────────────────────────────────────
-# Route registration traffic through a SOCKS proxy. Requires the `socks`
-# package: npm install socks
+# Route every outbound connection through a SOCKS proxy: the message socket
+# (mobile TCP and web WSS alike), registration, the announced-version lookups,
+# the APK material download and media uploads. Requires the `socks` package:
+# npm install socks
 #
 # A bare host:port is assumed to be socks5. Add a scheme to be explicit, and
 # credentials if the proxy needs them. Percent-encode any @ or : in a password.
@@ -142,6 +144,18 @@
 # Only if `socks` lives somewhere require() cannot find it:
 # WA_SOCKS_LIB=/absolute/path/to/socks/build/index.js
 
+# ─── Push token ──────────────────────────────────────────────────────────────
+# Every WhatsApp on a real phone holds a Firebase push token — it is how the
+# server wakes the app. Registration fetches one from Google and ships it as
+# push_token, so the request looks like the install it claims to be.
+#
+# On by default. Three plain HTTPS calls to Google, once per number, cached with
+# the session afterwards. Any failure is silent: the field is dropped and
+# registration proceeds exactly as it would without it.
+#
+# Set to 0 to skip it entirely.
+# WA_FCM_PUSH=0
+
 
 # ─── Registration funnel telemetry ───────────────────────────────────────────
 # Registration reports the screens it passes through to WhatsApp's /client_log,

package/README.md

@@ -152,7 +152,8 @@ npm install -g whalibmob
     - [Two Sessions on One Number](#two-sessions-on-one-number)
   - [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under)
   - [When Registration Is Refused for Consent](#when-registration-is-refused-for-consent)
-  - [Routing Registration Through a Proxy](#routing-registration-through-a-proxy)
+  - [The Push Token](#the-push-token)
+  - [Routing Traffic Through a Proxy](#routing-traffic-through-a-proxy)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
   - [Signal Store Utilities](#signal-store-utilities)
     - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
@@ -2488,9 +2489,29 @@ If that is refused too, the number has to go through the real app once, on a pho
 > [!NOTE]
 > The `login` field in that reply is worth reading. Brazilian mobiles gained a ninth digit that WhatsApp never adopted, so `+5571976034186` is filed as `+557176034186`. whalibmob adopts the server's form automatically on a successful registration and saves the session under it — the digit difference is not itself the failure.
 
-## Routing Registration Through a Proxy
+## The Push Token
 
-Registration is the part of the protocol most likely to be refused from a datacenter IP. If you are seeing security blocks or an undeterminable number status, route it through a SOCKS proxy — Tor, or a residential provider.
+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.
+
+Registration fetches a real one and sends it, in three plain HTTPS calls to Google:
+
+| Step | Endpoint | Yields |
+|---|---|---|
+| 1 | `android.clients.google.com/checkin` | an android id and security token — the device's identity with Google |
+| 2 | `firebaseinstallations.googleapis.com` | a Firebase installation for WhatsApp's project |
+| 3 | `android.clients.google.com/c2dm/register3` | the FCM token itself |
+
+No root, no Frida, no phone. This is unrelated to Play Integrity attestation — the two travel in the same request but come from different places, and one works without the other.
+
+It runs once per number. The Firebase identity is cached on the session, because Google issues an android id once and expects it back; fetching a new one per registration step would mint a fresh phantom device each time.
+
+**Failure is silent by design.** A blocked network, a refusal from Google, a malformed answer — all end with the field omitted and registration proceeding exactly as it did before push tokens were wired up. A push token helps; it is never a prerequisite.
+
+Turn it off with `WA_FCM_PUSH=0`.
+
+## 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.
 
 Install the optional dependency and set one environment variable:
 
@@ -2517,10 +2538,30 @@ process.env.SOCKS_PROXY = 'socks5://user:pass@proxy.example.com:1080'
 await requestSmsCode(phone, store)
 ```
 
-> [!NOTE]
-> This covers the registration traffic to `v.whatsapp.net`. The message socket and media transfers are not proxied — if you need those behind a proxy as well, open an issue describing the setup.
+### What goes through it
+
+Everything the library sends out:
+
+| Connection | Destination |
+|---|---|
+| Message socket, mobile | raw TCP to WhatsApp |
+| Message socket, web | `wss://web.whatsapp.com/ws/chat` |
+| Registration | `v.whatsapp.net` |
+| Announced version, iOS | App Store lookup |
+| Announced version, Android | Play Store listing |
+| Announced version, web | `web.whatsapp.com/sw.js` |
+| APK material for registration | Play Store download |
+| Media upload | WhatsApp's media hosts |
+
+Node's `http`/`https` modules ignore proxy environment variables entirely — a proxy has to be handed in as an agent, per call site. Only the registration POST used to do that, which produced a confusing failure: `curl -x socks5://…` reached WhatsApp while the library timed out on the same machine, falling back to a pinned version with only a debug line to show for it:
+
+```
+[DBG] WEB_VERSION 2.3000.1035194821 (pinned fallback: sw.js fetch timed out)
+```
+
+All eight paths now share one agent.
 
-If `socks` is not installed, or a proxy is unreachable, you get a message saying so rather than a silent failure. In the rare case the package lives somewhere `require()` cannot find it, `WA_SOCKS_LIB` takes an absolute path to it.
+If `socks` is not installed, or a proxy is unreachable, you get a message saying so rather than a silent failure. A proxy URL that cannot be parsed leaves the connection direct rather than throwing — a version lookup with a pinned fallback should not take a process down over its proxy. In the rare case the package lives somewhere `require()` cannot find it, `WA_SOCKS_LIB` takes an absolute path to it.
 
 ## Saving & Restoring Sessions
 

package/lib/MediaService.js

@@ -195,11 +195,17 @@ function _tryUpload(host, mediaPath, token, auth, encrypted, web) {
     const hostname = typeof host === 'string' ? host : host.hostname;
     const urlPath  = `/${mediaPath}/${token}?auth=${auth}&token=${token}`;
 
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     const options = {
       hostname,
       port:    443,
       path:    urlPath,
       method:  'POST',
+      // The media hosts are as unreachable as the rest of WhatsApp on a network
+      // that needs a proxy. Uploading direct while the socket is proxied leaves
+      // a session that connects and then cannot send a photo.
+      agent:   agent || undefined,
       headers: Object.assign({
         'Content-Type':   'application/octet-stream',
         'Content-Length': encrypted.length,
@@ -265,9 +271,15 @@ const MAX_REDIRECTS = 5;
 
 function _httpGet(url, opts, depth) {
   return new Promise((resolve, reject) => {
-    const lib = url.startsWith('https') ? https : http;
+    const isTls = url.startsWith('https');
+    const lib = isTls ? https : http;
     const web = !!(opts && opts.web);
-    lib.get(url, { headers: mediaHeaders(web) }, (res) => {
+    // The agent tunnels TLS, so it belongs on https only. A plain-http media
+    // URL is rare enough that leaving it direct is better than handing an
+    // https.Agent to the http module and getting an obscure failure.
+    const { proxyAgent } = require('./socks');
+    const agent = isTls ? proxyAgent() : null;
+    lib.get(url, { agent: agent || undefined, headers: mediaHeaders(web) }, (res) => {
       const status = res.statusCode || 0;
       if (status === 301 || status === 302) {
         res.resume();                                   // drop the redirect body

package/lib/PlayStore.js

@@ -124,12 +124,18 @@ function _request(url, opts) {
   opts = opts || {};
   return new Promise((resolve, reject) => {
     const u   = new URL(url);
+    // The APK material download is a Google endpoint, blocked on the same
+    // networks that block WhatsApp. Registration would otherwise fall back to
+    // stale certificate material with no way to refresh it.
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     const req = https.request({
       hostname: u.hostname,
       port:     u.port || 443,
       path:     u.pathname + u.search,
       method:   opts.method || 'GET',
       headers:  opts.headers || {},
+      agent:    agent || undefined,
       timeout:  REQUEST_TIMEOUT
     }, (res) => {
       // The CDN answers a signed URL with a redirect more often than not.

package/lib/Registration.js

@@ -56,108 +56,23 @@ function registrationHeaders(device, waVersion) {
 
 // ---------- SOCKS4 / SOCKS5 / Tor support ----------
 //
-// Set SOCKS_PROXY (or TOR_PROXY) to route registration traffic through a proxy:
-//
-//   socks5://127.0.0.1:9050              Tor
-//   socks5://user:pass@host:1080         authenticated residential proxy
-//   socks5h://host:1080                  resolve the destination at the proxy
-//   socks4://host:1080                   older proxies
-//
-// Requires the `socks` package: npm install socks
-
-const SOCKS_SCHEMES = {
-  'socks:':   5,
-  'socks5:':  5,
-  'socks5h:': 5,
-  'socks4:':  4,
-  'socks4a:': 4
-};
-
-// Resolve the library the way every other dependency is resolved.
-//
-// This used to be a hardcoded absolute path into one particular machine's
-// global npm directory. It resolved there and nowhere else, so proxy support
-// was dead for everybody who installed whalibmob normally — the require threw
-// MODULE_NOT_FOUND the moment a proxy was configured. WA_SOCKS_LIB stays as an
-// escape hatch for unusual layouts, but it is an override now, not the only
-// way in.
-function loadSocks() {
-  const override = process.env.WA_SOCKS_LIB;
-  if (override) {
-    try { return require(override); }
-    catch (err) {
-      throw new Error('WA_SOCKS_LIB points at ' + override +
-        ' but it could not be loaded: ' + err.message);
-    }
-  }
-  try {
-    return require('socks');
-  } catch (_) {
-    throw new Error(
-      "A SOCKS proxy is configured but the 'socks' package is not installed. " +
-      'Run: npm install socks'
-    );
-  }
-}
-
-/**
- * Parse a proxy URL into what SocksClient expects.
- *
- * Accepts the schemes above, with or without credentials, and defaults the
- * port to 1080 the way every SOCKS client does.
- */
-function parseSocksProxy(proxyUrl) {
-  let raw = String(proxyUrl || '').trim();
-  if (!raw) throw new Error('No SOCKS proxy configured');
-
-  // A bare host:port is what .env.example has always shown and what most people
-  // type. Without a scheme `new URL` reads "127.0.0.1:" as the protocol and the
-  // rest as the path, so it has to be filled in before parsing.
-  if (!/^[a-z0-9+.-]+:\/\//i.test(raw)) raw = 'socks5://' + raw;
-
-  let url;
-  try { url = new URL(raw); }
-  catch (_) { throw new Error('Invalid SOCKS proxy URL: ' + proxyUrl); }
-
-  const type = SOCKS_SCHEMES[url.protocol];
-  if (!type) {
-    throw new Error('Unsupported proxy scheme "' + url.protocol + '" — use ' +
-      Object.keys(SOCKS_SCHEMES).map(s => s.replace(':', '')).join(', '));
-  }
-  if (!url.hostname) throw new Error('SOCKS proxy URL has no host: ' + proxyUrl);
-
-  const proxy = {
-    host: url.hostname,
-    port: parseInt(url.port, 10) || 1080,
-    type
-  };
-  // Credentials may be percent-encoded in a URL; a password with an @ or a :
-  // in it is common enough on paid proxies to be worth decoding.
-  if (url.username) proxy.userId   = decodeURIComponent(url.username);
-  if (url.password) proxy.password = decodeURIComponent(url.password);
-  return proxy;
-}
-
-// TOR_PROXY wins when both are set — the precedence .env.example has always
-// documented.
-function socksProxyUrl() {
-  return process.env.TOR_PROXY || process.env.SOCKS_PROXY || '';
-}
+// The parsing, the dialer and the HTTPS agent all live in ./socks now, because
+// registration is no longer the only thing that needs them: the version
+// lookups below, the web sw.js probe, the WhatsApp Web socket and the mobile
+// TCP socket route through the same proxy. They are re-exported at the bottom
+// of this file so existing importers keep working.
+const {
+  parseSocksProxy, socksProxyUrl, socksConnect, proxyAgent
+} = require('./socks');
 
 async function httpPostViaSocks(path, body, waVersion, proxyUrl, authHeader, device) {
-  const proxy = parseSocksProxy(proxyUrl);
   const dHost = 'v.whatsapp.net';
   const dPort = 443;
 
-  const { SocksClient } = loadSocks();
-  const { socket: rawSocket } = await SocksClient.createConnection({
-    proxy,
-    command:     'connect',
-    destination: { host: dHost, port: dPort },
-    // Without this a proxy that accepts the TCP connection and then says
-    // nothing leaves the whole registration hanging with no error.
-    timeout: 20000
-  });
+  // socksConnect carries the same 20s handshake timeout this used to set
+  // inline: without one, a proxy that accepts the TCP connection and then says
+  // nothing leaves the whole registration hanging with no error.
+  const rawSocket = await socksConnect(proxyUrl, dHost, dPort);
 
   const tlsSocket = tls.connect({
     socket:             rawSocket,
@@ -671,9 +586,10 @@ async function fetchIosVersion(business) {
   if (hit) return hit;
   const bundleId = business ? IOS_BUSINESS_BUNDLE_ID : IOS_BUNDLE_ID;
   return new Promise((resolve) => {
+    const agent = proxyAgent();
     const req = https.get(
       'https://itunes.apple.com/lookup?bundleId=' + bundleId,
-      { headers: { 'User-Agent': IOS_USER_AGENT } },
+      { agent: agent || undefined, headers: { 'User-Agent': IOS_USER_AGENT } },
       (res) => {
         const chunks = [];
         res.on('data', d => chunks.push(d));
@@ -705,6 +621,10 @@ async function fetchAndroidVersion(business) {
   const packageName = business ? WHATSAPP_BUSINESS_PACKAGE : WHATSAPP_PACKAGE;
   try {
     const axios = require('axios');
+    // Unlike https.get, axios reads HTTP_PROXY/HTTPS_PROXY on its own. That
+    // stays untouched when no SOCKS proxy is configured; `proxy: false` is set
+    // only alongside our own agent, so the two never fight over the socket.
+    const socksAgent = proxyAgent();
     const resp = await axios.get(
       'https://play.google.com/store/apps/details?id=' + packageName + '&hl=en&gl=us',
       {
@@ -719,7 +639,11 @@ async function fetchAndroidVersion(business) {
         },
         responseType: 'text',
         decompress:   true,
-        timeout: 12000
+        timeout: 12000,
+        // axios takes an agent under a different key than https.get does, but
+        // drives it identically. Omitted, this lookup ignores SOCKS_PROXY and
+        // silently falls back to a pinned version on a blocked network.
+        ...(socksAgent ? { httpsAgent: socksAgent, proxy: false } : {})
       }
     );
     // Buffer when the response was compressed and axios handed the bytes back
@@ -1333,7 +1257,13 @@ async function buildPayload(store, waVersion, useToken, extraPairs) {
       .update(Buffer.concat([store.identityId, stripKeyPrefix(store.noiseKeyPair.public)]))
       .digest()
   );
-  const attestFields = await attestation.attestationFields(device, nonceB64);
+  // 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);
+
+  const attestFields = await attestation.attestationFields(device, nonceB64, { pushToken });
 
   return buildForm([
     'cc',                cc,

package/lib/Store.js

@@ -201,6 +201,10 @@ function storeToJson(store) {
     // call it has to know, since that code is read off the caller ID rather
     // than out of a message.
     codeMethod:     store.codeMethod || null,
+    // Firebase identity behind the push_token. Google issues an android id once
+    // and expects it back; discarding it would mint a new phantom device on
+    // every registration step, which is worse than carrying one.
+    fcm:            store.fcm || null,
     name,
     version,
     device,
@@ -244,6 +248,9 @@ function storeFromJson(obj) {
     registered:     !!obj.registered,
     codePending:    obj.codePending || false,
     codeMethod:     obj.codeMethod || null,
+    // Absent on stores written before push tokens existed; null simply means
+    // the first registration step will fetch one.
+    fcm:            obj.fcm || null,
     name,
     version,
     device,

package/lib/WebSocketStream.js

@@ -38,8 +38,15 @@ class WebSocketStream extends EventEmitter {
 
   connect() {
     const WebSocket = loadWs();
+    // ws drives an agent exactly the way https.request does, so the same SOCKS
+    // agent that carries the version probe carries the socket. Without it the
+    // upgrade request goes out directly while everything else in the process
+    // is proxied, which fails in the one situation a proxy is set for.
+    const { proxyAgent } = require('./socks');
+    const agent = proxyAgent();
     this._ws = new WebSocket(this._url, {
       origin:  this._origin,
+      agent:   agent || undefined,
       headers: {
         'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
                       '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'

package/lib/WebVersion.js

@@ -18,6 +18,7 @@
 
 const https = require('https');
 const { WEB_VERSION_FALLBACK } = require('./constants');
+const { proxyAgent } = require('./socks');
 
 const SW_URL   = 'https://web.whatsapp.com/sw.js';
 const CACHE_MS = 60 * 60 * 1000;   // an hour; the revision changes far slower
@@ -27,7 +28,13 @@ let _cachedAt = 0;
 
 function fetchText(url, timeoutMs) {
   return new Promise((resolve, reject) => {
+    // Without this the request ignores SOCKS_PROXY and goes out directly —
+    // which on a network that cannot reach web.whatsapp.com means a ten-second
+    // stall and a fall back to the pinned revision, while curl through the very
+    // same proxy answers instantly.
+    const agent = proxyAgent();
     const req = https.get(url, {
+      agent: agent || undefined,
       headers: {
         // The minimum that gets past the anti-bot check on this path.
         'sec-fetch-site': 'none',

package/lib/fcm.js

@@ -0,0 +1,445 @@
+'use strict';
+
+// Firebase Cloud Messaging registration — the push_token a real WhatsApp
+// install carries.
+//
+// Every WhatsApp on a real phone holds a push token, because that is how the
+// server wakes it when a message arrives. A registration that ships no
+// push_token describes a WhatsApp that cannot be notified, which is a device
+// that does not exist. The field was already wired through
+// Attestation.attestationFields; nothing ever filled it, so buildForm dropped
+// it and every registration went out without one.
+//
+// Three steps, all plain HTTPS with Google — no root, no Frida, no phone:
+//
+//   1. checkin      android.clients.google.com/checkin
+//                   protobuf in, protobuf out; yields an android id and a
+//                   security token, which together are the device's identity
+//                   with Google.
+//   2. FIS install  firebaseinstallations.googleapis.com/v1/projects/…
+//                   registers a Firebase installation for WhatsApp's project
+//                   and returns a short-lived auth token.
+//   3. register3    android.clients.google.com/c2dm/register3
+//                   trades the two for the actual FCM token.
+//
+// Everything here fails soft. A blocked network, a refusal from Google, a
+// malformed answer — all of them return null, the field is omitted, and
+// registration proceeds exactly as it did before this file existed. A push
+// token is a signal that helps; it is not a prerequisite, and it must never be
+// the reason a registration cannot be attempted.
+//
+// The session is persisted with the account. Google hands out an android id
+// once and expects it to keep coming back; re-running checkin on every
+// registration step would mint a new device each time, which is itself a
+// pattern no real phone produces.
+
+const https = require('https');
+const zlib  = require('zlib');
+const crypto = require('crypto');
+
+const { dbg: _whaDbg } = require('./logger');
+const { proxyAgent }   = require('./socks');
+
+// WhatsApp's own Firebase project. These are public client-side identifiers,
+// the same ones the APK ships in google-services.json.
+const FCM_CONFIG = {
+  personal: {
+    projectId:   'whatsapp-messenger',
+    appId:       '1:293955441834:android:7373a2d0bdfa3228',
+    apiKey:      'AIzaSyCGOJbGQ95SWrXxl8wk-_cRQZcJl42bvDU',
+    senderId:    '293955441834',
+    packageName: 'com.whatsapp',
+    certSha1:    '38a0f7d505fe18fec64fbf343ecaaaf310dbd799'
+  },
+  business: {
+    projectId:   'whatsapp-messenger',
+    appId:       '1:293955441834:android:7373a2d0bdfa3228',
+    apiKey:      'AIzaSyCGOJbGQ95SWrXxl8wk-_cRQZcJl42bvDU',
+    senderId:    '293955441834',
+    packageName: 'com.whatsapp.w4b',
+    certSha1:    '38a0f7d505fe18fec64fbf343ecaaaf310dbd799'
+  }
+};
+
+const CHECKIN_URL  = 'https://android.clients.google.com/checkin';
+const REGISTER_URL = 'https://android.clients.google.com/c2dm/register3';
+const FIS_URL      = 'https://firebaseinstallations.googleapis.com/v1/projects/%s/installations';
+
+const HTTP_TIMEOUT_MS = 15000;
+
+// A Firebase installation id: 17 random bytes with the top nibble pinned to
+// 0b0111 per the FIS spec, url-safe base64, truncated to 22 characters.
+const FID_BYTES = 17;
+const FID_LENGTH = 22;
+
+// ─── minimal protobuf writer ─────────────────────────────────────────────────
+//
+// The checkin message is the only protobuf this file has to produce, and it is
+// a handful of scalar fields. A writer for exactly those is smaller than a
+// schema plus a runtime, and it keeps the wire format visible next to the code
+// that depends on it.
+
+function varint(value) {
+  let v = typeof value === 'bigint' ? value : BigInt(Math.trunc(value));
+  if (v < 0n) v += 1n << 64n;                       // two's complement, as protobuf does
+  const out = [];
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) byte |= 0x80;
+    out.push(byte);
+  } while (v > 0n);
+  return Buffer.from(out);
+}
+
+const pbTag   = (field, wire) => varint((field << 3) | wire);
+const pbInt   = (field, n)    => Buffer.concat([pbTag(field, 0), varint(n)]);
+const pbBool  = (field, b)    => Buffer.concat([pbTag(field, 0), varint(b ? 1 : 0)]);
+
+function pbBytes(field, buf) {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(String(buf), 'utf8');
+  return Buffer.concat([pbTag(field, 2), varint(b.length), b]);
+}
+const pbStr = pbBytes;
+const pbMsg = pbBytes;
+
+// ─── checkin request / response ──────────────────────────────────────────────
+
+function encodeCheckinRequest() {
+  const now = Date.now();
+
+  // The device this claims to be. A fixed, unremarkable build: Google's own
+  // reference hardware, which is what every FCM client library has announced
+  // for a decade. Randomising it would make each registration a different
+  // phantom device, which reads worse than one ordinary repeated one.
+  const build = Buffer.concat([
+    pbStr(1,  'google/razor/flo:5.0.1/LRX22C/1602158:user/release-keys'),
+    pbStr(2,  'flo'),
+    pbStr(3,  'google'),
+    pbStr(6,  'android-google'),
+    pbInt(7,  Math.floor(now / 1000)),
+    pbInt(10, 30),
+    pbStr(11, 'Nexus 7'),
+    pbStr(12, 'asus'),
+    pbStr(13, 'razor'),
+    pbBool(14, false)
+  ]);
+
+  const event = Buffer.concat([
+    pbStr(1, 'event_log_start'),
+    pbInt(3, now)
+  ]);
+
+  const checkin = Buffer.concat([
+    pbMsg(1, build),
+    pbInt(2, 0),
+    pbMsg(3, event),
+    pbInt(9, 0)
+  ]);
+
+  // 53 bits of randomness rather than a full 63: it stays an exact JS integer,
+  // and Google only needs the value to be unlikely to collide.
+  const loggingId = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+
+  return Buffer.concat([
+    pbInt(2,  0),
+    pbMsg(4,  checkin),
+    pbStr(6,  'en_US'),
+    pbInt(7,  loggingId),
+    pbStr(12, 'UTC'),
+    pbInt(14, 3),
+    pbInt(20, 0),
+    pbInt(22, 0)
+  ]);
+}
+
+// Only two fields matter in the answer, both fixed64: 7 = android id,
+// 8 = security token. They are 64-bit and are echoed back to Google verbatim,
+// so they are kept as BigInt and only ever stringified — a Number would round
+// them and the Authorization header would be silently wrong.
+function decodeCheckinResponse(buf) {
+  let i = 0;
+  const out = { androidId: null, securityToken: null };
+
+  const readVarint = () => {
+    let result = 0n, shift = 0n;
+    while (i < buf.length) {
+      const b = buf[i++];
+      result |= BigInt(b & 0x7f) << shift;
+      shift += 7n;
+      if (!(b & 0x80)) break;
+    }
+    return result;
+  };
+
+  while (i < buf.length) {
+    const key   = Number(readVarint());
+    const field = key >> 3;
+    const wire  = key & 7;
+
+    if (wire === 0) { readVarint(); }
+    else if (wire === 1) {
+      if (i + 8 > buf.length) break;
+      const v = buf.readBigUInt64LE(i);
+      i += 8;
+      if (field === 7) out.androidId = v;
+      if (field === 8) out.securityToken = v;
+    }
+    else if (wire === 2) {
+      const len = Number(readVarint());
+      i += len;
+    }
+    else if (wire === 5) { i += 4; }
+    else break;
+  }
+  return out;
+}
+
+// ─── HTTP ────────────────────────────────────────────────────────────────────
+//
+// Routed through the SOCKS agent when one is configured, like every other
+// outbound call in the library — a machine that needs a proxy to reach WhatsApp
+// generally needs one to reach Google too.
+
+function httpPost(url, body, headers) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const agent = proxyAgent();
+    const req = https.request({
+      hostname: u.hostname,
+      port:     u.port || 443,
+      path:     u.pathname + u.search,
+      method:   'POST',
+      headers:  Object.assign({ 'Content-Length': body.length }, headers),
+      agent:    agent || undefined
+    }, res => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        let raw = Buffer.concat(chunks);
+        if (String(res.headers['content-encoding'] || '').includes('gzip')) {
+          try { raw = zlib.gunzipSync(raw); } catch (_) {}
+        }
+        resolve({ status: res.statusCode || 0, body: raw });
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.setTimeout(HTTP_TIMEOUT_MS, () => req.destroy(new Error('timed out')));
+    req.write(body);
+    req.end();
+  });
+}
+
+// ─── the three steps ─────────────────────────────────────────────────────────
+
+async function checkin() {
+  const body = zlib.gzipSync(encodeCheckinRequest());
+  const res  = await httpPost(CHECKIN_URL, body, {
+    'Content-Type':     'application/x-protobuffer',
+    'Content-Encoding': 'gzip',
+    'Accept-Encoding':  'gzip',
+    'User-Agent':       'Android-Checkin/2.0 (generic JLS36G); gzip'
+  });
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error('checkin HTTP ' + res.status);
+  }
+  const { androidId, securityToken } = decodeCheckinResponse(res.body);
+  if (!androidId || !securityToken) {
+    throw new Error('checkin returned no android id (' + res.body.length + ' B)');
+  }
+  return { androidId: androidId.toString(), securityToken: securityToken.toString() };
+}
+
+function generateFid() {
+  const raw = crypto.randomBytes(FID_BYTES);
+  raw[0] = 0b01110000 | (raw[0] & 0b00001111);
+  return raw.toString('base64url').slice(0, FID_LENGTH);
+}
+
+async function fisInstall(config, existingFid) {
+  const fid  = existingFid || generateFid();
+  const body = Buffer.from(JSON.stringify({
+    fid,
+    appId:       config.appId,
+    authVersion: 'FIS_v2',
+    sdkVersion:  'a:17.0.0'
+  }), 'utf8');
+
+  const res = await httpPost(FIS_URL.replace('%s', config.projectId), body, {
+    'Content-Type':    'application/json',
+    'Accept':          'application/json',
+    'Cache-Control':   'no-cache',
+    'User-Agent':      'Dalvik/2.1.0 (Linux; U; Android 11; Pixel 2 Build/RP1A.201005.004) FirebaseInstallations/17.0.0',
+    'X-Firebase-Client': Buffer.from('{"heartbeats":[],"version":2}', 'utf8').toString('base64url'),
+    'x-goog-api-key':  config.apiKey,
+    'X-Android-Package': config.packageName,
+    'X-Android-Cert':  config.certSha1.replace(/:/g, '').toUpperCase()
+  });
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error('FIS install HTTP ' + res.status + ': ' + res.body.toString('utf8').slice(0, 200));
+  }
+
+  let parsed;
+  try { parsed = JSON.parse(res.body.toString('utf8')); }
+  catch (_) { throw new Error('FIS install returned non-JSON'); }
+
+  const auth = parsed.authToken || {};
+  return {
+    fid:          parsed.fid || fid,
+    authToken:    auth.token || '',
+    refreshToken: parsed.refreshToken || '',
+    expiresAt:    Math.floor(Date.now() / 1000) + parseDurationSeconds(auth.expiresIn)
+  };
+}
+
+// Google writes durations as "604800s". A missing or malformed value becomes 0,
+// which reads as already expired and simply forces a refresh next time.
+function parseDurationSeconds(text) {
+  const m = /^(\d+)s$/.exec(String(text || ''));
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+async function register3(config, session) {
+  const form = {
+    app:           config.packageName,
+    sender:        config.senderId,
+    device:        session.androidId,
+    cert:          config.certSha1.replace(/:/g, '').toLowerCase(),
+    app_ver:       '1',
+    target_ver:    '30',
+    info:          '',
+    'X-subtype':      config.senderId,
+    'X-subscription': config.senderId,
+    'X-app_ver':      '1',
+    'X-osv':          '30',
+    'X-cliv':         'fiid-21.1.0',
+    'X-gmsv':         '240913000',
+    'X-scope':        '*',
+    'X-appid':        session.fid,
+    'X-gmp_app_id':   config.appId,
+    'X-Goog-Firebase-Installations-Auth': session.fisAuthToken,
+    'X-firebase-app-name-hash': ''
+  };
+
+  const body = Buffer.from(
+    Object.keys(form)
+      .map(k => encodeURIComponent(k) + '=' + encodeURIComponent(form[k]))
+      .join('&'),
+    'utf8'
+  );
+
+  const res = await httpPost(REGISTER_URL, body, {
+    'Authorization': 'AidLogin ' + session.androidId + ':' + session.securityToken,
+    'Content-Type':  'application/x-www-form-urlencoded',
+    'User-Agent':    'Android-GCM/1.5 (generic LRX22C)',
+    'app':           config.packageName
+  });
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error('register3 HTTP ' + res.status + ': ' + res.body.toString('utf8').slice(0, 200));
+  }
+
+  // The answer is a flat key=value list; anything other than a token line is
+  // an error Google chose to report with a 200.
+  const text = res.body.toString('utf8').trim();
+  for (const line of text.split('\n')) {
+    const eq = line.indexOf('=');
+    if (eq > 0 && line.slice(0, eq).trim() === 'token') {
+      const token = line.slice(eq + 1).trim();
+      if (token) return token;
+    }
+  }
+  throw new Error('register3 returned no token: ' + text.slice(0, 200));
+}
+
+// ─── public entry point ──────────────────────────────────────────────────────
+
+/** Whether push-token acquisition is switched on. Opt out with WA_FCM_PUSH=0. */
+function enabled() {
+  const v = process.env.WA_FCM_PUSH;
+  return v === undefined || !(v === '0' || v.toLowerCase() === 'false' || v === 'off');
+}
+
+// A token in hand is reused. Google mints an android id once and expects it
+// back; running checkin again per registration step would present a new phantom
+// device every time.
+function cached(store) {
+  const s = store && store.fcm;
+  return s && s.token ? s.token : null;
+}
+
+/**
+ * The FCM push token for this account, or null.
+ *
+ * Never throws and never rejects: every failure path ends as null, which
+ * attestationFields turns into an omitted field and buildForm leaves out of the
+ * body entirely — byte for byte what registration sent before this existed.
+ *
+ * @param {object} store   the account store; the session is cached on store.fcm
+ * @param {object} device  device config; device.business picks the w4b package
+ * @returns {Promise<string|null>}
+ */
+async function getPushToken(store, device) {
+  if (!enabled()) return null;
+  if (!store) return null;
+
+  const hit = cached(store);
+  if (hit) {
+    _whaDbg('[DBG] FCM push token from cache, length=' + hit.length);
+    return hit;
+  }
+
+  const config = (device && device.business) ? FCM_CONFIG.business : FCM_CONFIG.personal;
+  const prev   = store.fcm || {};
+
+  try {
+    let androidId     = prev.androidId;
+    let securityToken = prev.securityToken;
+
+    if (!androidId || !securityToken) {
+      _whaDbg('[DBG] FCM step 1/3 checkin');
+      const ids = await checkin();
+      androidId     = ids.androidId;
+      securityToken = ids.securityToken;
+    }
+
+    _whaDbg('[DBG] FCM step 2/3 FIS install (' + config.packageName + ')');
+    const fis = await fisInstall(config, prev.fid);
+
+    _whaDbg('[DBG] FCM step 3/3 register3');
+    const token = await register3(config, {
+      androidId, securityToken,
+      fid:           fis.fid,
+      fisAuthToken:  fis.authToken
+    });
+
+    store.fcm = {
+      androidId, securityToken,
+      fid:             fis.fid,
+      fisAuthToken:    fis.authToken,
+      fisRefreshToken: fis.refreshToken,
+      fisExpiresAt:    fis.expiresAt,
+      token
+    };
+    _whaDbg('[DBG] FCM push token acquired, length=' + token.length);
+    return token;
+  } catch (err) {
+    // Keep whatever identity was established: a checkin that succeeded before a
+    // later step failed is worth carrying into the next attempt rather than
+    // minting a second android id.
+    _whaDbg('[DBG] FCM push token unavailable: ' + (err && err.message) +
+      ' — registering without one');
+    return null;
+  }
+}
+
+module.exports = {
+  getPushToken,
+  enabled,
+  FCM_CONFIG,
+  // exported for tests
+  encodeCheckinRequest,
+  decodeCheckinResponse,
+  generateFid,
+  parseDurationSeconds
+};

package/lib/noise.js

@@ -370,15 +370,8 @@ class NoiseSocket extends EventEmitter {
       this._connectResolve = resolve;
       this._connectReject  = reject;
 
-      if (this.transport === 'web') {
-        const { WebSocketStream } = require('./WebSocketStream');
-        this.socket = new WebSocketStream().connect();
-      } else {
-        this.socket = net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT });
-      }
-      // OS-level TCP keepalive: detects silently-dead NAT connections that never send FIN/RST
-      this.socket.setKeepAlive(true, 15000);
-      // Connect-phase watchdog: abort if TCP handshake takes >20s
+      // Armed before the socket exists so it covers a SOCKS handshake that
+      // never completes, not just a TCP one.
       this._connectTimeoutTimer = setTimeout(() => {
         if (this._connectReject) {
           const err = new Error('WA TCP connect timeout (20s)');
@@ -386,16 +379,55 @@ class NoiseSocket extends EventEmitter {
           this._connectResolve = null;
           this._connectReject  = null;
         }
-        try { this.socket.destroy(); } catch (_) {}
+        try { if (this.socket) this.socket.destroy(); } catch (_) {}
       }, 20000);
-      this.socket.on('connect', () => {
-        clearTimeout(this._connectTimeoutTimer);
-        this._connectTimeoutTimer = null;
-        this._onTcpConnect();
-      });
-      this.socket.on('data',    (data) => this._onData(data));
-      this.socket.on('error',   (err)  => this._onTcpError(err));
-      this.socket.on('close',   ()     => this._onTcpClose());
+
+      // `alreadyConnected` is the SOCKS case: the proxy hands back a socket
+      // whose handshake is finished, so no 'connect' event will ever fire on
+      // it and waiting for one would stall until the watchdog fires.
+      const attach = (sock, alreadyConnected) => {
+        this.socket = sock;
+        // OS-level TCP keepalive: detects silently-dead NAT connections that
+        // never send FIN/RST.
+        sock.setKeepAlive(true, 15000);
+
+        sock.on('data',  (data) => this._onData(data));
+        sock.on('error', (err)  => this._onTcpError(err));
+        sock.on('close', ()     => this._onTcpClose());
+
+        const onUp = () => {
+          clearTimeout(this._connectTimeoutTimer);
+          this._connectTimeoutTimer = null;
+          this._onTcpConnect();
+        };
+        if (alreadyConnected) onUp();
+        else sock.on('connect', onUp);
+      };
+
+      if (this.transport === 'web') {
+        const { WebSocketStream } = require('./WebSocketStream');
+        attach(new WebSocketStream().connect(), false);
+        return;
+      }
+
+      // Mobile is a raw TCP socket, and net.createConnection has no notion of
+      // a proxy. Dial through SOCKS when one is configured so the mobile
+      // transport is reachable from the same networks the web one is.
+      const { socksProxyUrl, socksConnect } = require('./socks');
+      const proxyUrl = socksProxyUrl();
+      if (!proxyUrl) {
+        attach(net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT }), false);
+        return;
+      }
+
+      _whaDbg('[DBG] TCP via SOCKS proxy → ' + WHATSAPP_HOST + ':' + WHATSAPP_PORT);
+      socksConnect(proxyUrl, WHATSAPP_HOST, WHATSAPP_PORT)
+        .then(sock => attach(sock, true))
+        .catch(err => {
+          clearTimeout(this._connectTimeoutTimer);
+          this._connectTimeoutTimer = null;
+          this._onTcpError(err);
+        });
     });
   }
 

package/lib/socks.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// SOCKS4 / SOCKS5 / Tor support for every outbound connection the library makes.
+//
+// Set SOCKS_PROXY (or TOR_PROXY) and everything goes through it:
+//
+//   socks5://127.0.0.1:9050              Tor
+//   socks5://user:pass@host:1080         authenticated residential proxy
+//   socks5h://host:1080                  resolve the destination at the proxy
+//   socks4://host:1080                   older proxies
+//
+// Requires the `socks` package, which ships as an optional dependency.
+//
+// Why this module exists at all: the proxy used to be honoured by exactly one
+// call site, the registration POST. Everything else — the App Store and Play
+// Store version lookups, the web client's sw.js revision probe, the WhatsApp
+// Web socket and the mobile TCP socket — went out through `https.get`,
+// `axios` and `net.createConnection`, none of which look at proxy environment
+// variables. Node has no built-in proxy support; an agent has to be handed in.
+//
+// The visible symptom was a connection that "worked" in curl and timed out in
+// the library:
+//
+//   [DBG] WEB_VERSION 2.3000.1035194821 (pinned fallback: sw.js fetch timed out)
+//
+// curl honours SOCKS_PROXY, https.get does not. Same machine, same proxy,
+// opposite results.
+
+const https = require('https');
+const tls   = require('tls');
+
+const SOCKS_SCHEMES = {
+  'socks:':   5,
+  'socks5:':  5,
+  'socks5h:': 5,
+  'socks4:':  4,
+  'socks4a:': 4
+};
+
+// How long a SOCKS handshake may take before it is treated as dead. A proxy
+// that accepts the TCP connection and then says nothing would otherwise hang
+// whatever asked for the connection.
+const SOCKS_TIMEOUT_MS = 20000;
+
+// Resolve the library the way every other dependency is resolved.
+//
+// WA_SOCKS_LIB stays as an escape hatch for unusual layouts, but it is an
+// override, not the only way in.
+function loadSocks() {
+  const override = process.env.WA_SOCKS_LIB;
+  if (override) {
+    try { return require(override); }
+    catch (err) {
+      throw new Error('WA_SOCKS_LIB points at ' + override +
+        ' but it could not be loaded: ' + err.message);
+    }
+  }
+  try {
+    return require('socks');
+  } catch (_) {
+    throw new Error(
+      "A SOCKS proxy is configured but the 'socks' package is not installed. " +
+      'Run: npm install socks'
+    );
+  }
+}
+
+/**
+ * Parse a proxy URL into what SocksClient expects.
+ *
+ * Accepts the schemes above, with or without credentials, and defaults the
+ * port to 1080 the way every SOCKS client does.
+ */
+function parseSocksProxy(proxyUrl) {
+  let raw = String(proxyUrl || '').trim();
+  if (!raw) throw new Error('No SOCKS proxy configured');
+
+  // A bare host:port is what .env.example has always shown and what most people
+  // type. Without a scheme `new URL` reads "127.0.0.1:" as the protocol and the
+  // rest as the path, so it has to be filled in before parsing.
+  if (!/^[a-z0-9+.-]+:\/\//i.test(raw)) raw = 'socks5://' + raw;
+
+  let url;
+  try { url = new URL(raw); }
+  catch (_) { throw new Error('Invalid SOCKS proxy URL: ' + proxyUrl); }
+
+  const type = SOCKS_SCHEMES[url.protocol];
+  if (!type) {
+    throw new Error('Unsupported proxy scheme "' + url.protocol + '" — use ' +
+      Object.keys(SOCKS_SCHEMES).map(s => s.replace(':', '')).join(', '));
+  }
+  if (!url.hostname) throw new Error('SOCKS proxy URL has no host: ' + proxyUrl);
+
+  const proxy = {
+    host: url.hostname,
+    port: parseInt(url.port, 10) || 1080,
+    type
+  };
+  // Credentials may be percent-encoded in a URL; a password with an @ or a :
+  // in it is common enough on paid proxies to be worth decoding.
+  if (url.username) proxy.userId   = decodeURIComponent(url.username);
+  if (url.password) proxy.password = decodeURIComponent(url.password);
+  return proxy;
+}
+
+// TOR_PROXY wins when both are set — the precedence .env.example has always
+// documented. Read from the environment on every call rather than cached at
+// require time, so a process that sets it late still gets it.
+function socksProxyUrl() {
+  return process.env.TOR_PROXY || process.env.SOCKS_PROXY || '';
+}
+
+/** Whether a proxy is configured at all. Cheap, and never throws. */
+function hasProxy() {
+  return !!socksProxyUrl();
+}
+
+/**
+ * Open a raw TCP connection to host:port through the configured proxy.
+ *
+ * Resolves with a connected socket — the SOCKS handshake is already done, so
+ * no 'connect' event will fire on it. Callers that key off 'connect' have to
+ * account for that.
+ */
+async function socksConnect(proxyUrl, host, port, timeoutMs) {
+  const proxy = parseSocksProxy(proxyUrl);
+  const { SocksClient } = loadSocks();
+  const { socket } = await SocksClient.createConnection({
+    proxy,
+    command:     'connect',
+    destination: { host, port },
+    timeout:     timeoutMs > 0 ? timeoutMs : SOCKS_TIMEOUT_MS
+  });
+  return socket;
+}
+
+/**
+ * An https.Agent that tunnels through SOCKS.
+ *
+ * `https.get`, `axios` and `ws` all accept an agent and all drive it the same
+ * way, so one of these covers every HTTPS and WSS call site in the library.
+ *
+ * The base agent's createConnection calls tls.connect on a fresh TCP socket;
+ * this one gets the TCP socket from the proxy first and layers TLS on top of
+ * it. Everything else — pooling, keep-alive, timeouts — is inherited.
+ */
+class SocksHttpsAgent extends https.Agent {
+  constructor(proxyUrl, opts) {
+    super(opts);
+    this._proxyUrl = proxyUrl;
+    // Fail fast on a malformed URL, at construction rather than on first use,
+    // so a typo surfaces as a clear error instead of a stalled request.
+    this._proxy = parseSocksProxy(proxyUrl);
+  }
+
+  createConnection(options, callback) {
+    const { SocksClient } = loadSocks();
+    const host = options.host || options.hostname;
+    const port = Number(options.port) || 443;
+
+    SocksClient.createConnection({
+      proxy:       this._proxy,
+      command:     'connect',
+      destination: { host, port },
+      timeout:     SOCKS_TIMEOUT_MS
+    }).then(({ socket }) => {
+      // servername has to be set explicitly: the TLS socket is built on a
+      // socket that was never given a hostname, so without it SNI goes out
+      // empty and WhatsApp's edge answers with the wrong certificate.
+      const tlsSocket = tls.connect(Object.assign({}, options, {
+        socket,
+        host,
+        port,
+        servername: options.servername || (typeof host === 'string' ? host : undefined)
+      }));
+      callback(null, tlsSocket);
+    }).catch(err => callback(err));
+  }
+}
+
+// One agent per proxy URL. Agents pool sockets, so building a fresh one per
+// request would throw the pool away every time.
+const _agentCache = new Map();
+
+/**
+ * The agent for a given proxy URL, or null when none is configured.
+ *
+ * Never throws: a proxy that cannot be parsed, or a missing `socks` package,
+ * returns null and leaves the caller on a direct connection. A version lookup
+ * that has a pinned fallback must not take the process down over its proxy.
+ */
+function socksAgent(proxyUrl) {
+  const url = proxyUrl || socksProxyUrl();
+  if (!url) return null;
+  if (_agentCache.has(url)) return _agentCache.get(url);
+
+  let agent = null;
+  try {
+    agent = new SocksHttpsAgent(url, { keepAlive: false });
+  } catch (_) {
+    agent = null;
+  }
+  _agentCache.set(url, agent);
+  return agent;
+}
+
+/** The agent for the environment's proxy, or null. */
+function proxyAgent() {
+  return socksAgent(socksProxyUrl());
+}
+
+/** Drop cached agents. For tests, and for a process that swaps proxies. */
+function clearAgentCache() {
+  for (const agent of _agentCache.values()) {
+    if (agent && typeof agent.destroy === 'function') {
+      try { agent.destroy(); } catch (_) {}
+    }
+  }
+  _agentCache.clear();
+}
+
+module.exports = {
+  SOCKS_SCHEMES,
+  SOCKS_TIMEOUT_MS,
+  loadSocks,
+  parseSocksProxy,
+  socksProxyUrl,
+  hasProxy,
+  socksConnect,
+  socksAgent,
+  proxyAgent,
+  clearAgentCache,
+  SocksHttpsAgent
+};

package/package.json

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