# 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.

---

## 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
└─────────────────────────────────────────────┘
```

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"`.

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.

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).

---

## Security properties

| Property | Mechanism |
|---|---|
| Transport confidentiality | TLS 1.3 over QUIC (`rustls` with `TLS13` only) |
| Transport authentication | TLS 1.3 server certificate (self-signed, SANs: `localhost`, `127.0.0.1`, `::1`) |
| Group key agreement | `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` |
| Post-compromise security (PCS) | MLS epoch ratchet -- each Commit advances the key schedule |
| Post-quantum readiness | X25519 + ML-KEM-768 hybrid KEM envelope |
| Identity | Ed25519 (`ed25519-dalek`); public key used as MLS `BasicCredential` |
| 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) |

For a deeper discussion of the cryptographic guarantees, threat model, and known gaps, see:

- [Forward Secrecy](cryptography/forward-secrecy.md)
- [Post-Compromise Security](cryptography/post-compromise-security.md)
- [Threat Model](cryptography/threat-model.md)

---

## 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.

**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:

- **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)

**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)
- `openmls` group creation, member addition, and application message encryption
- `wasm-bindgen` for compiling Rust crypto to WebAssembly
- `zeroize`-on-drop key material handling

---

## Quick links

| Section | What you will find |
|---|---|
| **[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 |
| [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 |
| [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 |

---

## 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
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

**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.

For the full milestone tracker, see [Milestones](roadmap/milestones.md).

---

## License

quicproquo is released under the **MIT** license. See `LICENSE` in the repository root.
