AwesomeREA.org

Case study

whatsapp-web-reveng: documenting the legacy WhatsApp Web protocol

Documents and reimplements the WebSocket protocol WhatsApp Web used while browser sessions mirrored a paired phone: QR pairing, Curve25519/HKDF key setup, AES/HMAC-protected binary messages, the token-based node encoding and end-to-end media encryption. A Python backend, Node.js relay and browser front end decode a logged-in session’s messages into inspectable JSON, and the README lists independent reimplementations such as Baileys and go-whatsapp. This is an older protocol generation from before WhatsApp’s 2021 multi-device architecture, not a description of current WhatsApp Web.

Requirements and limitations

  • Reviewed at the 2024-04-22 master head, a README-only change; the backend and Node relay last changed in August 2021, the protobuf schema in March 2020, and there are no releases or tags. The README’s pairing flow has the phone supply session details such as its battery level, the phone-mirroring companion model that WhatsApp’s July 2021 engineering post says multi-device replaces. A 2022 issue reports the server answering a QR scan with an upgrade_md_prod command; whether the flow still connects was not tested.
  • Use needs the user’s own WhatsApp account and phone to scan the pairing code, and the backend connects to WhatsApp’s servers. The protobuf definitions come from a helper script that parses the public WhatsApp Web JavaScript bundle. The README’s task list still names growing binary-decoding errors, writing binary messages and a less technical interface as open work.
  • Bare-metal setup needs Node.js 8+ and Python 2.7 with websocket-client, simple-websocket-server, curve25519-donna, pycrypto (pycryptodome in requirements.txt), pyqrcode and protobuf; Windows also needs Visual C++ for Python 9.0 and a supplied header. A shell.nix (Python 2.7, Node.js 13) and a Dockerfile are provided, and npm start runs the backend, Node API and front end together. The README says the Docker version is not stable enough for production.
  • There is no test suite: the package.json test script only starts the components. The documented correctness checks are HMAC validation of the server’s key data and of each binary message, and an in-browser JavaScript demo prints decrypted messages after a QR scan. This source review opened no session and decoded no traffic.
  • MIT (LICENSE, package.json). The README states the project is unaffiliated with and not endorsed by WhatsApp, that use is at the user’s own risk, and adds a cryptography export notice; WhatsApp’s services and terms apply separately. The reviewed sources establish no AI or REA use.

About this entry

Type
Case study
Category
Independent reconstruction cases
Relationship
Independent reconstruction project
Targets
Protocol · Website

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Primary sources

  1. README.md GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  2. backend/whatsapp.py GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  3. backend/whatsapp_binary_reader.py GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  4. doc/spec/def.proto GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  5. doc/spec/protobuf-extractor/index.js GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  6. package.json GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  7. requirements.txt GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  8. shell.nix GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  9. Dockerfile GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  10. LICENSE GitHub · sigalor/whatsapp-web-reveng · Revision 04caed2
  11. https://github.com/sigalor/whatsapp-web-reveng/issues/372
  12. https://engineering.fb.com/2021/07/14/security/whatsapp-multi-device/