# QPQ — quicproquo [](https://github.com/xorwell/quicproquo/actions/workflows/ci.yml) > End-to-end encrypted messaging over **QUIC + TLS 1.3 + MLS** (RFC 9420), written in Rust. The server never sees plaintext. Every byte on the wire is protected by a QUIC transport secured with TLS 1.3 (`quinn` + `rustls`). The inner **MLS** layer provides forward secrecy, post-compromise security, and ratcheted group key agreement across any number of participants. Messages are framed with **Cap'n Proto** for zero-copy, schema-versioned serialisation. ``` ┌─────────────────────────────────────────────┐ │ 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 or CA) | | Group key agreement | MLS `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` | | Post-compromise security | MLS epoch ratchet | | Forward secrecy | Per-epoch key schedule | | Identity | Ed25519 (MLS credential + leaf node signature) | | Password auth | OPAQUE (password never sent to server) | | Post-quantum readiness | X25519 + ML-KEM-768 hybrid KEM envelope | | Local storage encryption | SQLCipher + Argon2id + ChaCha20-Poly1305 | | Message framing | Cap'n Proto (unpacked wire format) | --- ## Features ### Core - **Interactive REPL** — multi-conversation chat with auto-register, auto-login, 40+ slash commands, background polling, and message history - **1:1 DMs** — dedicated channels with server-enforced membership authorization - **Multi-party groups** — N-member MLS groups with Commit fan-out and epoch sync - **OPAQUE authentication** — password-authenticated key exchange (password never leaves the client) - **Encrypted local storage** — SQLCipher database + encrypted session tokens (Argon2id + ChaCha20-Poly1305) - **Persistent state** — server and client survive restarts; SQLite/SQLCipher or file-backed storage - **Rich messaging** — reactions, read receipts, typing indicators, message editing, message deletion - **File transfer** — chunked upload/download with SHA-256 content addressing, MIME detection, 50 MB limit - **Disappearing messages** — per-conversation TTL with server-side GC (`/disappear 30m`, `1h`, `1d`, `7d`) - **Account deletion** — transactional purge of all user data, sessions, and channel memberships (GDPR-ready) - **Self-DM notepad** — send messages to yourself (local-only, no server round-trip) - **Certificate pinning** — pass the server cert as `--ca-cert` to trust only that server - **Federation** — server-to-server message relay via Cap'n Proto RPC over QUIC with mTLS - **mDNS discovery** — servers announce `_quicproquo._udp.local.`; clients auto-discover nearby nodes - **Sealed sender mode** — optional anonymous enqueue (sender identity inside MLS ciphertext only) - **Prometheus metrics** — `--metrics-listen` exposes `/metrics` endpoint for monitoring - **Dynamic plugin system** — load `.so`/`.dylib` plugins at runtime via `--plugin-dir` - **Safety numbers** — `/verify ` for out-of-band key verification (60-digit numeric code) - **Transcript export** — encrypted, tamper-evident message archives with hash-chain integrity verification - **MLS key rotation** — `/update-key` rotates MLS leaf node material with epoch advancement ### Client SDKs - **Go SDK** (`sdks/go/`) — native QUIC transport via `quic-go`, Cap'n Proto RPC, full API: connect, OPAQUE auth, send/receive, disappearing messages, account deletion - **TypeScript SDK** (`sdks/typescript/`) — `@quicproquo/client` with WASM crypto (175 KB), WebSocket transport, offline crypto mode, browser demo - **Python FFI** (`examples/python/`) — `ctypes` wrapper over the C FFI library with CLI - **C FFI** (`crates/quicproquo-ffi/`) — `libquicproquo_ffi.so` with 7 extern functions: connect, login, send, receive, disconnect, last_error, free_string ### REPL slash commands | Command | Description | |---|---| | `/dm ` | Start a 1:1 DM with a peer | | `/create-group ` (or `/cg`) | Create a new group | | `/invite ` | Add a member to the current group | | `/remove ` | Remove a member from the current group | | `/join` | Join a pending group invitation | | `/leave` | Leave the current group | | `/switch @user` or `/switch #group` | Switch active conversation | | `/list` or `/ls` | List all conversations | | `/members` | Show group members with resolved usernames | | `/group-info` (or `/gi`) | Show group type, members, MLS epoch | | `/rename ` | Rename the current conversation | | `/history [count]` (or `/hist`) | Show message history (default 20) | | `/react [index]` | React to a message with an emoji | | `/typing` | Send a typing indicator | | `/typing-notify on\|off` | Toggle typing indicator display | | `/edit ` | Edit one of your messages | | `/delete ` | Delete one of your messages | | `/send-file ` (or `/sf`) | Upload and send a file (chunked, SHA-256 verified) | | `/download ` (or `/dl`) | Download a received file | | `/disappear ` | Set message TTL (`30m`, `1h`, `1d`, `7d`) | | `/verify ` | Compare safety numbers with a peer | | `/update-key` (or `/rotate-key`) | Rotate your MLS key material | | `/delete-account` | Permanently delete your account (with confirmation) | | `/whoami` | Show identity and group status | | `/help` | Command reference | | `/quit` | Exit | **Mesh commands** (requires `--features mesh`): | Command | Description | |---|---| | `/mesh peers` | Scan for nearby qpq nodes via mDNS | | `/mesh server ` | Note a discovered server address | | `/mesh send ` | Direct P2P message via iroh | | `/mesh broadcast ` | Publish to a broadcast channel | | `/mesh subscribe ` | Join a broadcast channel | | `/mesh route` | Show routing table | | `/mesh identity` | Show mesh identity info | | `/mesh store` | Show store-and-forward stats | ### Mesh networking (feature-gated: `--features mesh`) - **P2P transport** (`quicproquo-p2p`) — iroh-based direct peer-to-peer messaging with NAT traversal - **Self-sovereign identity** — Ed25519 keypair-based mesh identity, independent of server registration - **Store-and-forward** — TTL-based message buffering with hop counting and deduplication - **Broadcast channels** — ChaCha20-Poly1305 symmetric topic-based pub/sub (no MLS overhead) - **mDNS discovery** — servers announce `_quicproquo._udp.local.`; clients auto-discover nearby nodes - **Federation routing** — server-to-server message relay with mTLS ### Experimental / proof-of-concept - **Tauri 2 GUI** (`quicproquo-gui`) — foundational desktop app shell; not feature-complete - **Mobile FFI** (`quicproquo-mobile`) — C API for QUIC connection migration (wifi to cellular) - **Bot framework** (`quicproquo-bot`) — programmable bot client --- ## Quick start ```bash # Prerequisites: Rust 1.77+, capnp CLI brew install capnp # macOS # apt-get install capnproto # Debian/Ubuntu # Build (excludes GUI — requires GTK system libs) cargo build --bin qpq-server --bin qpq # Run tests cargo test --workspace --exclude quicproquo-gui # Start the server (port 7000 by default, auto-generates self-signed cert) cargo run --bin qpq-server -- --allow-insecure-auth # Interactive REPL (auto-registers and logs in) cargo run --bin qpq -- repl --username alice --password mypass ``` ### REPL quickstart (two terminals) ```bash # Terminal 1 qpq repl --username alice --password secretA # Terminal 2 qpq repl --username bob --password secretB # In Alice's REPL: /dm bob Hello from Alice! # Bob sees: [alice] Hello from Alice! ``` ### Server configuration (TOML) ```bash 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 = "your-strong-token-here" store_backend = "sql" # or "file" db_path = "data/qpq.db" db_key = "your-db-encryption-key" metrics_listen = "0.0.0.0:9090" metrics_enabled = true # Federation (optional) # federation_enabled = true # federation_domain = "chat.example.com" # federation_listen = "0.0.0.0:7001" # Plugin loading (optional) # plugin_dir = "/etc/qpq/plugins" EOF cargo run --bin qpq-server -- --config qpq-server.toml ``` > **Production:** use a strong `QPQ_AUTH_TOKEN`, set `QPQ_DB_KEY` when using `store_backend = "sql"`, and provide real TLS certificates (the server refuses to auto-generate certs in production mode). See the [full demo walkthrough](docs/src/getting-started/demo-walkthrough.md) for a step-by-step guide. --- ## Crate layout | Crate | Purpose | |---|---| | `quicproquo-core` | MLS group operations, hybrid KEM, OPAQUE auth, crypto primitives, WASM-compatible modules | | `quicproquo-proto` | Cap'n Proto schemas and generated RPC code | | `quicproquo-server` | QUIC server, NodeService RPC (24 methods), storage backends, federation, plugins, blob storage | | `quicproquo-client` | CLI + REPL (40+ commands), session management, conversation store, file transfer | | `quicproquo-ffi` | C FFI bindings (`libquicproquo_ffi.so`) for cross-language integration | | `quicproquo-plugin-api` | C-compatible plugin hook API (`HookVTable`, 6 hooks) | | `quicproquo-kt` | Key transparency / Merkle-log identity bindings | | `quicproquo-bot` | Programmable bot client framework | | `quicproquo-gen` | Code generation utilities | | `quicproquo-gui` | Tauri 2 desktop app (experimental, requires GTK) | | `quicproquo-mobile` | C FFI for mobile connection migration (experimental) | | `quicproquo-p2p` | iroh-based P2P transport, mesh identity, store-and-forward, broadcast channels | --- ## CI pipeline GitHub Actions runs on every push and PR: - `cargo fmt --check` — formatting - `cargo build --workspace` — full build - `cargo test --workspace` — 130+ tests (core, server, client, E2E, P2P, doctests) - `cargo clippy --workspace` — lint - `cargo deny check` — license and advisory audit - `cargo audit` — vulnerability scan - `cargo tarpaulin` — code coverage (uploaded as artifact) - `docker build` — container image validation --- ## 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, OPAQUE login, 20 subcommands | | M5 | Multi-party groups | **Done** | N > 2 members, Commit fan-out, `send --all`, epoch sync | | M6 | Persistence + REPL | **Done** | SQLite/SQLCipher, interactive REPL, DM channels, encrypted local storage | | M7 | Post-quantum MLS | **Planned** | Hybrid X25519 + ML-KEM-768 integrated into MLS ciphersuite | M7 note: the hybrid KEM envelope is already implemented and tested (10 tests passing). What remains is integrating it into the OpenMLS CryptoProvider so all MLS key material gets post-quantum confidentiality. --- ## Roadmap See [ROADMAP.md](ROADMAP.md) for the full phased plan. Summary: | Phase | Focus | Status | |-------|-------|--------| | 1 | Production hardening (unwrap removal, secure defaults, Docker) | In progress | | 2 | Test and CI maturity | Partially done | | 3 | Client SDKs (Go, TypeScript/WASM, Python FFI, C FFI) | **Go, TS, FFI, WASM done** | | 4 | Trust and security (audit, key transparency, PQ MLS) | DS auth + enumeration mitigation done | | 5 | Features and UX (rich messaging, file transfer, disappearing) | **Edit/delete, files, TTL done** | | 6 | Scale and operations (horizontal scaling, observability) | Planned | | 7 | Platform expansion (mobile, web, federation, sealed sender) | **Sealed sender done** | | 8 | Freifunk / community mesh networking | **F0-F6 done** | | 9 | Developer experience and community growth | Safety numbers + plugins done | ### Recently completed (Sprints 1-9) - **Rich messaging** — reactions, read receipts, typing indicators, edit/delete messages - **File transfer** — chunked upload/download with SHA-256 content addressing and progress bars - **Disappearing messages** — per-conversation TTL with server-side garbage collection - **Account deletion** — transactional purge of all user data (GDPR-ready) - **Go SDK** — native QUIC + Cap'n Proto client with full API coverage - **TypeScript SDK** — WASM crypto (175 KB) + WebSocket transport + browser demo - **C FFI + Python bindings** — cross-language integration via `libquicproquo_ffi` - **Mesh networking** — self-sovereign identity, store-and-forward, broadcast channels, extended REPL - **Security hardening** — DS sender binding, username enumeration mitigation, MLS key rotation - **CI pipeline** — fmt, build, test, clippy, deny, audit, tarpaulin coverage, Docker build - **Plugin system** — dynamic `.so`/`.dylib` loading with 6 C-compatible hook points --- ## Building without the GUI The GUI crate requires GTK system libraries. To build just the server and client: ```bash cargo build --bin qpq-server --bin qpq ``` To build the client with mesh/P2P support: ```bash cargo build -p quicproquo-client --features mesh ``` --- ## Documentation Full documentation is available as an **mdBook** in [`docs/`](docs/): ```bash cargo install mdbook # once mdbook serve docs # http://localhost:3000 ``` - **[Getting Started](docs/src/getting-started/prerequisites.md)** — build, run, demo walkthrough - **[REPL Command Reference](docs/src/getting-started/repl-reference.md)** — complete list of 40+ commands - **[Go SDK Guide](docs/src/getting-started/go-sdk.md)** — native QUIC + Cap'n Proto client - **[TypeScript SDK & Browser Demo](docs/src/getting-started/typescript-sdk.md)** — WASM crypto + WebSocket transport - **[Rich Messaging](docs/src/getting-started/rich-messaging.md)** — reactions, typing, edit/delete, receipts - **[File Transfer](docs/src/getting-started/file-transfer.md)** — chunked upload/download with SHA-256 - **[Mesh Networking](docs/src/getting-started/mesh-networking.md)** — P2P, broadcast, store-and-forward - **[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 key decisions - **[Wire Format Reference](docs/src/wire-format/overview.md)** — annotated Cap'n Proto schemas - **[Roadmap](docs/src/roadmap/milestones.md)** — milestones, production readiness, future research - **[Future Improvements](docs/FUTURE-IMPROVEMENTS.md)** — prioritised list of security, ops, and feature improvements --- ## Security This is a **research project** and has not undergone a formal third-party audit. See the [threat model](docs/src/cryptography/threat-model.md) and [security audit](docs/SECURITY-AUDIT.md) for details. - The server only routes opaque ciphertexts by recipient key — it never sees plaintext. - OPAQUE ensures passwords never leave the client. - Local databases are encrypted with SQLCipher when a password is provided. - Session tokens are encrypted at rest (Argon2id key derivation + ChaCha20-Poly1305). - **Certificate pinning:** pass the server cert as `--ca-cert` so the client trusts only that server. - **Sealed sender:** optional mode where the server cannot see who sent a message. - **Dependency checks:** CI runs `cargo deny check` and `cargo audit` on every PR. --- ## License MIT