How sigalor/whatsapp-web-reveng works
Project type and purpose
• This is a full-stack, reverse-engineering tool for WhatsApp Web. It provides:
• A browser-based client UI that mimics WhatsApp Web’s login and message display
• A Node.js API/WebSocket proxy layer that exposes an HTTP server and a WebSocket endpoint to the client
• A Python backend that speaks the real WhatsApp Web protocol (handles encryption, protobuf, binary framing) and relays messages to/from the official WhatsApp Web servers
File structure
• Top-level:
• Dockerfile, shell.nix, package.json / requirements.txt → deployment & environment setup
• index.js & index_jsdemo.js → Node.js entry points
• client/ → static assets (HTML, CSS/SCSS, JavaScript libraries, Bootstrap, SJCL encryption helpers, QR-code, JSON tree viewer)
• backend/ → Python modules:
‑ whatsapp.py (core crypto, HKDF, AES, HMAC)
‑ whatsapp_web_backend.py (WebSocket server, message queue, routing to whatsapp.py)
‑ whatsapp_binary_reader/writer.py, protobuf_pb2.py (binary framing, protobuf definitions)
‑ utilities.py (shared helpers)
• doc/ → protocol spec, protobuf definitions, app-architecture image
• windows/stdint.h → Windows build support
README for insights
• Describes a three-component architecture (shown in doc/img/app-architecture1000.png)
• Specifies ports used by each service and how they chain:
• Frontend served over HTTP on port 2018
• Node.js WebSocket API on port 2020
• Python WebSocket backend on port 2019
• Explains dependencies (Node v13+, Python 2.7 with pycrypto, curve25519-donna, protobuf, simple-websocket-server)
Main components
a. Frontend (Browser)
• Static HTML/CSS/JS served by Node.js
• WebSocketClient.js handles WS to Node
• UI libraries: BootstrapStep, UpdaterPromise, JSONTree, curve25519-js, sjcl, qrcode
b. Node.js API & Proxy Layer
• index.js starts:
• HTTP server (serves /client) on port 2018
• WebSocket server for the browser on port 2020
• Listens for browser requests, forwards calls over its WebSocket to Python backend, and relays responses back
c. Python WebSocket Backend
• whatsapp-web-backend.py starts a local WS server on port 2019
• Manages an active WebSocketClient to wss://w[1-8].web.whatsapp.com/ws (official WhatsApp servers)
• Contains whatsapp.py for:
• Key exchange (Curve25519, HKDF)
• AES-CBC encryption/decryption of binary messages
• HMAC validation
• Protobuf encode/decode (whatsapp_protobuf_pb2.py)
• Reads/writes binary/JSON, transforms WhatsApp frames into JSON messages for Node
d. External Services
• Official WhatsApp Web servers (wss://w[1-8].web.whatsapp.com/ws)
Relationships and data flow
• Browser → HTTP GET → Node.js (static files)
• Browser → WebSocket → Node.js (port 2020)
• Node.js → WebSocket → Python backend (port 2019)
• Python backend ↔ WebSocket → Official WhatsApp servers (wss://…)
• Responses flow back along the chain in reverse order
Architectural patterns & design principles
• Clear separation of concerns (UI vs. API proxy vs. protocol handler)
• Event-driven, message-oriented microservices (WS chain)
• Decoupled protocol handling in Python, UI logic in JS
• Environment reproducibility via Nix and Docker
Technologies & frameworks
• Frontend: vanilla JS, Bootstrap, sjcl (crypto), curve25519-js, qrcode, JSONTree
• Mid-tier: Node.js, simple-websocket-server, nodemon, concurrently, Express (serving static)
• Backend: Python 2.7, websocket-client, curve25519-donna, pycrypto, pyqrcode, protobuf
• Deployment: Docker, shell.nix, direnv