@kangwifi-pro/waliwa 1.0.0

package/docs/PROTOCOL.md

@@ -0,0 +1,489 @@
+# WhatsApp Protocol Reverse Engineering
+
+This document describes the WhatsApp protocols implemented in Waliwa, based on publicly documented reverse engineering efforts.
+
+## Table of Contents
+
+1. [WhatsApp Web Multi-Device Protocol](#whatsapp-web-multi-device-protocol)
+2. [Mobile API Pairing Protocol](#mobile-api-pairing-protocol)
+3. [Binary Protocol Format](#binary-protocol-format)
+4. [Noise Protocol Handshake](#noise-protocol-handshake)
+5. [Media Encryption](#media-encryption)
+6. [Message Types](#message-types)
+
+## WhatsApp Web Multi-Device Protocol
+
+### Connection
+
+WhatsApp Web MD connects to `wss://web.whatsapp.com/ws/chat` via WebSocket with custom headers:
+
+```
+Origin: https://web.whatsapp.com
+User-Agent: Mozilla/5.0 ...
+```
+
+WebSocket compression is disabled to reduce CPU overhead.
+
+### Frame Format
+
+Every frame follows this structure:
+
+```
+┌─────────┬──────────┬───────────┬─────────────────────┐
+│ WA (2B) │ Ver (2B) │ Len (3B)  │ Encrypted Payload    │
+└─────────┴──────────┴───────────┴─────────────────────┘
+```
+
+- **WA (2 bytes)**: Magic header `0x57 0x41` ("WA")
+- **Version (2 bytes)**: Protocol version, typically `0x05 0x2d`
+- **Length (3 bytes)**: Big-endian length of payload (max 16MB)
+- **Payload**: AES-256-GCM encrypted with traffic keys
+
+### Traffic Encryption
+
+After Noise handshake completes, two traffic keys are derived:
+- `sendKey` (32 bytes) - For encrypting outgoing frames
+- `recvKey` (32 bytes) - For decrypting incoming frames
+
+Each frame uses counter-based nonce:
+```
+Nonce (12 bytes):
+┌───────────────┬───────────────┐
+│ 4 bytes zeros │ 8 bytes counter│
+└───────────────┴───────────────┘
+```
+
+Counter increments per message (separate counters for send/recv).
+
+### Keep-Alive
+
+Every 20 seconds, client sends ping:
+```xml
+<iq type="get" id="ping-123">
+  <ping/>
+</iq>
+```
+
+Server responds with `<iq type="result" id="ping-123"/>`.
+
+## Mobile API Pairing Protocol
+
+### Pairing Code Generation
+
+Pairing code is 8 alphanumeric characters derived via HKDF:
+
+1. Inputs:
+   - Phone number (target, digits only)
+   - Pairing static key (Curve25519 private key, 32 bytes)
+
+2. Derivation:
+   ```
+   derived = HKDF-SHA256(
+     ikm = pairingKey.private,
+     salt = phoneNumber_bytes,
+     info = "pairing-code-v1",
+     length = 4 bytes
+   )
+   ```
+
+3. Encoding (4 bytes → 8 chars):
+   - Each nibble (4 bits) → 1 char from "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+   - Ambiguous characters (0/O, 1/I) excluded
+   - Format: `XXXX-XXXX` (dash separator at position 4)
+
+### Pairing Request Flow
+
+```
+Client                              Server
+  │                                    │
+  │  WebSocket + Noise handshake       │
+  │ ─────────────────────────────────→ │
+  │                                    │
+  │  Pairing request:                   │
+  │  <iq type="set" to="s.whatsapp.net">│
+  │    <pair code="AB12CD34"           │
+  │          phone="6281234567890"     │
+  │          pubkey="<base64>"         │
+  │          platform="Waliwa"/>       │
+  │  </iq>                             │
+  │ ─────────────────────────────────→ │
+  │                                    │
+  │  User inputs code in mobile app    │
+  │                                    │
+  │  Pairing result:                    │
+  │  <iq type="result">                 │
+  │    <pair jid="6281234567890@..."   │
+  │          platform="android"        │
+  │          identity="<base64>"/>     │
+  │  </iq>                             │
+  │ ←─────────────────────────────────│
+  │                                    │
+```
+
+### Pairing Code Expiry
+
+- Code expires after 65 seconds
+- Client must refresh and request new code if expired
+- Server rejects expired codes with `<error code="410">`
+
+## Binary Protocol Format
+
+WhatsApp uses a custom binary format for encoding XML-like nodes.
+
+### Node Structure
+
+```
+Node = Tag + Attributes + Content
+
+Tag: string (dictionary-encoded)
+Attributes: { key: value, ... }
+Content: string | bytes | Node[] | undefined
+```
+
+### Encoding Tags
+
+| Tag Value | Meaning              | Description                              |
+|-----------|----------------------|------------------------------------------|
+| 0x00      | EMPTY                | Empty string or no content                |
+| 0xF8      | LIST_8               | List with 8-bit count                     |
+| 0xF9      | LIST_16              | List with 16-bit count                     |
+| 0xFA      | JID_PAIR             | JID user@server format                    |
+| 0xFB      | PACKED_NIBBLE        | Numeric string (4 bits per char)          |
+| 0xFC      | BINARY_8 / PACKED_HEX| Binary 8-bit length / Hex string          |
+| 0xFD      | BINARY_20            | Binary 20-bit length                      |
+| 0xFE      | BINARY_32            | Binary 32-bit length                      |
+| 0xFF      | ADJACENT             | Adjacent node marker                      |
+
+### Dictionary Encoding
+
+Common strings are stored in 4 dictionaries (240+ entries each). Encoding:
+- Look up string in dictionary
+- If found: emit `0xFC + dict_num` byte, then index byte (1 byte total)
+- If not found: emit as raw bytes with length prefix
+
+### Packed Nibble Encoding
+
+For numeric strings (phone numbers, IDs), use nibble packing:
+- 2 characters per byte (4 bits each)
+- Append `0xF` terminator if odd length
+
+Example: `"12345"` → `[0x12, 0x34, 0x5F]`
+
+### Packed Hex Encoding
+
+For hex strings (hashes, IDs), use hex packing:
+- Same as nibble but supports `a-f` characters
+- Append `0xF` terminator if odd length
+
+### Binary Encoding
+
+For arbitrary bytes (media hashes, encrypted payloads):
+- **BINARY_8**: 1-byte length prefix (max 255 bytes)
+- **BINARY_20**: 3-byte length prefix (max 1MB)
+- **BINARY_32**: 4-byte length prefix (max 4GB)
+
+## Noise Protocol Handshake
+
+WhatsApp uses Noise Protocol Framework with **XX pattern**:
+
+### Protocol Name
+```
+Noise_XX_25519_AESGCM_SHA256
+```
+
+### Handshake Flow
+
+```
+Client                              Server
+  │                                    │
+  │  -> e                              │  (ephemeral key, 32 bytes)
+  │ ─────────────────────────────────→ │
+  │                                    │
+  │  <- e, ee, s, es                   │
+  │                                    │
+  │  (server ephemeral + encrypted     │
+  │   server static + DH computations) │
+  │ ←─────────────────────────────────│
+  │                                    │
+  │  -> s, se                          │
+  │                                    │
+  │  (client static, encrypted with    │
+  │   current handshake key)           │
+  │ ─────────────────────────────────→ │
+  │                                    │
+  │  Handshake complete                │
+  │  Traffic keys derived              │
+  │                                    │
+```
+
+### Key Derivation
+
+```
+Initial state:
+  ck = SHA256("Noise_XX_25519_AESGCM_SHA256")
+  h = SHA256("Noise_XX_25519_AESGCM_SHA256")
+
+Step 1: Client sends ephemeral
+  h = SHA256(h || client_ephemeral_pub)
+  ck, k = HKDF(ck, client_ephemeral_pub, info=empty, 64 bytes)
+  (split: ck = first 32, k = next 32)
+
+Step 2: Server sends ephemeral + encrypted static
+  h = SHA256(h || server_ephemeral_pub)
+  ck, k = HKDF(ck, server_ephemeral_pub, info=empty, 64 bytes)
+  
+  ee = X25519(client_ephemeral_priv, server_ephemeral_pub)
+  ck, k = HKDF(ck, ee, info=empty, 64 bytes)
+  
+  server_static_encrypted = AES-GCM-Encrypt(k, h, server_static_pub)
+  h = SHA256(h || server_static_pub)
+  
+  es = X25519(client_ephemeral_priv, server_static_pub)
+  ck, k = HKDF(ck, es, info=empty, 64 bytes)
+
+Step 3: Client sends encrypted static
+  client_static_encrypted = AES-GCM-Encrypt(k, h, client_static_pub)
+  h = SHA256(h || client_static_pub)
+  
+  se = X25519(client_static_priv, server_ephemeral_pub)
+  ck, k = HKDF(ck, se, info=empty, 64 bytes)
+
+Final: Traffic keys
+  prk = HKDF(ck, empty_input, "Noise_XX_..._handshake_done", 64 bytes)
+  sendKey = prk[:32]
+  recvKey = prk[32:64]
+```
+
+### AEAD Construction
+
+AES-256-GCM with:
+- Key: 32 bytes (derived from HKDF)
+- Nonce: 12 bytes (4 bytes zeros + 8 bytes counter, big-endian)
+- AAD: Current handshake hash `h`
+- Plaintext: Message payload
+- Output: Ciphertext + 16-byte tag
+
+Counter starts at 0 and increments per message (separate for send/recv).
+
+## Media Encryption
+
+### Media Key Derivation
+
+```
+mediaKey = random 32 bytes
+derived = HKDF-SHA256(
+  ikm = mediaKey,
+  salt = [mediaType_byte],
+  info = "WhatsApp ${mediaType} Keys",
+  length = 112 bytes
+)
+
+iv = derived[0:16]
+cipherKey = derived[16:48]
+macKey = derived[48:80]
+refKey = derived[80:112]
+```
+
+Media type bytes:
+- 1 = image
+- 2 = video
+- 3 = audio
+- 4 = document
+- 5 = sticker
+- etc.
+
+### Encryption Process
+
+```
+1. fileSha256 = SHA256(plaintext)
+2. ciphertext = AES-256-CBC-Encrypt(cipherKey, iv, plaintext + PKCS7_PAD)
+3. mac = HMAC-SHA256(macKey, iv + ciphertext)[0:10]
+4. encFileSha256 = SHA256(ciphertext + mac)
+5. Upload (ciphertext + mac) to CDN
+```
+
+Note: MAC is truncated to 10 bytes (not full 32) for bandwidth efficiency.
+
+### Decryption Process
+
+```
+1. Split: ciphertext = data[:-10], mac = data[-10:]
+2. expectedMac = HMAC-SHA256(macKey, iv + ciphertext)[0:10]
+3. Verify mac == expectedMac (constant-time comparison)
+4. plaintext = AES-256-CBC-Decrypt(cipherKey, iv, ciphertext)
+5. Strip PKCS7 padding
+```
+
+## Message Types
+
+### Text Message
+
+```xml
+<message to="jid" type="text" id="msgId">
+  <conversation>Text content</conversation>
+</message>
+```
+
+### Image Message
+
+```xml
+<message to="jid" type="media" id="msgId">
+  <imageMessage
+    url="https://mmg.whatsapp.net/..."
+    mimetype="image/jpeg"
+    fileSha256="<base64>"
+    fileLength="12345"
+    mediaKey="<base64>"
+    encFileSha256="<base64>">
+    <caption>Optional caption</caption>
+  </imageMessage>
+</message>
+```
+
+### Reply (Quoted) Message
+
+```xml
+<message to="jid" type="text" id="msgId">
+  <conversation>Reply text</conversation>
+  <contextInfo>
+    <stanzaId>original_msg_id</stanzaId>
+    <participant>original_sender@s.whatsapp.net</participant>
+    <quotedMessage>Original text</quotedMessage>
+    <mentionedJidList>
+      <user>mentioned_user@s.whatsapp.net</user>
+    </mentionedJidList>
+  </contextInfo>
+</message>
+```
+
+### Reaction
+
+```xml
+<message to="jid" type="reaction" id="msgId">
+  <reactionMessage
+    key='{"id":"original_id","fromMe":false,"remoteJid":"..."}'
+    text="👍"
+    timestamp="1234567890"/>
+</message>
+```
+
+### Poll
+
+```xml
+<message to="jid" type="poll" id="msgId">
+  <pollCreationMessage name="Question?" selectableOptionsCount="[1]">
+    <option index="0" name="Option 1"/>
+    <option index="1" name="Option 2"/>
+  </pollCreationMessage>
+</message>
+```
+
+## Receipts
+
+### Read Receipt
+
+```xml
+<receipt id="msgId" type="read" to="jid@s.whatsapp.net" t="1234567890">
+  <receipt id="msgId1"/>
+  <receipt id="msgId2"/>
+</receipt>
+```
+
+### Delivery Receipt
+
+```xml
+<receipt id="msgId" type="delivered" to="jid" t="1234567890"/>
+```
+
+## Presence
+
+### Subscribe to User Presence
+
+```xml
+<iq type="set" to="s.whatsapp.net" id="sub-1">
+  <user jid="target@s.whatsapp.net"/>
+</iq>
+```
+
+### Presence Update
+
+```xml
+<presence from="user@s.whatsapp.net" type="available" t="1234567890"/>
+```
+
+### Typing Indicator
+
+```xml
+<chat to="jid" type="composing"/>
+<chat to="jid" type="recording"/>
+<chat to="jid" type="paused"/>
+```
+
+## Group Operations
+
+### Create Group
+
+```xml
+<iq type="set" to="g.us" id="create-1">
+  <create subject="Group Name">
+    <participant jid="user1@s.whatsapp.net"/>
+    <participant jid="user2@s.whatsapp.net"/>
+  </create>
+</iq>
+```
+
+### Add/Remove Participants
+
+```xml
+<iq type="set" to="group@g.us" id="add-1">
+  <add>
+    <participant jid="newuser@s.whatsapp.net"/>
+  </add>
+</iq>
+```
+
+### Group Settings
+
+```xml
+<!-- Restrict (only admins can send) -->
+<iq type="set" to="group@g.us" id="restrict-1">
+  <announce type="restrict"/>
+</iq>
+
+<!-- Announce (only admins can edit info) -->
+<iq type="set" to="group@g.us" id="announce-1">
+  <info type="announce"/>
+</iq>
+```
+
+## Call Events
+
+### Incoming Call
+
+```xml
+<call
+  from="caller@s.whatsapp.net"
+  id="call-123"
+  to="me@s.whatsapp.net"
+  video="false"
+  status="ringing"/>
+```
+
+### Reject Call
+
+```xml
+<call
+  id="call-123"
+  to="caller@s.whatsapp.net"
+  action="reject"
+  type="reject"/>
+```
+
+## References
+
+- [Noise Protocol Framework Specification](https://noiseprotocol.org/)
+- [Signal Protocol Documentation](https://signal.org/docs/)
+- [HKDF (RFC 5869)](https://tools.ietf.org/html/rfc5869)
+- [WhatsApp Multi-Device Documentation](https://faq.whatsapp.com/384073008)
+
+*Note: Protocol details are based on publicly documented reverse engineering efforts. WhatsApp may change protocol without notice.*