whalibmob 2.0.0

package/README.md

@@ -0,0 +1,379 @@
+# whalibmob
+
+A pure JavaScript Node.js library and CLI for WhatsApp. Operates as a
+mobile iOS client with full Signal Protocol end-to-end encryption, SenderKey
+group messaging, multi-device fanout, persistent sessions, and automatic
+reconnection.
+
+---
+
+> **⚠️ IMPORTANT — You need a brand-new phone number and a brand-new SIM card
+> dedicated to WhatsApp for this library to work for you.** Using an existing
+> WhatsApp account that is already active on a real phone will cause
+> WhatsApp to ban or revoke the session. Register a fresh number that has
+> never been used with WhatsApp before.
+
+---
+
+## Features
+
+- **Mobile iOS fingerprint** — authentic iOS device headers; behaves like
+  WhatsApp on an iPhone
+- **Signal Protocol E2E encryption** — X3DH session setup, Double Ratchet
+  for 1-to-1 messages
+- **SenderKey group encryption** — efficient group messaging with chain-key
+  advance and SKDM distribution
+- **Multi-device fanout** — messages delivered to all linked devices of each
+  recipient via usync device query
+- **All media types** — images, video, audio, voice notes (PTT), documents,
+  stickers; AES-256-CBC + HKDF-SHA256 encryption, uploaded to WhatsApp CDN
+- **Text, reactions, extended text** — full message type coverage
+- **Participant hash (phash)** — SHA-256 participant-list validation sent
+  with every multi-device and group message
+- **deviceSentMessage** — own linked devices (tablet, secondary phone) receive
+  a proper copy-sent wrapper so they show the message as sent
+- **senderKeyMap** — SKDM is sent to each device only once; subsequent group
+  messages skip SKDM entirely for devices that already have the key
+- **Automatic reconnection** — exponential backoff (1 s → 2 → 4 → 8 → 15 → 30 s)
+- **Pre-key replenishment** — automatic upload when supply drops below 20
+- **Persistent sessions** — JSON files on disk; no re-registration after restart
+- **Auth confirmation** — waits for server `<success>` before declaring the
+  connection open; handles `<failure>` (session revoked / account banned)
+- **Professional `wa` CLI** — yowsup-style interface for registration, sending,
+  listening, and interactive chat
+
+---
+
+## Installation
+
+```bash
+cd tools/whalibmob
+npm install
+npm link          # makes `wa` available globally
+```
+
+Requires **Node.js 18** or higher.
+
+---
+
+## CLI Usage
+
+### Check if a number is registered
+
+```bash
+wa registration --check 919634847671
+```
+
+### Request a verification code
+
+```bash
+# via SMS (default)
+wa registration --request-code 919634847671
+
+# via voice call
+wa registration --request-code 919634847671 --method voice
+
+# via backup WhatsApp account (wa_old)
+wa registration --request-code 919634847671 --method wa_old
+```
+
+### Register with the received code
+
+```bash
+wa registration --register 919634847671 --code 123456
+```
+
+### Connect and enter an interactive shell
+
+```bash
+wa connect 919634847671
+```
+
+Interactive commands at the `wa>` prompt:
+
+```
+/send <jid> <text>     Send a text message
+/presence              Set presence to available
+/presence away         Set presence to unavailable
+/quit                  Disconnect and exit
+```
+
+### Send messages
+
+```bash
+# Text
+wa send 919634847671 --to 911234567890@s.whatsapp.net --text "Hello!"
+
+# Image with caption
+wa send 919634847671 --to 911234567890@s.whatsapp.net --image ./photo.jpg --caption "Look at this"
+
+# Video
+wa send 919634847671 --to 911234567890@s.whatsapp.net --video ./clip.mp4
+
+# Voice note (PTT)
+wa send 919634847671 --to 911234567890@s.whatsapp.net --ptt ./voice.ogg
+
+# Audio file
+wa send 919634847671 --to 911234567890@s.whatsapp.net --audio ./song.mp3
+
+# Document
+wa send 919634847671 --to 911234567890@s.whatsapp.net --document ./report.pdf
+
+# Sticker
+wa send 919634847671 --to 911234567890@s.whatsapp.net --sticker ./sticker.webp
+
+# Emoji reaction
+wa send 919634847671 --to 911234567890@s.whatsapp.net --reaction 👍 --msg-id 3EB0ABCDEF123456
+
+# Group message
+wa send 919634847671 --to 120363000000000000@g.us --text "Hi everyone!"
+```
+
+### Listen for incoming messages
+
+```bash
+wa listen 919634847671
+```
+
+### Print version
+
+```bash
+wa version
+```
+
+### Full options reference
+
+| Flag | Description |
+|---|---|
+| `--session <dir>` | Session directory (default: `~/.waSession`) |
+| `--method sms\|voice\|wa_old` | Verification code delivery method |
+| `--code <code>` | Verification code |
+| `--to <jid>` | Recipient JID (`phone@s.whatsapp.net` or `groupid@g.us`) |
+| `--text <msg>` | Text message body |
+| `--caption <text>` | Caption for media messages |
+| `--reaction <emoji>` | Emoji to send as a reaction |
+| `--msg-id <id>` | Message ID to react to (required with `--reaction`) |
+
+---
+
+## Library Usage
+
+### Connect and send messages
+
+```javascript
+const { WhalibmobClient } = require('whalibmob');
+
+const client = new WhalibmobClient({ sessionDir: '/path/to/sessions' });
+
+client.on('connected', async () => {
+  // Text
+  await client.sendText('919876543210@s.whatsapp.net', 'Hello!');
+
+  // Image
+  await client.sendImage('919876543210@s.whatsapp.net', '/path/to/photo.jpg', {
+    caption: 'My photo'
+  });
+
+  // Image from Buffer
+  const buf = require('fs').readFileSync('/path/to/photo.jpg');
+  await client.sendImage('919876543210@s.whatsapp.net', buf, { caption: 'From buffer' });
+
+  // Voice note
+  await client.sendAudio('919876543210@s.whatsapp.net', '/path/to/voice.ogg', {
+    ptt: true,
+    seconds: 12
+  });
+
+  // Document
+  await client.sendDocument('919876543210@s.whatsapp.net', '/path/to/file.pdf', {
+    fileName: 'report.pdf',
+    mimetype: 'application/pdf'
+  });
+
+  // Reaction
+  await client.sendReaction('919876543210@s.whatsapp.net', '3EB0ABC123', '👍');
+
+  // Group message
+  await client.sendText('120363000000000000@g.us', 'Hi group!');
+});
+
+client.on('message', (msg) => {
+  console.log('From:', msg.from, '|', msg.text);
+});
+
+client.on('auth_failure', ({ reason }) => {
+  console.error('Session revoked by WhatsApp:', reason);
+  // reason values: '401', '403', 'not_authorized', 'device_removed', etc.
+});
+
+client.on('close', () => console.log('Disconnected'));
+client.on('error', (err) => console.error(err));
+
+await client.init('919634847671');
+```
+
+### Registration (programmatic)
+
+```javascript
+const {
+  createNewStore,
+  saveStore,
+  loadStore,
+  checkIfRegistered,
+  requestSmsCode,
+  verifyCode
+} = require('whalibmob');
+
+const storePath = '/path/to/sessions/919634847671.json';
+
+// Create or load a session store
+let store = loadStore(storePath) || createNewStore('919634847671');
+
+// Check if already registered
+const status = await checkIfRegistered(store);
+console.log(status.status);  // "ok" if registered
+
+// Request verification code — methods: "sms", "voice", "wa_old"
+const res = await requestSmsCode(store, 'sms');
+console.log(res.status);     // "sent" on success
+
+// Verify the received code and save session
+const reg = await verifyCode(store, '123456');
+if (reg.status === 'ok') {
+  saveStore(store, storePath);
+  console.log('Registered!');
+}
+```
+
+---
+
+## Events
+
+| Event | Payload | Description |
+|---|---|---|
+| `connected` | — | Server confirmed `<success>`, session is live |
+| `close` | — | Connection closed |
+| `disconnected` | — | TCP connection dropped (reconnect scheduled) |
+| `reconnecting` | `{ delay, attempt }` | About to reconnect after backoff delay |
+| `reconnected` | — | Reconnection succeeded |
+| `auth_failure` | `{ reason, node }` | Server sent `<failure>` — session revoked or account banned |
+| `error` | `Error` | Non-fatal error occurred |
+| `message` | `{ id, from, participant, ts, text?, plaintext?, isGroup? }` | Incoming message (plaintext is a Buffer) |
+| `receipt` | `{ id, from, type }` | Delivery or read receipt |
+| `presence` | `{ from, available }` | Contact came online / went offline |
+| `call` | `{ from, node }` | Incoming call (auto-rejected by the library) |
+| `notification` | `{ type, attrs, node }` | Raw server notification |
+| `decrypt_error` | `{ id, from, err }` | Decryption failed; retry request sent automatically |
+| `media_conn` | `{ hosts, auth }` | Media upload server connection ready |
+| `session_refresh` | `{ node }` | Server sent a late `<success>` (re-auth flow) |
+| `stream_error` | `{ reason }` | Server-side stream error |
+
+---
+
+## Session Files
+
+Sessions are stored as JSON in the session directory (default `~/.waSession`):
+
+```
+~/.waSession/919634847671.json         # WhatsApp credentials and keys
+~/.waSession/919634847671.signal.json  # Signal Protocol session state
+~/.waSession/919634847671.sk.json      # SenderKey group state + SKDM map
+```
+
+Once registered, sessions persist across restarts. Re-registration is only
+required if WhatsApp revokes the session (you will receive an `auth_failure`
+event with reason `401` or `not_authorized`).
+
+---
+
+## Signal Protocol
+
+End-to-end encryption follows the Signal Protocol spec:
+
+1. On first connection, pre-keys are generated and uploaded to WhatsApp.
+2. When contacting a new recipient, the library fetches their pre-key bundle
+   and runs X3DH to establish a session.
+3. All subsequent messages use the Double Ratchet algorithm.
+4. Pre-keys are automatically replenished when supply drops below 20.
+5. Session state is persisted to disk between restarts.
+
+---
+
+## Group Messaging (SenderKey)
+
+Group messages use the SenderKey protocol for efficient delivery:
+
+1. Each sender generates a SenderKey (signing key pair + chain key).
+2. On first group message, a SenderKey Distribution Message (SKDM) is
+   encrypted individually for every device of every group member and sent.
+3. Subsequent messages are encrypted once with the SenderKey and broadcast
+   — no per-member re-encryption needed.
+4. The library tracks which devices have already received the SKDM (persisted
+   in `.sk.json`) and skips them on subsequent messages.
+5. The chain key advances with each message (HMAC-SHA256).
+6. Out-of-order message decryption is supported via cached message keys.
+
+---
+
+## Multi-Device
+
+The library fully supports WhatsApp's multi-device architecture:
+
+- Device lists are fetched via usync queries.
+- Signal sessions are established for each linked device.
+- All outgoing DMs are fanned out to every device of every recipient as well
+  as the sender's own linked devices (tablet, secondary phone, etc.).
+- Own linked devices receive a `deviceSentMessage` wrapper so they display
+  the message as sent (not received).
+- All multi-device stanzas include a `phash` (SHA-256 participant hash) so
+  the server can validate the participant list.
+- SKDM distribution in groups covers all member devices.
+
+---
+
+## Noise Handshake & Auth
+
+The transport uses **Noise_XX_25519_AESGCM_SHA256**:
+
+1. TCP connection to `g.whatsapp.net:443`.
+2. Client sends `ClientHello` with ephemeral X25519 public key.
+3. Server replies with `ServerHello` (ephemeral + encrypted static + payload).
+4. Three Diffie-Hellman steps (EE, SE, SS) derive the session keys.
+5. Client sends `ClientFinish` (encrypted static + encrypted payload).
+6. **Library waits for the server's `<success>` or `<failure>` node.**
+7. Only after `<success>` is the channel opened and the `connected` event
+   emitted. A `<failure>` rejects with an `auth_failure` event.
+
+---
+
+## Automatic Reconnection
+
+The client reconnects on disconnect with exponential backoff:
+
+| Attempt | Delay |
+|---|---|
+| 1 | 1 s |
+| 2 | 2 s |
+| 3 | 4 s |
+| 4 | 8 s |
+| 5 | 15 s |
+| 6+ | 30 s |
+
+---
+
+## Media Encryption
+
+Media files use WhatsApp's standard encryption scheme:
+
+1. A random 32-byte media key is generated.
+2. HKDF-SHA256 expands it to produce the IV, cipher key, and MAC key.
+3. The file is encrypted with AES-256-CBC.
+4. A 10-byte HMAC-SHA256 MAC is appended.
+5. The encrypted ciphertext is uploaded to WhatsApp's CDN.
+6. The media key and URL are sent in the message envelope.
+
+---
+
+## License
+
+MIT