QPQ — quicproquo

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 <username> 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 <username>	Start a 1:1 DM with a peer
/create-group <name> (or /cg)	Create a new group
/invite <username>	Add a member to the current group
/remove <username>	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 <name>	Rename the current conversation
/history [count] (or /hist)	Show message history (default 20)
/react <emoji> [index]	React to a message with an emoji
/typing	Send a typing indicator
/typing-notify on|off	Toggle typing indicator display
/edit <index> <text>	Edit one of your messages
/delete <index>	Delete one of your messages
/send-file <path> (or /sf)	Upload and send a file (chunked, SHA-256 verified)
/download <index> (or /dl)	Download a received file
/disappear <duration>	Set message TTL (30m, 1h, 1d, 7d)
/verify <username>	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 <host:port>	Note a discovered server address
/mesh send <peer_id> <msg>	Direct P2P message via iroh
/mesh broadcast <topic> <msg>	Publish to a broadcast channel
/mesh subscribe <topic>	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

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

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

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

cargo build --bin qpq-server --bin qpq

To build the client with mesh/P2P support:

cargo build -p quicproquo-client --features mesh

---

Documentation

Full documentation is available as an mdBook in docs/:

cargo install mdbook     # once
mdbook serve docs        # http://localhost:3000

• Getting Started — build, run, demo walkthrough
• REPL Command Reference — complete list of 40+ commands
• Go SDK Guide — native QUIC + Cap'n Proto client
• TypeScript SDK & Browser Demo — WASM crypto + WebSocket transport
• Rich Messaging — reactions, typing, edit/delete, receipts
• File Transfer — chunked upload/download with SHA-256
• Mesh Networking — P2P, broadcast, store-and-forward
• Architecture Overview — two-service model, dual-key design, crate layout
• Protocol Deep Dives — QUIC/TLS 1.3, Cap'n Proto, MLS, Hybrid KEM
• Cryptographic Properties — forward secrecy, post-compromise security, PQ readiness, threat model
• Design Rationale — why MLS over Signal/Matrix, ADRs for key decisions
• Wire Format Reference — annotated Cap'n Proto schemas
• Roadmap — milestones, production readiness, future research
• Future Improvements — 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 and security audit 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