Pigeon for developers
These pages are for engineers who want to know exactly what Pigeon does before trusting it. Each one covers one topic, says what is built and what is planned, and cites the design record it comes from.
Pigeon is one Rust core, shared by every app, that does all of the cryptography and protocol work, and a network of mailbox servers that store and forward bytes they can't read. Group encryption is MLS (RFC 9420) through OpenMLS. The code is MIT-licensed.
Built means the code is merged into the main branch and tested. Planned means it's designed, or decided, but not built. Nothing here describes a production network yet: Pigeon is in private alpha.
Architecture overview
How Pigeon is built: one Rust core for every client, blind mailbox nodes, five-replica rendezvous placement, rotating mailbox ids and sealed envelopes.
Desktop app architecture
How the Pigeon desktop app is built: one Rust core, a thin Tauri shell, the store key in the OS keystore, and a locked-down web layer that loads nothing remote.
Group encryption (MLS) and ordering
How Pigeon uses MLS (RFC 9420) through OpenMLS for every chat, and how a five-replica commit slot keeps one agreed history per epoch, checked with TLA+.
Message ordering and outages
How Pigeon orders messages and group changes, what the app shows during an outage, and why an accepted message is never dropped, only delayed.
Identity, the key log and seed phrases
How a Pigeon account works without a phone number: a pre-rotated root key, per-device keys, a 24-word seed phrase and a planned key log.
Handles and lookups
How Pigeon handles work: optional names, exact-match lookup, look-alike protection, what the directory learns today and the private lookup planned.
Invite codes and the private alpha
How Pigeon's private alpha works: single-use invite codes built on blind tokens, what the server keeps, what it can't link, and what is still planned.
The seed phrase, shown once
Why Pigeon shows your 24-word seed phrase exactly once at sign-up, what it can do, what happens if you lose it, and how the sign-up check works.
Stolen-device rescue and the trusted circle
What happens when a Pigeon device is stolen: instant revoke, seed-phrase rotation and quarantine, time-locked rescue, and the trusted circle.
Trusted circle and group transparency
Pigeon's trusted circle is opt-in and empty by default; groups have no admins, and every member sees the same signed answer to who gets security alerts.
Attachments, padding and erasure coding
How Pigeon sends attachments: two-layer ChaCha20-Poly1305 with key commitment, 1 MiB parts, Padmé size padding and Reed-Solomon RS(9,6) erasure coding.
Reporting and message franking
How Pigeon lets people report abuse without scanning chats: franking commitments, asymmetric message franking (AMF) on Ristretto255, and sealed reports.
Media tokens (Privacy Pass, RFC 9497)
How Pigeon limits media storage without tracking users: privately verifiable Privacy Pass-style tokens built on the RFC 9497 VOPRF with ristretto255-SHA512.
Reliability and delivery
Pigeon's delivery rule: an accepted message is never dropped and waits out outages. The delivery target, quorum writes and zero-loss soak results.
Threat model summary
Pigeon's threat model in brief: thirteen attacker types, what is defended today, the known gaps and what is out of scope.
Security review FAQ
Straight answers for security reviewers: audit status, what servers see, post-quantum coverage, unsafe code, testing, signed builds and how to report a bug.
Open-source licences
Pigeon's code is MIT-licensed. The licence rule its dependencies must meet, every named exception and why, and credits for the research it builds on.
Citations name files in the Pigeon repository: architecture decision records (docs/adr/), wire specifications (docs/specs/) and the threat model (docs/THREAT_MODEL.md).