c/quicproquo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite mdBook documentation for v2 architecture

Browse Source 
Update 25+ files and add 6 new pages to reflect the v2 migration from
Cap'n Proto to Protobuf framing over QUIC. Integrates SDK and Operations
docs into the mdBook, restructures SUMMARY.md, and rewrites the wire
format, architecture, and protocol sections with accurate v2 content.
This commit is contained in:
Christian Nennemann
2026-03-04 22:02:31 +01:00
parent f7a7f672b4
commit d073f614b3
31 changed files with 4423 additions and 2379 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/src/introduction.md
View File

@@ -1,26 +1,26 @@
# Introduction
**quicproquo** is a research-oriented, end-to-end encrypted group messaging system written in Rust. It layers the Messaging Layer Security protocol (MLS, [RFC 9420](https://datatracker.ietf.org/doc/rfc9420/)) on top of QUIC + TLS 1.3 transport (via [quinn](https://github.com/quinn-rs/quinn) and [rustls](https://github.com/rustls/rustls)), with all service RPCs and wire messages framed using [Cap'n Proto](https://capnproto.org/). The project exists to explore how modern transport encryption (QUIC), a formally specified group key agreement protocol (MLS), and a zero-copy serialisation format (Cap'n Proto) compose in practice -- and to provide a readable, auditable reference implementation for security researchers, protocol designers, and Rust developers who want to study or extend the design.
**quicproquo** is a research-oriented, end-to-end encrypted group messaging system written in Rust. It layers the Messaging Layer Security protocol (MLS, [RFC 9420](https://datatracker.ietf.org/doc/rfc9420/)) on top of QUIC + TLS 1.3 transport (via [quinn](https://github.com/quinn-rs/quinn) and [rustls](https://github.com/rustls/rustls)), with all service RPCs framed using a compact binary Protocol Buffers format over a custom framing layer. The project exists to explore how modern transport encryption (QUIC), a formally specified group key agreement protocol (MLS), and post-quantum hybrid key encapsulation compose in practice -- and to provide a readable, auditable reference implementation for security researchers, protocol designers, and Rust developers who want to study or extend the design.
---
## Protocol stack
```
┌─────────────────────────────────────────────┐
│ Application / MLS ciphertext │ <- group key ratchet (RFC 9420)
├─────────────────────────────────────────────┤
│ Cap'n Proto RPC │ <- typed, schema-versioned framing
├─────────────────────────────────────────────┤
│ QUIC + TLS 1.3 (quinn/rustls) │ <- mutual auth + transport secrecy
└─────────────────────────────────────────────┘
+---------------------------------------------+
| Application / MLS ciphertext | <- group key ratchet (RFC 9420)
+---------------------------------------------+
| Protobuf framing (custom binary header) | <- typed, length-prefixed framing
+---------------------------------------------+
| QUIC + TLS 1.3 (quinn/rustls) | <- mutual auth + transport secrecy
+---------------------------------------------+
```
Each layer addresses a distinct concern:
1. **QUIC + TLS 1.3** provides authenticated, confidential transport with 0-RTT connection establishment and multiplexed streams. The server presents a TLS 1.3 certificate (self-signed by default); the client verifies it against a local trust anchor. ALPN negotiation uses the token `b"capnp"`.
1. **QUIC + TLS 1.3** provides authenticated, confidential transport with 0-RTT connection establishment and multiplexed streams. The server presents a TLS 1.3 certificate (self-signed by default); the client verifies it against a local trust anchor. ALPN negotiation uses the token `qpq`.
2. **Cap'n Proto RPC** defines the wire schema for all service operations (KeyPackage upload/fetch, message enqueue/fetch, health probes). Schemas live in `schemas/*.capnp` and are compiled to Rust at build time. Because Cap'n Proto uses a pointer-based layout, messages can be read without an unpacking step -- though quicproquo currently uses the unpacked wire format for simplicity.
2. **Protobuf framing** defines the wire format for all service operations across 44 RPC methods. Each request carries a `[method_id: u16][request_id: u32][payload_len: u32]` header followed by a Protobuf-encoded payload. Server-to-client push events use a separate frame type on QUIC uni-streams. Message definitions live in `proto/qpq/v1/*.proto` and are compiled to Rust with `prost` at build time.
3. **MLS (RFC 9420)** provides the group key agreement layer. Each participant holds an Ed25519 identity keypair and generates single-use HPKE KeyPackages. The MLS epoch ratchet delivers forward secrecy and post-compromise security: compromising a member's state at epoch *n* does not reveal plaintext from epochs *< n* (forward secrecy) or *> n+1* (post-compromise security, once the compromised member updates).
@@ -39,7 +39,7 @@ Each layer addresses a distinct concern:
| Password auth | OPAQUE (password never sent to server) |
| Metadata protection | Sealed sender + message padding |
| Local storage | SQLCipher + Argon2id + ChaCha20-Poly1305 |
| Framing | Cap'n Proto (unpacked wire format, schema-versioned) |
| Framing | Protobuf (prost) with custom binary header (method_id, request_id, length) |
For a deeper discussion of the cryptographic guarantees, threat model, and known gaps, see:
@@ -51,22 +51,20 @@ For a deeper discussion of the cryptographic guarantees, threat model, and known
## Who is this for?
**Security researchers** studying how MLS composes with QUIC transport and Cap'n Proto framing. The codebase spans 12 crates with clear cryptographic boundaries for auditability.
**Security researchers** studying how MLS composes with QUIC transport and post-quantum hybrid KEM. The codebase spans 9 workspace crates with clear cryptographic boundaries for auditability.
**Protocol designers** evaluating MLS deployment patterns. quicproquo implements a concrete Authentication Service (AS) and Delivery Service (DS) pair, demonstrating single-use KeyPackage lifecycle, Welcome routing, and epoch advancement in a live system.
**Application developers** building on the platform via SDKs:
**Application developers** building on the platform via the Rust SDK:
- **Go SDK** — native QUIC + Cap'n Proto client with full API
- **TypeScript SDK** — WASM crypto + WebSocket transport for browsers
- **C FFI** — cross-language integration (Python, Swift, Kotlin)
- **`quicproquo-sdk`** -- `QpqClient` with async event streams and a `ConversationStore`
- **C FFI** -- cross-language integration via `quicproquo-plugin-api`
**Rust developers** looking for a working example of:
- `quinn` + `rustls` server/client setup with self-signed certificates
- `capnp-rpc` over QUIC bidirectional streams (including the `!Send` / `LocalSet` constraint)
- Custom binary framing over QUIC bidirectional streams
- `openmls` group creation, member addition, and application message encryption
- `wasm-bindgen` for compiling Rust crypto to WebAssembly
- `zeroize`-on-drop key material handling
---
@@ -77,19 +75,13 @@ For a deeper discussion of the cryptographic guarantees, threat model, and known
|---|---|
| **[Comparison with Classical Protocols](design-rationale/protocol-comparison.md)** | **Why quicproquo? IRC+SSL, XMPP, Telegram vs. our design** |
| [Prerequisites](getting-started/prerequisites.md) | Toolchain and system dependencies |
| [Building from Source](getting-started/building.md) | `cargo build`, Cap'n Proto codegen, troubleshooting |
| [Building from Source](getting-started/building.md) | `cargo build`, Protobuf codegen, troubleshooting |
| [Running the Server](getting-started/running-the-server.md) | Server startup, configuration, TLS cert generation |
| [Running the Client](getting-started/running-the-client.md) | All CLI subcommands with examples |
| [REPL Command Reference](getting-started/repl-reference.md) | Complete list of 40+ slash commands |
| [Rich Messaging](getting-started/rich-messaging.md) | Reactions, typing, read receipts, edit/delete |
| [File Transfer](getting-started/file-transfer.md) | Chunked upload/download with SHA-256 verification |
| [Go SDK](getting-started/go-sdk.md) | Native QUIC + Cap'n Proto Go client |
| [TypeScript SDK & Browser Demo](getting-started/typescript-sdk.md) | WASM crypto + WebSocket transport |
| [Mesh Networking](getting-started/mesh-networking.md) | P2P, broadcast channels, store-and-forward, federation |
| [Demo Walkthrough](getting-started/demo-walkthrough.md) | Step-by-step Alice-and-Bob narrative with sequence diagram |
| [Architecture Overview](architecture/overview.md) | Crate boundaries, service architecture, data flow |
| [Protocol Layers](protocol-layers/overview.md) | Deep dives into QUIC/TLS, Cap'n Proto, MLS, Hybrid KEM |
| [Wire Format Reference](wire-format/overview.md) | Cap'n Proto schema documentation |
| [Protocol Layers](protocol-layers/overview.md) | Deep dives into QUIC/TLS, Protobuf framing, MLS, Hybrid KEM |
| [Wire Format Reference](wire-format/overview.md) | Protobuf schema documentation and method ID table |
| [Cryptography](cryptography/overview.md) | Identity keys, key lifecycle, forward secrecy, PCS, threat model |
| [Design Rationale](design-rationale/overview.md) | ADRs and protocol design decisions |
| [Roadmap](roadmap/milestones.md) | Milestone tracker and future research directions |
@@ -99,26 +91,28 @@ For a deeper discussion of the cryptographic guarantees, threat model, and known
## Current status
quicproquo is a **research project** with production-grade features. It has
not been audited by a third party. The test suite covers 130+ tests across
not been audited by a third party. The test suite covers 301 tests across
core, server, client, E2E, and P2P modules.
**What works today:**
- Full-featured REPL with 40+ commands: DMs, groups, reactions, typing,
edit/delete, file transfer, disappearing messages, safety numbers, MLS key
rotation, account deletion
- Go SDK, TypeScript SDK (WASM crypto + browser demo), C FFI + Python bindings
- Mesh networking: P2P via iroh, mDNS discovery, federation, store-and-forward,
broadcast channels
- Dynamic plugin system with 6 C-compatible hook points
- 24 Cap'n Proto RPC methods on the server
- OPAQUE password authentication (register + login, 4-method handshake)
- 44 Protobuf RPC methods across 14 proto files and 9 workspace crates
- MLS group creation, member add, message encryption, and epoch advancement
- Hybrid X25519 + ML-KEM-768 key encapsulation for post-quantum readiness
- SQLCipher-backed local storage with Argon2id key derivation
- Key transparency (REVOKE, CHECK_REVOCATION, AUDIT)
- Multi-device management and push notification registration
- Blob storage (upload/download)
- Federation relay for cross-server message delivery
- Content moderation (report, ban, unban)
- Account recovery bundle store
**Known limitations:**
- MLS credentials use `CredentialType::Basic` (raw public key). A production system would bind credentials to a certificate authority or use X.509 certificates.
- The hybrid KEM envelope is implemented and tested, but not yet integrated into the OpenMLS CryptoProvider for full post-quantum MLS (milestone M7).
- Browser connectivity requires a WebSocket-to-Cap'n-Proto bridge proxy (not yet included).
- The GUI crate (`quicproquo-gui`) requires GTK system libraries and is not feature-complete.
- The hybrid KEM envelope is implemented and tested, but not yet integrated into the OpenMLS CryptoProvider for full post-quantum MLS (planned for a future milestone).
- Browser connectivity requires a WebSocket-to-Protobuf bridge proxy (not yet included).
For the full milestone tracker, see [Milestones](roadmap/milestones.md).