whalibmob 5.12.10 → 5.12.13

package/.env.example

@@ -53,13 +53,41 @@
 # ─── WhatsApp version ────────────────────────────────────────────────────────
 # Pin the WhatsApp client version. When set, the live version lookup is skipped
 # entirely. Leave unset to fetch the current version automatically (recommended).
+#
+# On Android this is normally not needed either way: the version is taken from
+# the APK the token material came from, since the token is signed over that
+# build. Setting this still overrides it.
 # WA_VERSION=2.24.10.75
 
-# Override the static registration token. Leave unset to use the built-in token
-# for the selected platform — only change this if you know what you are doing.
+# Override the static registration token. iOS only — Android has no static token
+# and signs its own out of the APK (see below). Leave unset to use the built-in
+# one; only change this if you know what you are doing.
 # WA_STATIC_TOKEN=
 
 
+# ─── Android registration token material ─────────────────────────────────────
+# Registering with WA_OS=android needs material read out of a WhatsApp APK. The
+# first registration fetches the APK from Google Play and does this on its own —
+# nothing to run first. To do it by hand, from a Play download or an APK you
+# already have:
+#
+#     wa apk-material --download
+#     wa apk-material base.apk [split_config.xxhdpi.apk ...]
+#
+# It is written to <session dir>/android-apk-material.json by default. Set this
+# to keep it somewhere else. Registering as iOS needs none of it.
+# WA_ANDROID_APK_MATERIAL=/path/to/android-apk-material.json
+
+# Never fetch the APK automatically. Registration then fails with instructions
+# instead of pulling a hundred megabytes unasked.
+# WA_NO_APK_DOWNLOAD=1
+
+# Register with material from an APK that is not signed by WhatsApp. Refused by
+# default, because a re-signed APK yields a token that belongs to nobody and
+# spends code requests against your number for nothing.
+# WA_ALLOW_FOREIGN_APK=1
+
+
 # ─── Proxy ───────────────────────────────────────────────────────────────────
 # Route registration traffic through a SOCKS proxy. Requires the `socks`
 # package: npm install socks

package/README.md

@@ -120,6 +120,10 @@ npm install -g whalibmob
 - [Library API](#library-api)
   - [Connecting Account](#connecting-account)
     - [Register a New Number](#register-a-new-number)
+    - [Registering as Android](#registering-as-android)
+      - [Why an APK is involved at all](#why-an-apk-is-involved-at-all)
+      - [Fetching the APK on its own](#fetching-the-apk-on-its-own)
+      - [Reading it out of an APK you already have](#reading-it-out-of-an-apk-you-already-have)
     - [Device Attestation with Frida (optional)](#device-attestation-with-frida-optional)
     - [Connect](#connect)
   - [Linking to an Existing Account (Pairing Code)](#linking-to-an-existing-account-pairing-code)
@@ -286,6 +290,16 @@ wa registration --request-code 919634847671 --method voice
 wa registration --request-code 919634847671 --method wa_old
 ```
 
+**Registering as Android** is the same command with the platform named. Nothing
+else to prepare — see [what it does behind that one command](#registering-as-android):
+
+```sh
+WA_OS=android WA_DEVICE=samsung-s24-ultra wa registration --request-code 919634847671 --debug
+```
+
+Set `WA_OS=android` in a `.env` file instead and the plain command is enough.
+`--debug` prints every request and reply, which is worth having the first time.
+
 The CLI sends the code request, prints the result, and then **stays open** in the interactive shell. You will see:
 
 ```
@@ -1544,6 +1558,148 @@ Both are optional and both keep working when omitted — you get an error naming
 > [!NOTE]
 > Registration reports the screens it passes through to WhatsApp's `/client_log`, the way the phone clients do — a client that registers in total silence does something no real installation does. It is fire-and-forget and every failure is swallowed, so it can never take a registration down. Set `WA_FUNNEL_LOG=0` to send none of it.
 
+### Registering as Android
+
+**There is nothing to do first.** Name the platform and register:
+
+```sh
+WA_OS=android WA_DEVICE=samsung-s24-ultra wa registration --request-code 919634847671 --debug
+```
+
+The first Android registration finds no token material, fetches the WhatsApp APK
+from Google Play, reads what it needs out of it, checks that WhatsApp really
+signed it, and carries on to the code request — one command, no APK to find:
+
+```
+no Android token material yet — fetching the WhatsApp APK from Google Play
+    version 2.26.30.3 (code 263000302)
+    downloading base.apk and 1 density split (of 24 the server offered): config.xxxhdpi
+    token material written to /home/you/.waSession/android-apk-material.json
+requesting sms code for +919634847671...
+  status  sent
+```
+
+It happens once. Every later registration reads the file. `WA_NO_APK_DOWNLOAD=1`
+turns the fetch off if you would rather it never pulled a hundred megabytes
+unasked, and `wa apk-material` below does the same job by hand.
+
+The rest of this section is what happens behind that one command, and how to
+drive each part yourself.
+
+#### Why an APK is involved at all
+
+The registration token is computed differently on each platform, and only iOS
+derives it from a constant. The Android client signs it with material out of its
+own APK:
+
+```
+key   = PBKDF2-HMAC-SHA1(password = "com.whatsapp" + about_logo.png,
+                         salt = fixed, iterations = 128, length = 64)
+token = urlencode(base64(HMAC-SHA1(key, signing certificates
+                                      + MD5(classes.dex)
+                                      + national number)))
+```
+
+None of that can be derived, so it has to be read out of a real APK once. Sending
+the iOS-shaped token as Android is answered with `{"reason":"bad_token"}`, and no
+value in `WA_STATIC_TOKEN` changes that — the constant is not what is wrong, the
+formula is. `WA_STATIC_TOKEN` applies to iOS only.
+
+#### Fetching the APK on its own
+
+This runs by itself on a registration that finds no material. To do it separately
+— to refresh after a WhatsApp release, or just to see what it picks up:
+
+```sh
+wa apk-material --download
+```
+
+It is the route Cobalt takes: an anonymous Play Store token from the Aurora OSS
+dispenser, then Google's own `/fdfe` catalogue and delivery endpoints, then the
+signed CDN URLs. **No Google account of yours is involved.** Only the density
+splits are downloaded — the token's key comes from `about_logo.png`, which lives
+in one of those, and the architecture and language splits would be a hundred
+megabytes nothing here reads.
+
+Two caveats. The dispenser is a free third-party service: when it is down or rate
+limiting, this fails and an APK from a phone still works. And downloading from
+Play this way is against Play's terms of service, which is your call to make.
+
+Play serves the splits that suit the device profile it is asked as, not the full
+set a bundle holds, so the density this yields can differ from the one in a
+complete bundle — and a different density is a different key. The `about_logo`
+line in the output names which one was used.
+
+#### Reading it out of an APK you already have
+
+Pull one off any phone or emulator that has WhatsApp installed:
+
+```sh
+adb shell pm path com.whatsapp
+# package:/data/app/~~xyz==/com.whatsapp-abc==/base.apk
+# package:/data/app/~~xyz==/com.whatsapp-abc==/split_config.xxhdpi.apk
+adb pull /data/app/~~xyz==/com.whatsapp-abc==/base.apk
+adb pull /data/app/~~xyz==/com.whatsapp-abc==/split_config.xxhdpi.apk
+```
+
+Recent releases ship as an App Bundle, so `about_logo.png` often lives in a
+density split rather than in `base.apk`. Pull the `split_config.*dpi.apk` files
+too and pass them along — only splits whose name ends in `dpi` are searched.
+
+**Read the material out of it:**
+
+```sh
+wa apk-material base.apk split_config.xxhdpi.apk
+```
+
+```
+reading base.apk...
+  package               com.whatsapp
+  version               2.26.25.80  (code 260908001)
+  certificates          1
+  signed by             C=US, ST=California, L=Santa Clara, O=WhatsApp Inc., …
+  sha256                AD:AD:64:31:29:8F:64:2B:…
+  classes.dex md5       5c71f02aaad331e16e436bfa83ea3c5b
+  written to            /home/you/.waSession/android-apk-material.json
+```
+
+**Watch the `signed by` line.** The token is an HMAC over the signing
+certificates, so it is only the token the server expects when those certificates
+are WhatsApp's own. Mirrors re-sign the APKs they host, commonly with the AOSP
+test key whose private half ships in the Android sources — a re-signed APK yields
+a token that is well-formed and belongs to nobody. Anything other than WhatsApp
+in that subject is called out here as a warning, and registration refuses to
+start on it rather than spending code requests against your number on something
+that cannot succeed. `WA_ALLOW_FOREIGN_APK=1` sends it anyway.
+
+Only the derived pieces are kept — the APK is never needed again. Registration
+picks the file up on its own from then on. `--out <file>` writes it elsewhere,
+and `WA_ANDROID_APK_MATERIAL` points at it if you keep it somewhere else.
+
+**The version comes from the APK too.** It is read out of the binary
+`AndroidManifest.xml` and announced from then on, instead of the version the Play
+Store currently lists. The token is signed over *this* build's `classes.dex`, so
+announcing any other version describes a build the token does not belong to.
+`WA_VERSION` still overrides everything if you need it to; on a manifest with no
+`versionName`, pass `--version <x.y.z.w>`.
+
+**Refresh it on a new WhatsApp release.** `classes.dex` changes every release and
+its MD5 is signed into the token, so material from an older build stops matching
+the version being announced. `wa apk-material --download` re-reads the current
+one; deleting the file and registering again does the same thing on its own.
+
+Programmatically:
+
+```js
+const { extractMaterial, computeToken, materialToJson } = require('whalibmob/lib/AndroidApk')
+
+const material = extractMaterial(
+  fs.readFileSync('base.apk'),
+  [{ name: 'split_config.xxhdpi.apk', data: fs.readFileSync('split_config.xxhdpi.apk') }]
+)
+fs.writeFileSync('android-apk-material.json', JSON.stringify(materialToJson(material)))
+```
+
 ### Device Attestation with Frida (optional)
 
 WhatsApp's registration servers score every `/code` and `/register` request on how

package/cli.js

@@ -252,9 +252,26 @@ function enableWireTrace() {
     };
     req.on('response', (res) => {
       trace(`\n${C.http}${stamp()} ◀── HTTP ${res.statusCode} from ${host}${C.off}`);
-      let body = '';
-      res.on('data', d => { if (body.length < 8192) body += d.toString('utf8'); });
-      res.on('end', () => { if (body) trace(`  ${C.dim}${body}${C.off}`); });
+      // Registration answers in JSON, so the body was printed as text. An APK
+      // download answers in tens of megabytes of binary, and printing that as
+      // text emptied a terminal full of control characters. Keep a bounded head
+      // of it, decide from those bytes whether it is text at all, and say what
+      // it was rather than showing it when it is not.
+      const head = [];
+      let seen = 0, total = 0;
+      res.on('data', (d) => {
+        total += d.length;
+        if (seen < 4096) { head.push(d); seen += d.length; }
+      });
+      res.on('end', () => {
+        if (!total) return;
+        const buf = Buffer.concat(head).slice(0, 4096);
+        if (isPrintable(buf)) {
+          trace(`  ${C.dim}${buf.toString('utf8')}${total > buf.length ? ' …' : ''}${C.off}`);
+        } else {
+          trace(`  ${C.dim}[${total} bytes, binary]${C.off}`);
+        }
+      });
     });
     return req;
   };
@@ -2068,7 +2085,7 @@ async function handleLine(line) {
           }
           const methodLabel = method === 'email' ? ('email → ' + emailAddr) : method;
           out('requesting ' + methodLabel + ' code for +' + ph + '...');
-          const codeOpts = method === 'email' ? { email: emailAddr } : {};
+          const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {}, { onProgress: out });
           const r = await requestSmsCode(store, method, codeOpts);
           store.codePending = true;
           saveStore(store, sessFile);
@@ -2083,7 +2100,7 @@ async function handleLine(line) {
           const file  = path.join(_sessDir, `${ph}.json`);
           const store = loadStore(file) || initAuthCreds(ph);
           out('verifying...');
-          const r = await verifyCode(store, code, registrationPrompts());
+          const r = await verifyCode(store, code, Object.assign(registrationPrompts(), { onProgress: out }));
           if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
             if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
             const finalStore = r.store || store;
@@ -2328,10 +2345,13 @@ usage:
   wa registration --request-code <phone>    request SMS code
   wa registration --register <phone> --code <code>
   wa registration --check <phone>
+  wa apk-material <base.apk> [split.apk ...]  read the Android token material
+  wa apk-material --download                  fetch that APK from Google Play
   wa version
 
 options:
   --session <dir>   session directory  (default: ~/.waSession)
+  --out <file>      where apk-material writes  (default: <session dir>/android-apk-material.json)
   --sms             connect by registering this number over SMS
   --pair            connect by linking to an existing account (8-digit code)
   --method          sms | voice | wa_old | email  (default: sms)
@@ -2434,6 +2454,86 @@ async function main() {
     return;
   }
 
+  // Read the Android registration token material out of a WhatsApp APK.
+  //
+  // Registering as Android signs its token with the APK's own signing
+  // certificates, the MD5 of its classes.dex, and a key derived from
+  // about_logo.png — none of which can be derived, so they are read out of a
+  // real APK once and kept. Registering as iOS needs none of it.
+  if (cmd === 'apk-material') {
+    // parseArgs puts the first non-flag argument in sub, the rest in pos.
+    const apks = [sub, ...pos].filter(Boolean);
+    if (!apks.length && !flags.download) {
+      fail('usage: wa apk-material <base.apk> [split.apk ...]');
+      out('       wa apk-material --download        fetch the APK from Google Play instead');
+      process.exit(1);
+    }
+    const outFile = flags.out ||
+      process.env.WA_ANDROID_APK_MATERIAL ||
+      path.join(_sessDir, 'android-apk-material.json');
+    try {
+      const AndroidApk = require('./lib/AndroidApk');
+      let material;
+      if (flags.download) {
+        const PlayStore = require('./lib/PlayStore');
+        out('fetching ' + (flags.business ? 'com.whatsapp.w4b' : 'com.whatsapp') + ' from Google Play...');
+        const apk = await PlayStore.downloadApk({
+          packageName: flags.business ? 'com.whatsapp.w4b' : 'com.whatsapp',
+          onProgress:  (m) => out('  ' + m)
+        });
+        material = AndroidApk.extractMaterial(apk.base, apk.splits);
+        // The catalogue's version is the authority when the manifest has none.
+        if (!material.apkVersion)     material.apkVersion     = apk.versionName;
+        if (!material.apkVersionCode) material.apkVersionCode = apk.versionCode;
+      } else {
+        const [basePath, ...splitPaths] = apks;
+        out('reading ' + basePath + '...');
+        material = AndroidApk.extractMaterial(
+          fs.readFileSync(basePath),
+          splitPaths.map(p => ({ name: path.basename(p), data: fs.readFileSync(p) }))
+        );
+      }
+      if (flags.version) material.apkVersion = String(flags.version);
+      if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
+      fs.writeFileSync(outFile, JSON.stringify(AndroidApk.materialToJson(material), null, 2));
+      kv('package', material.packageName);
+      kv('version', material.apkVersion
+        ? material.apkVersion + (material.apkVersionCode ? '  (code ' + material.apkVersionCode + ')' : '')
+        : '(not in the manifest — pass --version <x.y.z.w>)');
+      if (material.aboutLogoFrom) kv('about_logo', material.aboutLogoFrom);
+      kv('certificates', String(material.certificates.length));
+      const signer = AndroidApk.describeCertificate(material.certificates[0]);
+      if (signer) {
+        kv('signed by', signer.subject);
+        kv('sha256', signer.fingerprint256);
+      }
+      kv('classes.dex md5', material.classesDexMd5.toString('hex'));
+      kv('written to', outFile);
+      out('');
+      if (signer && !AndroidApk.looksLikeWhatsAppCertificate(signer)) {
+        warn('this APK is not signed by WhatsApp — the subject above is somebody else.');
+        out('  Mirrors re-sign the APKs they host, and re-signing replaces the certificate');
+        out('  the token is built from. The token will come out well-formed and belong to');
+        out('  nobody, which the server answers with bad_token. Use the APK installed on a');
+        out('  phone instead: pm path com.whatsapp');
+        out('');
+      }
+      if (material.apkVersion) {
+        out('  Registration will announce ' + material.apkVersion + ' from now on, because the');
+        out('  token is signed over this APK — the live Play Store version would name a');
+        out('  different build. WA_VERSION still overrides it.');
+      } else {
+        out('  The manifest carries no versionName, so the live Play Store version will be');
+        out('  announced. If that does not match this APK, pass --version or set WA_VERSION.');
+      }
+      out('  Re-run this when you update the APK — classes.dex changes every release.');
+    } catch (e) {
+      fail(e.message);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (cmd === 'registration' || cmd === 'reg') {
     const rawPhone =
       flags['request-code'] !== undefined && flags['request-code'] !== true ? String(flags['request-code']) :
@@ -2488,7 +2588,7 @@ async function main() {
       const methodLabel = method === 'email' ? ('email → ' + emailAddr) : method;
       out('requesting ' + methodLabel + ' code for +' + ph + '...');
       try {
-        const codeOpts = method === 'email' ? { email: emailAddr } : {};
+        const codeOpts = Object.assign(method === 'email' ? { email: emailAddr } : {}, { onProgress: out });
         const r = await requestSmsCode(store, method, codeOpts);
         store.codePending = true;
         saveStore(store, sessFile);
@@ -2514,7 +2614,7 @@ async function main() {
       const store = loadStore(file) || initAuthCreds(ph);
       out('verifying code for +' + ph + '...');
       try {
-        const r = await verifyCode(store, code, registrationPrompts());
+        const r = await verifyCode(store, code, Object.assign(registrationPrompts(), { onProgress: out }));
         if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
           if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
           const finalStore = r.store || store;