Glossary¶

The terms the WaWarden documents use, in alphabetical order. Each entry links to the document that describes the term in full.

Contents¶

Admin token · All-chats client · Archive · Audit anchor · Audit chain · Backfill · Canonical identifier · Chain head · Chat reference · Client · Device store · EMF · Engine · First contact · Grant · History blob · History sync · Idempotency key · Inbox · Key id · LID · Linked device · Master key · MCP · Message reference · Owner · Pacer · Pairing code · Protocol library · Pseudonym · Quarantine · Read chat · Re-key · Retired key · Shipped head · Write chat

Admin token¶

The credential of the admin listener, of the form wwadm_.... wawarden admin init prints it once, with its SHA-256. The service is configured with the hash only and refuses the token itself. It never expires. See admin init and rotating the admin token.

All-chats client¶

A client created with --all-chats. It reads every chat, including chats that appear later, and can never write. admin status counts these clients under all-chats clients active.

Archive¶

archive.db in the data directory: the SQLite database that holds the chats, messages, the inbox, the clients and the audit chain. One connection holds it under an exclusive lock while the service runs. See the message archive.

Audit anchor¶

At most one row of the archive that records the last audit chain row the nightly retention removed. It holds that row's id, time, key id and HMAC, and is signed under the master key. Verification of the remaining chain starts from it. See audit retention.

Audit chain¶

The archive's audit table. A row records each client change and each client request that the read budget admits. Each row carries an HMAC over its fields and the previous row's HMAC, under a key derived from the master key. wawarden audit verify recomputes it. See the audit chain.

Backfill¶

A request to the owner's phone for older messages of one chat, made with wawarden admin backfill. The phone answers, when it does, with a history blob. Requests have a quota of one every 5 minutes and 20 a day. See admin backfill.

Canonical identifier¶

The one normalised form of a WhatsApp chat or user identifier: <digits>@s.whatsapp.net for a phone-number user, <digits>@lid for a LID user and <digits>@g.us or <digits>-<digits>@g.us for a group. The strict normaliser drops agent and device numbers and maps c.us to s.whatsapp.net. It is the only source of a chat that a grant can allow. See the threat model.

Chain head¶

The first 16 bytes, in hexadecimal, of an audit chain row's HMAC. The service writes it on standard output in the audit line of each row, as chain_head.

Chat reference¶

A chat's ref: 32 random lower-case hexadecimal digits that the archive assigns when it first stores the chat. The client API names chats by it, and admin chats list prints it. It never reveals a phone number and stays the same across a re-key. See chat references and identifiers.

Client¶

An API client holding a WaWarden token of the form ww_<client id>_.... It reads only its read chats and writes only to its write chats, until it expires or is revoked. On the WhatsApp side, WaWarden itself is a linked device. See the client API and the guide for agents.

Device store¶

session.db in the data directory: the SQLite database where the protocol library keeps the linked device's identity, session keys and pre-keys. Backups include it. See the device store.

EMF¶

Embedded metric format: CloudWatch's format for metrics written as log lines. With WAWARDEN_METRICS_EMF=1, the service writes its metrics in EMF on standard output every 60 seconds. See embedded metric format.

Engine¶

The part of the service that links the account, connects to WhatsApp and ingests what arrives. It reports a state: unpaired, connecting, connected or disconnected. A development build can run a scripted fake engine instead. See engine states and disconnect reasons.

First contact¶

A send to a direct chat that has never written to the account: the archive holds no message from the other person, of any kind. It is refused with 403 first_contact_refused unless the client was created with --allow-first-contact. Groups are exempt. See the ban-risk notes.

Grant¶

A value that the policy core mints for one request after deciding that the client may do it: a read grant, a write grant or an admin grant. Every read of the archive and every send takes one. Grants have unexported fields, so no other code can build one. See the threat model.

History blob¶

One part of the chat history that the owner's phone sends, announced by a notification. The engine downloads it into history/ in the data directory, applies it to the archive and deletes it. See history sync.

History sync¶

The transfer of the chat history from the owner's phone in history blobs, after pairing or in answer to a backfill. admin status shows history blobs pending and history blobs quarantined.

Idempotency key¶

The required Idempotency-Key header of a send: 8 to 128 printable ASCII characters, such as a UUID. The service keeps each key for 24 hours per client. A repeat with the same chat, text and reply target sends nothing and answers as the first did. See sending.

Inbox¶

The table of the archive where the engine writes each live message before WhatsApp is acknowledged. One worker applies it in order. A row that fails three times is quarantined.

Key id¶

8 hexadecimal digits derived from a master key. It names the key of each audit row, of the audit anchor, of each cursor and message reference, and the file of a retired key. The keys_loaded event logs it.

LID¶

A WhatsApp user identifier that is not a phone number, written <digits>@lid. WhatsApp uses it in place of a phone number in some chats. The engine learns which LID belongs to which phone number from live messages and history sync, and then re-keys the chat.

Linked device¶

A device linked to the owner's WhatsApp account, such as WhatsApp Web or WaWarden itself, which links as Chrome (Linux). Another linked device has the account's full access, outside every scope and audit row of WaWarden. See retiring other linked devices.

Master key¶

keys/master in the data directory: 32 random bytes that the first start creates. Every key the service uses is derived from it with HKDF-SHA256. No backup holds it, so keep a copy off the host. wawarden keys rotate replaces it. See the master key.

MCP¶

The Model Context Protocol. The client listener serves the client API as MCP tools at POST /mcp, through the MCP library, for an MCP client such as Claude Code. See MCP.

Message reference¶

A message's mref: a value sealed under a key derived from the master key, which names a message for one client only. A send takes one as reply_to. See cursors and message references.

Owner¶

The person whose WhatsApp account WaWarden links, named by WAWARDEN_OWNER_PHONE. Only that account can be paired.

Pacer¶

The shared limit in front of every send: one send at a time, and each send of any client starts at least 3 seconds plus a random wait of up to 2 seconds after the previous one was admitted. A send it refuses answers 429 rate_limited. See send limits.

Pairing code¶

The code that wawarden admin pair prints, to enter on the owner's phone under Linked devices, Link with phone number instead. It is never logged or kept. See Getting started.

Protocol library¶

go.mau.fi/whatsmeow, the unofficial implementation of WhatsApp's multi-device protocol that the engine uses. Only one adapter package imports it. It sends some traffic by itself (see residual risks).

Pseudonym¶

What a WhatsApp identifier becomes in a log line: jid: and 8 hexadecimal digits of an HMAC under a key derived from the master key. The same identifier keeps the same pseudonym while the master key stays the same. See pseudonyms.

Quarantine¶

What happens to a history blob or an inbox row that fails three times, or a blob larger than WAWARDEN_HISTORY_MAX_BYTES. Its content is deleted, a record stays, and the quarantine event reports it with its queue.

Read chat¶

A chat a client may read, given with --read when the client is created. It is stored as a canonical identifier, so it may name a chat the archive has not seen yet.

Re-key¶

The move of a direct chat from a phone-number identifier to the person's LID, once the engine learns the mapping. It moves the chat, every client's read and write chats and the contact's names in one transaction, and keeps the chat reference. A mapping that would widen what a client reads is refused as a rekey_conflict. See ingest.

Retired key¶

A former master key kept in keys/retired/, named by its key id. wawarden keys rotate puts the old key there. The service uses it only to open cursors and message references sealed under it, and to verify audit rows written under it.

Shipped head¶

A chain head that left the host in the service's standard output, kept in a store the host cannot rewrite. wawarden audit verify --log reports every shipped head that a copy of the archive lacks, which detects rows removed from the end of the chain. See shipped heads.

Write chat¶

A chat a client may send to, given with --write when the client is created. Each write chat must also be a read chat, and an all-chats client has none.