whalibmob 5.32.0 → 5.32.1

package/README.md

@@ -27,6 +27,8 @@ code, and bring the account into being. Both transports, one API.
 [![Send messages](https://img.shields.io/badge/Send_messages-text_media_polls-34B7F1?style=for-the-badge)](#sending-messages)
 [![Handle events](https://img.shields.io/badge/Handle_events-incoming_%26_receipts-34B7F1?style=for-the-badge)](#handling-events)
 
+[![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)
+
 </div>
 
 ##
@@ -61,6 +63,71 @@ If you want to talk with me contact me on Telegram my username îs @brtyu545
 - **The API is identical in both modes.** Everything below — sending, media, groups, events — reads the same whichever way the session was created.
 - No browser, no Selenium, no external runtime. It talks to WhatsApp directly over a **TCP socket** with the **Noise Protocol** handshake.
 - Signal Protocol encryption is **fully inlined** in pure JavaScript — no native binaries, no node-gyp, runs anywhere Node.js runs.
+- **It can prove it is a real handset.** The on-device Frida scripts in [`frida/`](https://github.com/Kunboruto20/whalibmob/tree/main/frida) mint the hardware attestation WhatsApp's registration server expects — Play Integrity and Keystore on Android, App Attest on iOS — and whalibmob folds the result into the registration requests. See [Device Attestation](#device-attestation--play-integrity-and-app-attest).
+
+## Device Attestation — Play Integrity and App Attest
+
+This is the part most projects stop at, so it is worth saying up front what is
+here and what it does.
+
+When the real WhatsApp app registers a number, it does not just send the number
+and the code. It also proves to the server that it is running on a genuine
+handset, by minting a hardware-backed attestation token — **Play Integrity plus
+a Keystore certificate chain** on Android, **DeviceCheck App Attest** on iOS.
+Those tokens cannot be forged off-device: they are signed by a key that lives in
+the phone's secure hardware.
+
+whalibmob ships the on-device scripts that obtain them. They run under
+[Frida](https://frida.re) on a **rooted Android phone** or a **jailbroken
+iPhone**, start a small HTTP server on the device, and whalibmob calls it while
+registering:
+
+| Platform | Endpoint | What it feeds into the registration request |
+|----------|-------------|----------------------------------------------|
+| Android | `/info` | APK hashes, signature and secret key — the device fingerprint |
+| Android | `/integrity` | `gpia` and its `_gg _gi _gp _ge _ga` companions — the Play Integrity verdict |
+| Android | `/cert` | the `&H=` body signature and the `Authorization` certificate chain |
+| iOS | `/integrity` | the App Attest assertion and its `Authorization` header |
+
+```sh
+# on your computer — build the bundle
+cd frida/android                                  # or: cd frida/ios
+npm install && npm run build                      # → server_with_dependencies.js
+
+# attach it to WhatsApp on the device, with the Frida server running there
+frida -U "WhatsApp" -l server_with_dependencies.js
+
+# on the machine running whalibmob — it listens on 1119 (WhatsApp) / 1120 (Business)
+export WA_FRIDA_HOST=192.168.1.50
+wa registration --request-code 919634847671
+```
+
+The code, and the per-platform setup:
+
+- **[`frida/android/server.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/android/server.js)** — Play Integrity + Keystore attestation · [setup](https://github.com/Kunboruto20/whalibmob/blob/main/frida/android/README.md)
+- **[`frida/ios/server.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/server.js)** — DeviceCheck App Attest · [setup](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/README.md)
+- **[`frida/ios/registration/registration.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/registration/registration.js)** — prints the registration public key
+- **[`frida/ios/exchange/index.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/exchange/index.js)** — hooks `mbedtls_gcm_update` to read the payload
+- **[`lib/Attestation.js`](https://github.com/Kunboruto20/whalibmob/blob/main/lib/Attestation.js)** — the client that talks to the device
+
+> [!NOTE]
+> **None of this is required.** Leave `WA_FRIDA_HOST` unset and whalibmob sends
+> the same empty low-trust attestation fields the native client sends when its
+> own integrity minting fails — which the server tolerates. Registration works
+> without a rooted phone anywhere in sight. Attaching a device raises the trust
+> score, which is what helps when a number keeps hitting `no_routes` or a block
+> screen.
+
+> [!IMPORTANT]
+> **The Frida scripts themselves are reference material, not a maintained
+> feature.** They are published so that anyone with a rooted or jailbroken
+> device can reproduce what the native app does, and so that the method is on
+> the record. They also need the official app installed **from the Play Store /
+> App Store** — a sideloaded APK will not attest, because the token is bound to
+> the store-signed build. `lib/Attestation.js`, the client side inside
+> whalibmob, is maintained as part of the library.
+
+Full walkthrough, with the device prerequisites: [Device Attestation with Frida](#device-attestation-with-frida-optional).
 
 ## Install
 
@@ -76,6 +143,7 @@ npm install -g whalibmob
 
 ## Index
 
+- [Device Attestation — Play Integrity and App Attest](#device-attestation--play-integrity-and-app-attest)
 - [CLI — Getting Started](#cli--getting-started)
   - [Install the CLI](#install-the-cli)
   - [First-Time Setup: Register a Number](#first-time-setup-register-a-number)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.32.0",
+  "version": "5.32.1",
   "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",