karl/ghostwire
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify documentation and add repository development skill

Browse Source
This commit is contained in:
Ops Agent committed 2026-10-11 09:03:49 +02:00
1 parent 3d8cf46a63
commit 5aaa31dc1a
10 files changed
+473 -239
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+69 -54
View File
@@ -1,82 +1,97 @@
# WhatsApp Desktop Suite
A Windows toolkit for reading, searching and exporting local WhatsApp Desktop data, with a portable single-file Python distribution and an editable source package.
Read, search and export local WhatsApp Desktop messages and contacts. Install a message listener that delivers events to an HTTPS webhook.
The core live commands execute JavaScript inside the signed-in Desktop WebView through a bundled native bridge. They require neither CDP nor UI automation. Separate optional research commands use CDP, Frida or process-memory inspection.
The main commands run JavaScript inside the signed-in Windows Desktop app through a bundled native bridge. They use neither CDP nor UI automation. This is an independent, reverse-engineered toolkit; it is not an official WhatsApp API.
## Features
## Start here
| Feature | Command | Scope |
| --- | --- | --- |
| Contact export | `contacts-export` | Local contact rows, including distinct PN/LID records |
| Message ZIP export | `export-zip` | Local message rows, decoded text/captions and manifest; no media downloads |
| Old message reading | `live --suite history-read` | Five oldest local records, including records outside loaded chats |
| Desktop search | `desktop-search` | Bounded app search through the native bridge |
| Saved export search | `search` | Unicode-aware literal search, filtering and optional redaction |
| Message webhooks | `webhook` | In-process listener, direct HTTPS or loopback delivery, optional automatic restoration |
| Self-message test | `send-self` | One fixed message to the signed-in account, with stored-text verification |
| Inspection and diagnostics | `inventory`, `stats`, `live` | Storage inventory, export summaries and fixed probes |
| Optional research tools | See [CLI reference](docs/CLI.md) | CDP history export, RAM tools, SQLite probes and pairing tools |
## Quick start
Copy `whatsapp.py` into a writable folder. Run with Python 3.11 or newer:
**For users:** copy [whatsapp.py](whatsapp.py) into a writable folder. You need Python 3.11 or newer; live Desktop commands require Windows x64, 64-bit Python, and WhatsApp running and signed in. You do not need a C++ compiler or separate DLL files.
```powershell
python whatsapp.py --help
python whatsapp.py test
python whatsapp.py contacts-export --output contacts.json
python whatsapp.py export-zip --output messages.zip
python whatsapp.py live --suite history-read
```
Live bridge commands require **Windows x64 and 64-bit Python**. They were tested with WhatsApp Desktop **2.2639.100.0** and the recorded WebView component. Other versions are attempted with a compatibility warning rather than blocked. The helper discovers function/vtable locations from binary fingerprints rather than fixed module RVAs. It retains compiler/object-layout and ABI assumptions, so other versions remain unverified and incompatible patterns fail discovery. The core commands need only Python's standard library. Optional tools have [additional dependencies](docs/CLI.md#optional-dependencies); Node.js enables the JavaScript fixture tests.
The default tests use synthetic data and do not send messages or install listeners. Node.js enables the JavaScript fixture checks; without it, inspect the reported skips.
`send-self` actually sends a message. It is never part of the default tests and does not retry automatically. ZIP exports cover the local database, not necessarily every message ever received. Contacts are local table rows, not a deduplicated phone address book.
Choose the command for your task:
## Message listener with automatic restoration
| I want to… | Command |
| --- | --- |
| Export contacts | `python whatsapp.py contacts-export --output exports/contacts.json` |
| Export local messages as a ZIP | `python whatsapp.py export-zip --output exports/messages.zip` |
| Read the five oldest local records | `python whatsapp.py live --suite history-read` |
| Search the running app | `python whatsapp.py desktop-search "keyword" --limit 10` |
| Search an extracted message export | `python whatsapp.py search messages.jsonl "keyword"` |
| Test sending to my own account | `python whatsapp.py send-self` |
| Deliver message events to a webhook | See the example below |
Supply your endpoint token through `WHATSAPP_INJECTOR_WEBHOOK_TOKEN` using your secret manager, then run:
Exports and reports contain private data. Existing export files are refused: choose a new output name. A message ZIP contains decoded text records and a manifest, not downloaded media or guaranteed complete account history. Contact rows may contain separate PN/LID identities.
## Receive message events
Provide your endpoint token through the environment variable `WHATSAPP_INJECTOR_WEBHOOK_TOKEN`, preferably using your secret manager. Your endpoint must validate the `X-Webhook-Token` header.
```powershell
python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --auto-restore --config listener.json
python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --self-only --auto-restore --config listener.json
python whatsapp.py webhook status
```
`--endpoint` selects the HTTPS target; `--auto-restore` creates a per-user Windows task that checks every minute and restores the listener after WhatsApp restarts. Delivery runs inside WhatsApp, without CDP, UI automation, a local HTTP server or a continuously running Python process. Add `--self-only` for self-chat testing. The endpoint must authenticate the token header and accept message batches. See [setup, payload, limitations and full removal](docs/WEBHOOKS.md).
- `--endpoint` selects the HTTPS target.
- `--self-only` limits delivery to your self-chat for testing. Omit it to subscribe to qualifying events from other chats.
- `--auto-restore` registers a per-user Windows task that restores the listener after WhatsApp restarts.
- `--config` saves the listener settings and, for automatic restoration, a Windows-protected token.
## Development
The installer exits. Delivery runs inside WhatsApp; no local HTTP server or continuous Python process is needed. The task performs a brief check every minute while your Windows user is logged in. Process memory does not survive restart: the task reinstalls the listener, with a polling gap.
`send-self` sends a real test message and verifies its stored plaintext. It never retries an uncertain send automatically. No AI summarizer or automatic replies are included.
See [webhook setup, payload and removal](docs/WEBHOOKS.md) before integration.
## How it works
```mermaid
flowchart LR
P["Python CLI"] --> B["Bundled native bridge"]
B --> W["WhatsApp WebView JavaScript"]
W --> D["App database getters and decoder"]
D --> E["JSON / ZIP exports"]
W --> L["Message event queue"]
L --> H["Native HTTPS relay"]
H --> T["Your webhook endpoint"]
```
Python orchestrates documented Windows APIs through `ctypes`. A temporary Windows hook loads a native helper into WhatsApp; the helper locates the existing WebView and calls its script-execution interface. The portable file bundles the C++ DLLs; Python does not replace them with a pure-Python implementation. Read [the architecture](docs/ARCHITECTURE.md) for lifetimes and compatibility boundaries.
## Compatibility and verification
Tested with WhatsApp Desktop **2.2639.100.0** on Windows x64. Other versions are attempted with a warning. Native addresses are discovered from binary fingerprints, but compiler layout and interface assumptions remain; support for other builds is unverified.
The verified bundle passed **41 offline tests**. Live checks covered contact export, old-message reading, search, message ZIP export, self-send, direct HTTPS delivery and task restoration after a WhatsApp restart. See [validation evidence and untested cases](docs/VALIDATION.md).
Optional CDP, Frida, RAM and QR research commands have separate dependencies and behavior. They are listed separately in the [CLI reference](docs/CLI.md).
## Develop and extend
```powershell
python -m whatsapp_suite --help
python -m whatsapp_suite test
python build_whatsapp_bundle.py
python whatsapp.py test
```
The builder embeds the maintained modules, DLLs and fixtures. Modules load from memory; a verified DLL is extracted only when needed. The distribution is approximately 207 KiB. Keep source and bundle changes together.
Edit `whatsapp_suite/`; `whatsapp.py` is generated. The portable file is about 207 KiB and embeds the maintained modules, runtime assets and tests.
## Project layout
| Resource | Use it for |
| --- | --- |
| [CLI reference](docs/CLI.md) | Commands, options and output behavior |
| [Webhook guide](docs/WEBHOOKS.md) | Setup, event schema, restart behavior and removal |
| [Architecture](docs/ARCHITECTURE.md) | Understand the bridge and choose the right extension point |
| [Contributing](CONTRIBUTING.md) | Add a command, change JavaScript, rebuild native helpers |
| [Agent skill](skills/whatsapp-suite-development/SKILL.md) | Repository-specific guidance for coding agents |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Resolve common setup and runtime problems |
| [Validation](docs/VALIDATION.md) | Distinguish tested behavior from assumptions |
| [Security](SECURITY.md) | Handle private data and credentials |
| [Publishing](docs/PUBLISHING.md) | Review and upload the clean repository |
```text
whatsapp.py Portable generated distribution
whatsapp_suite/ Canonical Python implementations
whatsapp_suite/assets/ Runtime DLLs and SQLite agent
native/ Native helper C++ source
tests/ Synthetic Python and JavaScript fixtures
build_whatsapp_bundle.py Deterministic bundle builder
docs/ Architecture, validation and publishing guide
```
## Documentation
- [CLI and export behavior](docs/CLI.md)
- [Message webhooks and restart behavior](docs/WEBHOOKS.md)
- [Architecture and native bridge](docs/ARCHITECTURE.md)
- [Validation and limitations](docs/VALIDATION.md)
- [Development and contributions](CONTRIBUTING.md)
- [Publishing to tea.karlcom.de](docs/PUBLISHING.md)
- [Handling private data](SECURITY.md)
## Project status
Repository: [karl/whatsapp_injector](https://tea.karlcom.de/karl/whatsapp_injector). It is independent of WhatsApp/Meta. No open-source license has been selected; see [licensing status](LICENSE.md).
Repository: [karl/whatsapp_injector](https://tea.karlcom.de/karl/whatsapp_injector). No open-source license has been selected; see [licensing status](LICENSE.md).