# Introduction

**quicprochat** 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)
+---------------------------------------------+
|   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 `qpc`.

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

---

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

- [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 post-quantum hybrid KEM. The codebase spans 9 workspace crates with clear cryptographic boundaries for auditability.

**Protocol designers** evaluating MLS deployment patterns. quicprochat 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 the Rust SDK:

- **`quicprochat-sdk`** -- `QpqClient` with async event streams and a `ConversationStore`
- **C FFI** -- cross-language integration via `quicprochat-plugin-api`

**Rust developers** looking for a working example of:

- `quinn` + `rustls` server/client setup with self-signed certificates
- Custom binary framing over QUIC bidirectional streams
- `openmls` group creation, member addition, and application message encryption
- `zeroize`-on-drop key material handling

---

## Quick links

| Section | What you will find |
|---|---|
| **[Comparison with Classical Protocols](design-rationale/protocol-comparison.md)** | **Why quicprochat? 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`, 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 |
| [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, 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 |

---

## Current status

quicprochat is a **research project** with production-grade features. It has
not been audited by a third party. The test suite covers 301 tests across
core, server, client, E2E, and P2P modules.

**What works today:**

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

---

## License

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