quicproquo/README.md

# quicproquo

> End-to-end encrypted group messaging over **QUIC + TLS 1.3 + MLS** (RFC 9420), written in Rust.

Every byte on the wire is protected by a QUIC transport secured with TLS 1.3
(`quinn` + `rustls`). The inner **MLS** layer provides post-compromise security
and ratcheted group key agreement across any number of participants. Messages
are framed with **Cap'n Proto**, keeping serialisation zero-copy and
schema-versioned.

```
┌─────────────────────────────────────────────┐
│          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
└─────────────────────────────────────────────┘
```

| Property | Mechanism |
|---|---|
| Transport confidentiality | TLS 1.3 over QUIC (rustls) |
| Transport authentication | TLS 1.3 server cert (self-signed by default) |
| Group key agreement | MLS `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` |
| Post-compromise security | MLS epoch ratchet |
| Identity | Ed25519 (MLS credential + leaf node signature) |
| Message framing | Cap'n Proto (unpacked wire format) |

---

## Documentation

Full documentation is available as an **mdBook** wiki in [`docs/`](docs/):

```bash
# Install mdBook (once)
cargo install mdbook

# Build and serve locally
mdbook serve docs
# Open http://localhost:3000
```

### Highlights

- **[Architecture Overview](docs/src/architecture/overview.md)** — Two-service model, dual-key design, crate layout
- **[Protocol Deep Dives](docs/src/protocol-layers/overview.md)** — QUIC/TLS 1.3, Cap'n Proto, MLS, Hybrid KEM
- **[Cryptographic Properties](docs/src/cryptography/overview.md)** — Forward secrecy, post-compromise security, PQ readiness, threat model
- **[Design Rationale](docs/src/design-rationale/overview.md)** — Why MLS over Signal/Matrix, ADRs for all key decisions
- **[Wire Format Reference](docs/src/wire-format/overview.md)** — Annotated Cap'n Proto schemas
- **[Getting Started](docs/src/getting-started/prerequisites.md)** — Build, run, demo walkthrough
- **[Roadmap](docs/src/roadmap/milestones.md)** — Milestones, production readiness, future research
- **[Future Improvements](docs/FUTURE-IMPROVEMENTS.md)** — Prioritised list of security, ops, reliability, and feature improvements

---

## Quick start

```bash
# Prerequisites: Rust 1.77+, capnp CLI
brew install capnp          # macOS
# apt-get install capnproto # Debian/Ubuntu

# GUI prerequisites (Linux only) — WebKitGTK + GTK3 for Tauri 2
# sudo apt install -y libwebkit2gtk-4.1-dev libgtk-3-dev libglib2.0-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf

# Build and test
cargo build --workspace
cargo test --workspace

# Start the server (port 7000 by default)
cargo run -p quicproquo-server

# Or via a config file (TOML)
# Note: auth_token = "devtoken" and db_key = "" are for development only.
# Production: set QPQ_AUTH_TOKEN to a strong secret and (when store_backend = "sql")
# set QPQ_DB_KEY so the database is encrypted. Empty db_key = plaintext DB (insecure).
cat > qpq-server.toml <<'EOF'
listen = "0.0.0.0:7000"
data_dir = "data"
tls_cert = "data/server-cert.der"
tls_key = "data/server-key.der"
auth_token = "devtoken"
store_backend = "file" # or "sql"
db_path = "data/qpq.db"
db_key = ""
EOF
cargo run -p quicproquo-server -- --config qpq-server.toml

# Run the two-party demo
cargo run -p quicproquo-client -- demo-group \
  --server 127.0.0.1:7000

# Interactive 1:1 chat (after creating a group and inviting a peer)
# Terminal 1: qpq chat --peer-key <other_identity_hex>
# Terminal 2: qpq chat --peer-key <first_identity_hex>
# Type messages and press Enter; incoming messages appear as [peer] <msg>. Ctrl+D to exit.
```

See the [full demo walkthrough](docs/src/getting-started/demo-walkthrough.md) for a step-by-step guide.

---

## Milestones

| # | Name | Status | What it adds |
|---|------|--------|--------------|
| M1 | QUIC/TLS transport | Done | QUIC + TLS 1.3 endpoint, length-prefixed framing, Ping/Pong |
| M2 | Authentication Service | Done | Ed25519 identity, KeyPackage generation, AS upload/fetch |
| M3 | Delivery Service + MLS groups | Done | DS relay, `GroupMember` create/join/add/send/recv |
| M4 | Group CLI subcommands | Done | Persistent CLI (`create-group`, `invite`, `join`, `send`, `recv`), OPAQUE login |
| M5 | Multi-party groups | Done | N > 2 members, Commit fan-out, send --all, epoch sync |
| M6 | Persistence | Done | SQLite/SQLCipher, migrations, durable server + client state |
| M7 | Post-quantum | Next | PQ hybrid for MLS/HPKE (X25519 + ML-KEM-768) |

---

## Building without the GUI

To build only the server and CLI client (faster, no Tauri/WebKit):

```bash
cargo build -p quicproquo-server -p quicproquo-client
```

Core and proto crates are built as dependencies. Omit `quicproquo-gui` and `quicproquo-p2p` if you don't need them.

---

## Security notes

This is a **proof-of-concept research project**. It has not undergone a formal third-party audit. See the [threat model](docs/src/cryptography/threat-model.md) for what is and isn't protected, and the [security audit](docs/SECURITY-AUDIT.md) for an internal review of authentication, crypto, transport, and authorization.

- **Dependency checks:** Run `cargo install cargo-audit && cargo audit` to check for known vulnerabilities.
- **Certificate pinning:** Use the server's certificate as `--ca-cert` (e.g. copy `server-cert.der` from the server) so the client only trusts that server; see [Certificate pinning](docs/SECURITY-AUDIT.md#certificate-pinning) in the security audit.

**Production deployment:** Set `QPQ_PRODUCTION=1` and provide a strong `QPQ_AUTH_TOKEN` (not `devtoken`). When using `store_backend = "sql"`, set `QPQ_DB_KEY`; an empty key leaves the database unencrypted on disk.

---

## License

MIT