whalibmob 5.32.2 → 5.33.1

package/.env.example

@@ -145,16 +145,18 @@
 # 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.
+# Every WhatsApp on a real phone holds a push token — it is how the server wakes
+# the app. Registration fetches one and ships it as push_token, so the request
+# looks like the install it claims to be. Which network it comes from follows
+# from WA_OS: Firebase on android, APNs on ios. The two are not interchangeable.
 #
-# 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.
+# Both on by default, 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.
+# Set either to 0 to skip that one entirely.
 # WA_FCM_PUSH=0
+# WA_APNS_PUSH=0
 
 
 # ─── Registration funnel telemetry ───────────────────────────────────────────

package/README.md

@@ -254,6 +254,8 @@ npm install -g whalibmob
   - [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)
   - [The Push Token](#the-push-token)
+    - [On Android: Firebase](#on-android-firebase)
+    - [On iOS: APNs](#on-ios-apns)
     - [Receiving the Code over Push](#receiving-the-code-over-push-without-typing-it)
   - [Routing Traffic Through a Proxy](#routing-traffic-through-a-proxy)
     - [What Goes Through It](#what-goes-through-it)
@@ -1871,7 +1873,7 @@ if (result.status === 'ok') {
 }
 ```
 
-**Optional — let the code arrive by itself.** The two steps above are the whole flow, and nothing about them changes if you do nothing else. But because an Android registration sends a Firebase push token (see [The Push Token](#the-push-token)), WhatsApp *may* also deliver the six-digit code as a silent push. Open a listener for it before requesting the code, and the code can come back with nothing typed — on an `WA_OS=android` profile; on iOS it resolves `null` straight away, since only Firebase is implemented:
+**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 a registration sends a push token (see [The Push Token](#the-push-token)), WhatsApp *may* also deliver the six-digit code as a silent push. Open a listener for it before requesting the code, and the code can come back with nothing typed — on an Android profile over Firebase, on an iOS one over APNs:
 
 ```js
 const { receivePushCode } = require('whalibmob')
@@ -2777,7 +2779,7 @@ If that is refused too, the number has to go through the real app once, on a pho
 
 Every WhatsApp on a real phone holds a push token. It is the address the push network uses to wake the app, and no install exists without one — so a registration that ships no `push_token` describes a WhatsApp that cannot be notified, which is a device that does not exist.
 
-**This is an Android-profile feature.** Which push network an install uses follows from its platform: Android holds a *Firebase* token and keeps a stream open to Google, iOS holds an *APNs* token and keeps one open to Apple. They are not interchangeable, and the registration server sees both the token and the User-Agent naming the platform that sent it — an iPhone presenting a Firebase token describes a device nobody ships. Only the Firebase side is implemented here, so everything in this section applies when `WA_OS=android`. An iOS registration sends no `push_token` at all, which is the correct thing for a client with no push line, and every other part of the flow is unaffected.
+**Which token you get follows from the profile.** Which push network an install uses follows from its platform: Android holds a *Firebase* token and keeps a stream open to Google, iOS holds an *APNs* token and keeps one open to Apple. They are not interchangeable, and the registration server sees both the token and the User-Agent naming the platform that sent it — an iPhone presenting a Firebase token describes a device nobody ships. Both sides are implemented, and the right one is chosen from `WA_OS` without you asking for it. A profile that is neither sends no `push_token` at all, which is the correct thing for a client with no push line.
 
 The token does two distinct jobs, and it is easy to conflate them:
 
@@ -2791,6 +2793,8 @@ request a code ─┬─ method you chose  →  reaches a human   (SMS, a call,
                 └─ push_token line   →  reaches the app    (silent, auto-filled — if WhatsApp sends it)
 ```
 
+### On Android: Firebase
+
 Registration fetches a real token and sends it, in three plain HTTPS calls to Google:
 
 | Step | Endpoint | Yields |
@@ -2803,15 +2807,36 @@ No root, no Frida, no phone. This is unrelated to Play Integrity attestation —
 
 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`.
 
+### On iOS: APNs
+
+Apple's flow is not Google's, but it lands in the same place:
+
+| Step | Endpoint | Yields |
+|---|---|---|
+| 1 | `albert.apple.com` | a device certificate Apple signs for a keypair generated here — the activation every Apple device runs on first boot |
+| 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 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 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`.
+
+**Failure is silent by design, on both platforms.** A blocked network, a refusal from Google or Apple, 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.
+
 ### 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.
+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 push line to catch it — the same long-lived connection every phone keeps open to its push network. `receivePushCode(store, device)` opens the one that matches the profile:
+
+| Profile | Connection | Where the code is |
+|---|---|---|
+| `WA_OS=android` | `mtalk.google.com:5228`, the MCS protocol, logged in with the Firebase identity | an `appData` entry keyed `registration_code` |
+| `WA_OS=ios` | `<n>-courier.push.apple.com:443`, the APNs courier, authenticated with the activation certificate | the `regcode` field of the notification's JSON payload |
 
-Like the token itself, this is Android-only. On an iOS profile `receivePushCode` resolves `null` immediately rather than holding a listener open on a line no push can reach, and `/reg push` says so and stops instead of waiting out its timeout. Check with `supportsPush(store.device)` if you want to branch on it.
+Either way the call resolves with the code the moment a push carrying it arrives. A profile that is neither resolves `null` immediately rather than holding a listener open on a line no push can reach, and `/reg push` says so and stops instead of waiting out its timeout. Check with `supportsPush(store.device)` if you want to branch on it.
 
 The order matters. Open the listener **first**, so the line is live before the code is requested; then request the code by whatever method; then await it.
 
@@ -2838,7 +2863,7 @@ From the CLI the whole sequence is one command:
 
 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.
+Either connection carries a heartbeat and acknowledges what it has read, 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.

package/cli.js

@@ -663,7 +663,7 @@ 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 push    <phone> [sms|voice]                  request code and receive it over push
     /reg confirm <phone> <code>                       complete registration
 
   Connection
@@ -2424,7 +2424,8 @@ async function handleLine(line) {
           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('  opens the push listener this device profile keeps open — Firebase');
+            out('  on Android, APNs on iOS — 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.');
@@ -2439,24 +2440,25 @@ async function handleLine(line) {
           if (!store) { store = initAuthCreds(ph, { name: regName }); saveStore(store, sessFile); }
           if (!store.device) store.device = getDeviceConfig();
 
-          // Push verification needs a push line, and only Android has one here.
-          // An iOS session holds no Firebase identity, so the listener would sit
-          // for three minutes on a push that can never be routed to it. Say so
-          // now instead, and point at the two things that do work.
+          // Push verification needs a push line, and it has to be the one the
+          // announced platform actually keeps open. Android and iOS both have
+          // one; a profile that is neither would sit for three minutes on a push
+          // that can never be routed to it, so say so now instead.
           const pushClient = pushClientFor(store.device);
           if (!pushClient.supportsPush) {
             fail('push verification is not available for this device profile (' +
                  (store.device.os || 'unknown') + ')');
             out('  the code arrives over the push line of the platform being announced,');
-            out('  and only Android has one implemented (Firebase). iOS needs APNs.');
-            out('  either register this number on an Android profile:');
-            out('    WA_OS=android  (see /device) and re-run /reg push ' + ph);
+            out('  and only android and ios have one (Firebase and APNs).');
+            out('  either register this number on one of those profiles:');
+            out('    WA_OS=android  or  WA_OS=ios  (see /device) and re-run /reg push ' + ph);
             out('  or use the ordinary path:  /reg code ' + ph + '  then  /reg confirm ' + ph + ' <code>');
             break;
           }
           const receivePushCode = (s, d, o) => pushClient.receivePushCode(s, d, o);
 
-          out('opening Firebase push listener (this can take a moment)...');
+          out('opening the ' + (pushClient.platform === 'ios' ? 'APNs' : '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.

package/index.d.ts

@@ -1779,6 +1779,12 @@ export declare const Tokens: LibModule;
 export declare const PushClient: LibModule;
 export declare const Fcm: LibModule;
 export declare const FcmMcs: LibModule;
+/** `whalibmob/lib/apns` — the iOS push line: activation, token, push code. */
+export declare const Apns: LibModule;
+/** `whalibmob/lib/apns-courier` — the APNs stream the push code arrives on. */
+export declare const ApnsCourier: LibModule;
+/** `whalibmob/lib/plist` — Apple property lists, as APNs speaks them. */
+export declare const Plist: LibModule;
 
 /**
  * X25519 through Node's own OpenSSL — a drop-in for `curve25519-js`, roughly

package/index.js

@@ -81,8 +81,9 @@ const {
 // code over push" in the README.
 //
 // Routed through the push client for the device's platform: Android opens the
-// Firebase MCS stream, iOS resolves null because APNs is not implemented and
-// an iOS session holds no Firebase identity to listen with.
+// Firebase MCS stream, iOS the APNs courier. Either way the code arrives over
+// the line the announced platform actually keeps open, and a profile with no
+// push transport resolves null rather than listening on somebody else's.
 const receivePushCode = (store, device, opts) => {
   const dev = device || (store && store.device);
   return require('./lib/PushClient')
@@ -131,6 +132,9 @@ const Tokens           = require('./lib/tokens');
 const PushClient       = require('./lib/PushClient');
 const Fcm              = require('./lib/fcm');
 const FcmMcs           = require('./lib/fcm-mcs');
+const Apns             = require('./lib/apns');
+const ApnsCourier      = require('./lib/apns-courier');
+const Plist            = require('./lib/plist');
 
 const PairingCode      = require('./lib/PairingCode');
 const CompanionPairing = require('./lib/CompanionPairing');
@@ -372,6 +376,9 @@ module.exports = {
   PushClient,
   Fcm,
   FcmMcs,
+  Apns,
+  ApnsCourier,
+  Plist,
 
   // Linking to an account that already exists
   // X25519, through Node's own OpenSSL. Drop-in for curve25519-js.

package/lib/PushClient.js

@@ -12,15 +12,16 @@
 //
 // This module is the seam. `pushClientFor(device)` returns the client that
 // matches the device profile, so no caller has to reach for a transport by
-// name. Two implementations exist today:
+// name. Both platforms are implemented:
 //
-//   android → ./fcm  (checkin → FIS install → register3, then MCS for the code)
-//   ios     → NONE   (APNs is not implemented; every push field is omitted)
+//   android → ./fcm   (checkin → FIS install → register3, then MCS for the code)
+//   ios     → ./apns  (albert activation → courier GET_TOKEN, then the courier
+//                      stream for the code)
 //
-// The NONE client is not a failure path — it is the correct answer for a
-// platform we cannot speak push for. It supplies nothing, `buildForm` drops the
-// null, and the registration body goes out without a push token rather than
-// with somebody else's.
+// Anything else gets NONE, which is not a failure path — it is the correct
+// answer for a platform we cannot speak push for. It supplies nothing,
+// `buildForm` drops the null, and the registration body goes out without a push
+// token rather than with somebody else's.
 
 const { dbg: _whaDbg } = require('./logger');
 
@@ -63,13 +64,34 @@ const FCM_PUSH_CLIENT = {
   }
 };
 
+/**
+ * The push client backed by Apple Push Notification service, for iOS profiles.
+ *
+ * Delegates to ./apns, which owns the albert activation and the courier
+ * stream. Lazy for the same reason as the Firebase client above: a session that
+ * never registers should not pay for either stack.
+ */
+const APNS_PUSH_CLIENT = {
+  platform: 'ios',
+  supportsPush: true,
+
+  async getPushToken(store, device) {
+    return require('./apns').getPushToken(store, device);
+  },
+
+  async receivePushCode(store, device, opts) {
+    return require('./apns').receivePushCode(store, device, opts);
+  }
+};
+
 /**
  * The push client matching a device profile.
  *
- * Android profiles get the Firebase client; everything else gets NONE. The
- * choice is made on the device rather than on a global setting, because a
- * process can register an Android session and an iOS session in turn and each
- * has to present its own platform's push line — or none at all.
+ * Android profiles get the Firebase client, iOS profiles the APNs one, and
+ * everything else NONE. The choice is made on the device rather than on a
+ * global setting, because a process can register an Android session and an iOS
+ * session in turn and each has to present its own platform's push line — or
+ * none at all.
  *
  * @param {object} device  a device config; only `device.os` is read
  * @returns {{platform: string, supportsPush: boolean,
@@ -77,6 +99,7 @@ const FCM_PUSH_CLIENT = {
  */
 function pushClientFor(device) {
   if (device && device.os === 'android') return FCM_PUSH_CLIENT;
+  if (device && device.os === 'ios') return APNS_PUSH_CLIENT;
 
   if (device && device.os) {
     _whaDbg('[DBG] no push transport for ' + device.os + ' — push fields omitted');
@@ -102,5 +125,6 @@ module.exports = {
   pushClientFor,
   supportsPush,
   NONE_PUSH_CLIENT,
-  FCM_PUSH_CLIENT
+  FCM_PUSH_CLIENT,
+  APNS_PUSH_CLIENT
 };

package/lib/Registration.js

@@ -1517,10 +1517,10 @@ async function buildPayload(store, waVersion, useToken, extraPairs) {
       .digest()
   );
   // The push token a real install always has, taken from the transport that
-  // matches this device's platform: Firebase for Android, nothing for iOS until
-  // APNs exists. Asking ./fcm directly would have put a Google token in an
-  // iPhone's registration body — a device that keeps an MCS stream to Google
-  // and announces itself as iOS is not a device anyone ships.
+  // matches this device's platform: Firebase for Android, APNs for iOS. Asking
+  // ./fcm directly would put a Google token in an iPhone's registration body —
+  // a device that keeps an MCS stream to Google and announces itself as iOS is
+  // not a device anyone ships.
   //
   // Acquired once and cached on the store, so the two registration steps share
   // one. Returns null on any failure or on a platform with no transport, which

package/lib/Store.js

@@ -213,6 +213,12 @@ function storeToJson(store) {
     // 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,
+    // The same thing on the iOS side: the Apple-signed device certificate, the
+    // keypair it was issued against, and the tokens derived from them. Dropping
+    // it costs an activation round-trip and, worse, changes the push_token
+    // WhatsApp has already recorded — so the verification push would be
+    // addressed to a device nobody is listening as.
+    apns:           store.apns || null,
     name,
     version,
     device,
@@ -263,6 +269,9 @@ function storeFromJson(obj) {
     // Absent on stores written before push tokens existed; null simply means
     // the first registration step will fetch one.
     fcm:            obj.fcm || null,
+    // Same, for the APNs side. Absent means the first registration step runs
+    // the activation handshake once and writes the result back here.
+    apns:           obj.apns || null,
     name,
     version,
     device,