wa-go

module

v0.1.0 Latest Latest Go to latest Published: Jun 26, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jfelipesjc/wa-go

Links

Open Source Insights

README ¶

wa-go

Reimplementação do protocolo WhatsApp Web (estilo Baileys) em Go, do zero — sem whatsmeow. Objetivo: controle total (fingerprint de device, cadência humana de envio, multi-conta leve, acesso a frames brutos) e, no fim, aposentar o Evolution API.

Decomposto em 9 sub-projetos. Specs e planos em docs/superpowers/.

Status

#	Sub-projeto	Status
0	Capture harness (golden traces da Baileys real)	✅ feito
1	Wire layer (framing + Noise XX + binary-node codec)	✅ feito
2	Pairing/Auth (multi-device, QR + código, storage)	✅ feito — QR + pairing-code provados LIVE
3	Signal/E2E (X3DH, Double Ratchet) — cripto 1:1 do zero	✅ cripto provada (golden vectors byte-a-byte + 7 msgs reais decifradas live)
4	Messaging 1:1 (receber+enviar)	✅ bidirecional provado LIVE — texto + mídia + reação (ADM↔wa-go via Evolution)
4+	Grupos (sender keys), mídia (cripto+transfer), todos os tipos de msg	✅ mídia provada LIVE; grupos feitos offline (live pendente)
5	App-state sync (LTHash) — decode+encode+resync	✅ feito (offline)
6	Control layer (fingerprint, SendPacer, hooks de frame)	✅ feito (offline; default reproduz fixture)
7	Instance manager (multi-sessão)	✅ feito (offline; -race 50 instâncias)
8	Evolution-compat (HTTP/WS)	✅ projeto separado `wa-evolution` (importa esta lib via fachada `wa/`)

Esta é a biblioteca (a "Baileys"). O serviço estilo Evolution está em ../wa-evolution, que importa github.com/felipeleal/wa-go/wa (fachada pública, estilo index.ts).

Pareamento: QR e pairing-code (código de 8 chars) ambos PROVADOS LIVE (2026-06-23/24): o fluxo completo companion_hello → primary_hello → companion_finish → pair-success → login foi validado de ponta a ponta no WhatsApp real (w4b). cmd/wa-paircode pareia sozinho.

Cobertura de features (offline, 418 testes, suite -race verde)

Mensagens: texto, reply, menção, imagem/vídeo/áudio/documento/sticker (cripto + upload/download HTTP), localização, contato, reação, editar, apagar, enquete; recebimento parseia todos os tipos (eventos ricos). Grupos: sender keys (E2E), enviar/receber, metadata, criar, add/remover/promover/rebaixar, assunto/descrição, sair, convite, settings, comunidades/sub-grupos. App-state: LTHash decode+encode, arquivar/fixar/mutar/marcar lido/favoritar/limpar/apagar chat, resync. Perfil/privacidade: nome/status/foto, fetch status/foto, privacy settings, bloquear/desbloquear, blocklist. Outros: presença/digitando/recibo de leitura/subscribe, chamadas (parse+reject+evento), status/stories, business (perfil/catálogo/pedido), onWhatsApp, newsletters (criar/seguir/mute/metadata), history sync (download+decode). Infra: multi-sessão (instance manager), fingerprint por instância, cadência humana (pacer), hooks de frame bruto.

✅ Provado LIVE (2026-06-23/24): pareamento (QR + código), receber, enviar texto + imagem (mídia) + reação — todos validados ponta a ponta contra o WhatsApp real (wa-go ↔ ADM via Evolution). Inclui os fixes de estabilidade (re-upload de pre-keys / unlink 401) e de history-sync (pkmsg com prekey consumido). ⚠️ Ainda só offline (golden vectors + round-trips), live pendente: grupos (sender keys), app-state resync, status/stories, newsletters, perfil/privacidade. Lição operacional: NÃO re-parear/remover a mesma conta em loop — queima o device-management e o servidor para de relayar os envios.

#0 + #1 entregues

Harness (harness/): instrumenta a Baileys real, captura connect_pair (handshake Noise + ephemeral + nodes) e gera bateria sintética de 19 nodes cobrindo todos os caminhos do codec. Traces em testdata/traces/.
Wire (internal/wire/): framing 3-byte BE, dicionário de tokens (236 single + 1024 double), codec DecodeNode/EncodeNode (round-trip 19/19 estrutural), handshake Noise_XX_25519_AESGCM_SHA256, e Conn (SendNode/ReadNode).
Validação decisiva: o handshake roda contra o trace real e decifra o frame pair-device (698 B) do WhatsApp até decodificar o node idêntico ao capturado. go test ./... = 26/26 verde.

Rodar

export PATH=$PATH:/usr/local/go/bin
go test ./...            # suíte offline (unit + #1 + #2)
go run ./cmd/wiredump    # replay do trace, decodifica o pair-device (sem rede)

Pareamento (#2)

# Teste ao vivo (conecta ao WhatsApp REAL, emite QR, NÃO pareia / NÃO usa número):
go test -tags live ./internal/client/ -run TestLive_EmitsQR -v

# Pareamento interativo real (só com chip sacrificial isolado):
go run ./cmd/wa-pair -db ./wa-pair.creds.db -timeout 120s
# renderiza o QR no terminal; escaneie em WhatsApp > Aparelhos conectados.

Recapturar traces (opcional)

Requer Node + cd harness && npm i. node harness/capture.mjs conecta ao WhatsApp real até o QR (não precisa de número) e regrava testdata/traces/connect_pair/. node harness/gen_codec_battery.mjs regenera a bateria do codec (offline).

⚠️ Conexão ao WhatsApp real pelo código Go só a partir do #2, e só com chip sacrificial isolado. Ver docs/superpowers/specs/ e docs/superpowers/decisions.md.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
wa-features command Command wa-features relogs in with saved creds and exercises the lib features that aren't surfaced in the wa/ facade or wa-evolution yet — profile, status (stories), newsletters and app-state resync — so they can be validated LIVE.	Command wa-features relogs in with saved creds and exercises the lib features that aren't surfaced in the wa/ facade or wa-evolution yet — profile, status (stories), newsletters and app-state resync — so they can be validated LIVE.
wa-manager command Command wa-manager runs N WhatsApp sessions concurrently in one process using the instance Manager (#7).	Command wa-manager runs N WhatsApp sessions concurrently in one process using the instance Manager (#7).
wa-pair command Command wa-pair runs the interactive WhatsApp multi-device pairing flow.	Command wa-pair runs the interactive WhatsApp multi-device pairing flow.
wa-paircode command Command wa-paircode runs the WhatsApp multi-device pairing-by-code flow ("link with phone number") instead of QR scanning.	Command wa-paircode runs the WhatsApp multi-device pairing-by-code flow ("link with phone number") instead of QR scanning.
wiredump command wiredump replays the connect_pair golden trace in memory, runs the Noise XX handshake, and prints each decoded binary node.	wiredump replays the connect_pair golden trace in memory, runs the Noise XX handshake, and prints each decoded binary node.
internal
appstate Package appstate implements WhatsApp Web "app state" sync: decoding the encrypted SyncdPatch blobs the server pushes (contacts, chat names, mute, read, pin, archive, ...) and maintaining the per-collection state with an LTHash integrity check.	Package appstate implements WhatsApp Web "app state" sync: decoding the encrypted SyncdPatch blobs the server pushes (contacts, chat names, mute, read, pin, archive, ...) and maintaining the per-collection state with an LTHash integrity check.
client Package client: appstate_sync.go implements app-state RESYNC — fetching and applying the server's app-state patches/snapshots for a set of collections.	Package client: appstate_sync.go implements app-state RESYNC — fetching and applying the server's app-state patches/snapshots for a set of collections.
control Package control is the wa-go anti-ban "Control Layer".	Package control is the wa-go anti-ban "Control Layer".
keys Package keys generates the cryptographic identity of a WhatsApp multi-device "companion" client.	Package keys generates the cryptographic identity of a WhatsApp multi-device "companion" client.
manager Package manager runs N WhatsApp sessions (each a client.Client with its own store) concurrently inside one process, with per-instance supervision, exponential-backoff reconnection with jitter, and an aggregated event stream tagged by instance name.	Package manager runs N WhatsApp sessions (each a client.Client with its own store) concurrently inside one process, with per-instance supervision, exponential-backoff reconnection with jitter, and an aggregated event stream tagged by instance name.
media Package media implements WhatsApp's media payload encryption: the symmetric crypto layer that cifrar/decifrar image/audio/video/document blobs.	Package media implements WhatsApp's media payload encryption: the symmetric crypto layer that cifrar/decifrar image/audio/video/document blobs.
signal Package signal implements the subset of the Signal protocol (X3DH + Double Ratchet) that WhatsApp multi-device uses for 1:1 encrypted messages.	Package signal implements the subset of the Signal protocol (X3DH + Double Ratchet) that WhatsApp multi-device uses for 1:1 encrypted messages.
store Package store persists a WhatsApp device's credentials and the signal-protocol state.	Package store persists a WhatsApp device's credentials and the signal-protocol state.
waproto Package waproto contains the subset of the WhatsApp Web protobuf schema needed for pairing/auth: ClientPayload (and its dependencies) plus the ADV* device-identity messages used by the pair-success flow.	Package waproto contains the subset of the WhatsApp Web protobuf schema needed for pairing/auth: ClientPayload (and its dependencies) plus the ADV* device-identity messages used by the pair-success flow.
wire Package wire implements the WhatsApp binary wire protocol.	Package wire implements the WhatsApp binary wire protocol.
ws Package ws provides the WhatsApp WebSocket transport adapter.	Package ws provides the WhatsApp WebSocket transport adapter.
wa Package wa is the public API facade for the wa-go WhatsApp library.	Package wa is the public API facade for the wa-go WhatsApp library.