whalibmob 5.33.0 → 5.33.2

package/README.md

@@ -29,6 +29,8 @@ code, and bring the account into being. Both transports, one API.
 
 [![Device attestation](https://img.shields.io/badge/Device_attestation-Play_Integrity_%2B_App_Attest-8E44AD?style=for-the-badge)](#device-attestation--play-integrity-and-app-attest)
 
+[![Why registration can be blocked](https://img.shields.io/badge/Why_registration_can_be_blocked-anti--abuse_%26_unofficial--client_checks-C0392B?style=for-the-badge)](#why-registration-can-be-blocked--the-anti-abuse-landscape)
+
 </div>
 
 ##
@@ -2775,6 +2777,50 @@ 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.
 
+## Why Registration Can Be Blocked — The Anti-Abuse Landscape
+
+If registration works on some numbers and fails on others with the same code, the failure is almost never a bug in whalibmob. It is one of two **separate** defences WhatsApp runs, built at different times, for different reasons. Telling them apart is the whole of debugging a block, so this section explains what each one is, where it came from, and what actually moves the needle.
+
+### Two different walls
+
+**Wall 1 — "are you the real app?" (unofficial-client detection).**
+This is the wall built against **modified WhatsApp clients** — GB WhatsApp, FM WhatsApp, YoWhatsApp, WhatsApp Plus and the rest of that family, mods that repackage the official APK to add themes, dual accounts and privacy toggles. WhatsApp fought them for years and, from around 2024, banned tens of millions of the accounts using them in a single wave. The detection that came out of that fight checks three things on every connection: the **APK signature** (is it signed by WhatsApp Inc. or by a mod author?), the **integrity attestation** (does Play Integrity / App Attest vouch that this is the genuine app on a real device?), and **behaviour**.
+
+whalibmob is not a mod — but from the server's point of view a whalibmob request with **empty attestation** produces the same answer to those questions as a mod does: *"I can't prove I'm the official app."* WhatsApp does not read your project's name; it reads signals, and on that signal whalibmob and a mod look alike. That is why the same screens a mod triggers can appear here:
+
+- **`"reason":"blocked"` with a `custom_block_screen`** — *"For security reasons, we can't connect you right now."* The request is refused before the code is even routed.
+- **"We could not confirm you are using the official WhatsApp app,"** often with a link to download it.
+- On a **linked/companion** session, **"Use the official WhatsApp Web to continue"** — the same idea, one layer over, aimed at web-class linked devices.
+
+These tend to appear on numbers that have been **flagged before** (previously banned, or previously seen on an unofficial client). A clean number is usually given the benefit of the doubt and passes with empty attestation; a flagged number has spent that benefit and is asked to *prove* it is the official app — which empty attestation cannot.
+
+**Wall 2 — "are you spamming?" (anti-abuse / IP reputation).**
+This wall is **older than the mods** and unrelated to them. WhatsApp scores the **IP address** the request comes from, and if it belongs to a datacenter, a known VPN range or an address already on a spam list, it is refused regardless of how genuine the client looks. This is what fails **many numbers at once from the same server**: the common factor is not the numbers, it is the IP. It is also what a `no_routes` reply (with every `*_wait` at `3600`) usually means — a routing/rate refusal; cool down for an hour and slow down.
+
+The distinction matters because the fixes are different, and because **Wall 2 would exist even if the mods never had**. Even in a world with no GB WhatsApp, WhatsApp would still stop mass account creation — that is a spam problem it has fought since before any mod existed. There is no configuration that turns a headless server into "unlimited numbers": that is precisely the outcome the anti-abuse system is designed to prevent.
+
+### Reading the reply
+
+| What the server sends back | Which wall | What it means |
+|---|---|---|
+| `"reason":"no_routes"`, every `*_wait: 3600` | Anti-abuse | Can't route the code now; usually the IP or rate. Wait out the cooldown, use a cleaner IP. |
+| `"reason":"blocked"` + `custom_block_screen` | Unofficial-client / reputation | Refused for "security"; the IP and/or the number are distrusted. |
+| "not using the official app" / download link | Unofficial-client | The number is flagged and is being asked to prove it is the genuine app. |
+| `"reason":"consent"`, `"pending":"app_store_age"` | Consent (separate) | See [When Registration Is Refused for Consent](#when-registration-is-refused-for-consent). |
+
+### What actually helps — and what does not
+
+Honest, in order of effect:
+
+- **A clean IP does the most.** A residential or mobile IP, one that is not on a blocklist, clears Wall 2 more than anything else. Datacenter/VPS IPs are the single most common cause of a `blocked` reply across many numbers. Route through a good residential/mobile proxy (see [Routing Traffic Through a Proxy](#routing-traffic-through-a-proxy)), and do not push dozens of numbers through one address.
+- **Clean, unused numbers.** A number that has never been flagged passes with empty attestation. A number that already carries the "unofficial app" screen has been marked, and is usually not worth fighting — a fresh clean number is the better use of time.
+- **The Android profile** (`WA_OS=android`) carries more of the fields the server wants than the iOS one, and is the first thing to try when a number is refused.
+- **Real attestation** answers Wall 1 directly. The Frida scripts in [`frida/`](https://github.com/Kunboruto20/whalibmob/tree/main/frida) mint a genuine Play Integrity / App Attest token **from a real handset with the Play-Store app** and fold it in — this is the honest way to answer "prove you're the official app," because it *is* a real device proving it. It needs a rooted Android or jailbroken iOS phone (see [Device Attestation with Frida](#device-attestation-with-frida-optional)), so it is not always practical; clean numbers do not need it, and no software-only trick substitutes for it.
+
+### The honest bottom line
+
+This is a moving target, not a solved problem. WhatsApp changes these checks continually — the mods went from surviving *months* to surviving *hours* under the same pressure — and whalibmob is kept in step release by release, but nothing here is permanent and there is no magic bypass. Registration on the mobile protocol is a real capability that works, most reliably on **clean numbers from clean IPs**; the further you get from that, the harder the anti-abuse system pushes back, by design.
+
 ## The Push Token
 
 Every WhatsApp on a real phone holds a push token. It is the address the push network uses to wake the app, and no install exists without one — so a registration that ships no `push_token` describes a WhatsApp that cannot be notified, which is a device that does not exist.
@@ -2819,9 +2865,9 @@ Apple's flow is not Google's, but it lands in the same place:
 | 2 | `init-p01st.push.apple.com/bag` | which courier hosts to dial |
 | 3 | `<n>-courier.push.apple.com:443` | the device token, then `GET_TOKEN` for `net.whatsapp.WhatsApp` — the per-topic token that *is* `push_token` |
 
-Step 1 runs once per number and its result is cached on the session: the certificate is good for about three years, and the identity behind it is what makes the same push token come back on the next run. A token WhatsApp has already recorded stops being deliverable if that identity is thrown away, which is the same reason the Firebase android id is kept.
+Step 1 runs once per number and its result is cached on the session: the certificate Apple issues is good for a year, and the identity behind it is what makes the same push token come back on the next run. A token WhatsApp has already recorded stops being deliverable if that identity is thrown away, which is the same reason the Firebase android id is kept.
 
-The courier connection is a TLS stream with ALPN `apns-security-v3` — the device proves itself with a signature over a fresh nonce in the first frame rather than with a TLS client certificate. A network that terminates TLS in the middle cannot carry it, and the failure says so by name instead of looking like a dropped connection.
+The courier connection is a TLS stream that offers ALPN `apns-security-v3` — the device proves itself with a signature over a fresh nonce in the first frame rather than with a TLS client certificate. Apple accepts the offer without echoing it back, so a missing echo is normal and is not treated as a failure. A network that terminates TLS in the middle cannot carry the stream; what gives it away is the certificate, since a middlebox has to present one its own CA signed rather than Apple's. The failure names that issuer, instead of looking like a dropped connection.
 
 Turn it off with `WA_APNS_PUSH=0`.
 

package/lib/apns-courier.js

@@ -215,17 +215,22 @@ function parseBag(body) {
 /**
  * Where to ask for the bag, in the order to try.
  *
- * HTTPS first because that is the one a proxied session can route: the SOCKS
- * agent is an https.Agent, so a plain-HTTP attempt would go out direct and
- * around the proxy the user asked for. When one is configured the fallback is
- * dropped rather than leaked — the default pool is the better answer.
+ * Plain HTTP is the canonical URL and the one that actually answers: the bag is
+ * signed rather than encrypted, and the host does not serve a certificate for
+ * its own name — it presents one for images.apple.com, so HTTPS fails the
+ * hostname check every time. It is tried second only in case that ever changes.
+ *
+ * With a proxy configured the order inverts and HTTP is dropped entirely: the
+ * SOCKS agent is an https.Agent, so a plain-HTTP attempt would go out direct,
+ * around the proxy the user set precisely so that nothing does. Losing the bag
+ * costs nothing — the default pool below is the same answer it would have
+ * given.
  *
  * @returns {string[]}
  */
 function bagUrls() {
-  const urls = ['https://' + BAG_HOST + BAG_PATH];
-  if (!socksProxyUrl()) urls.push('http://' + BAG_HOST + BAG_PATH);
-  return urls;
+  if (socksProxyUrl()) return ['https://' + BAG_HOST + BAG_PATH];
+  return ['http://' + BAG_HOST + BAG_PATH, 'https://' + BAG_HOST + BAG_PATH];
 }
 
 async function fetchBag() {
@@ -278,6 +283,34 @@ function certificateDer(certificate) {
   return new crypto.X509Certificate(certificate).raw;
 }
 
+// A certificate field can repeat, and Node hands a repeated one back as an
+// array, so every read goes through this rather than assuming a string.
+function issuerValues(issuer, field) {
+  if (!issuer || issuer[field] == null) return [];
+  return [].concat(issuer[field]).map(String);
+}
+
+/**
+ * Whether the courier's certificate was issued by Apple.
+ *
+ * A middlebox that terminates TLS has to present its own certificate, signed
+ * by its own CA, because it cannot hold Apple's key. So the issuer's
+ * organisation is the one field that tells the real courier from something
+ * standing in front of it.
+ *
+ * @param {object|null} issuer  the issuer from getPeerCertificate()
+ * @returns {boolean}
+ */
+function isApplePeer(issuer) {
+  return issuerValues(issuer, 'O').includes('Apple Inc.');
+}
+
+/** A readable name for an issuer, for a log line or an error message. */
+function describeIssuer(issuer) {
+  const name = issuerValues(issuer, 'CN')[0] || issuerValues(issuer, 'O')[0];
+  return name ? '"' + name + '"' : 'an unnamed issuer';
+}
+
 // ─── The connection ───────────────────────────────────────────────────────────
 
 class ApnsCourierConnection {
@@ -296,6 +329,10 @@ class ApnsCourierConnection {
     this.onLost = typeof opts.onLost === 'function' ? opts.onLost : null;
 
     this.socket = null;
+    // Who signed the certificate the courier presented, set by the TLS
+    // handshake. Null until a socket exists, so a failure that happens before
+    // one does carries no note about interception.
+    this.peerIssuer = null;
     this.deviceToken = session.deviceToken || null;
     // Set by the handshake when Apple hands back a device token other than the
     // one presented. False until then, including before any connection.
@@ -329,6 +366,15 @@ class ApnsCourierConnection {
       // from. Callers do close on failure, but the connection should not depend
       // on them remembering to.
       this.close();
+      // A failure on a connection whose certificate Apple did not sign is the
+      // signature of TLS being terminated in the middle: the courier never saw
+      // the frame, something else did and hung up. Worth naming, because the
+      // error on its own reads like Apple refused the credentials.
+      if (this.peerIssuer && !isApplePeer(this.peerIssuer)) {
+        err.message += ' (the courier presented a certificate from ' +
+          describeIssuer(this.peerIssuer) + ', not Apple — TLS is being' +
+          ' intercepted on this network)';
+      }
       throw err;
     }
     return this;
@@ -345,14 +391,17 @@ class ApnsCourierConnection {
         host,
         port: COURIER_PORT,
         servername: host,
+        // Offered as every client offers it. Apple accepts it without echoing
+        // it back — see the issuer check below for what that means.
         ALPNProtocols: [COURIER_ALPN],
-        // The courier answers with a certificate from an Apple-internal issuer
-        // that is in no public trust store, so chain validation cannot succeed
-        // here and is not what protects this connection: the device proves
-        // itself with a signature over a fresh nonce, and every push that
-        // matters is a WhatsApp payload the registration server signs for
-        // separately. Verification stays on for every other socket in the
-        // library — this is the one endpoint that cannot use it.
+        // The courier answers with a certificate from Apple Server
+        // Authentication CA, which chains to an Apple root that is not in
+        // Node's bundled trust store, so chain validation cannot succeed here
+        // and is not what protects this connection: the device proves itself
+        // with a signature over a fresh nonce, and every push that matters is
+        // a WhatsApp payload the registration server signs for separately.
+        // Verification stays on for every other socket in the library — this
+        // is the one endpoint that cannot use it.
         rejectUnauthorized: false
       };
       if (base) options.socket = base;
@@ -360,18 +409,17 @@ class ApnsCourierConnection {
       const socket = tls.connect(options, () => {
         socket.setTimeout(0);
         socket.setNoDelay(true);
-        // The courier speaks its own protocol over the TLS session, and says so
-        // through ALPN. A middlebox that terminates TLS — a corporate gateway,
-        // an inspecting proxy — negotiates no protocol at all and then drops
-        // the connection the moment a frame that is not HTTP goes out. Saying
-        // that here turns an unexplained disconnect into the one line that
-        // names the cause.
-        if (socket.alpnProtocol !== COURIER_ALPN) {
-          socket.destroy();
-          reject(new Error('courier did not negotiate ' + COURIER_ALPN +
-            ' (TLS is being intercepted on this network)'));
-          return;
-        }
+        // Who signed the certificate on the other end. This, not ALPN, is what
+        // tells a genuine courier from a middlebox: Apple's courier accepts the
+        // apns-security-v3 offer without echoing it back, so a missing echo is
+        // what the real thing looks like too. A first version refused any
+        // connection that did not echo it, and so refused Apple itself.
+        //
+        // The issuer is recorded, not enforced. The handshake decides; this
+        // only explains a failure afterwards.
+        const certificate = socket.getPeerCertificate() || {};
+        this.peerIssuer = certificate.issuer || null;
+        _whaDbg('[DBG] APNs courier certificate issued by ' + describeIssuer(this.peerIssuer));
         resolve(socket);
       });
       socket.setTimeout(CONNECT_TIMEOUT_MS, () => socket.destroy(new Error('courier connect timed out')));
@@ -617,6 +665,8 @@ module.exports = {
   topicHash,
   createNonce,
   certificateDer,
+  isApplePeer,
+  describeIssuer,
   TAG,
   DEFAULT_BAG,
   F_NOTIFICATION_TOPIC,

package/lib/apns.js

@@ -16,7 +16,7 @@
 //                   we generate, given a FairPlay-signed request. This is what
 //                   a Mac or an iPhone does on first boot, and what every
 //                   desktop iMessage/APNs client has done since. The
-//                   certificate is good for about three years, so it is
+//                   certificate Apple signs is good for a year, so it is
 //                   persisted with the account and the handshake runs once.
 //   2. courier      one TLS connection to Apple carrying the device token, and
 //                   over it GET_TOKEN for net.whatsapp.WhatsApp — the per-topic

package/package.json

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