Christian Nennemann
8eba12170e
- Add meshservice to workspace members - Fix quicprochat-client: add MeshTrace/MeshStats slash commands - Add integration test: meshservice_tcp_transport - Document integration points in README and docs/status.md - Verify shared identity (IdentityKeypair → MeshAddress)
277 lines
12 KiB
Markdown
277 lines
12 KiB
Markdown
<p align="center">
|
||
<img src="assets/logo.png" alt="quicprochat" width="160">
|
||
</p>
|
||
|
||
<h1 align="center">quicprochat</h1>
|
||
|
||
<p align="center">
|
||
<strong>End-to-end encrypted group messaging over QUIC, powered by MLS and post-quantum cryptography.</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="docs/src/design-rationale/messenger-comparison.md">Why quicprochat?</a> ·
|
||
<a href="ROADMAP.md">Roadmap</a> ·
|
||
<a href="docs/sdk/index.md">SDK Docs</a> ·
|
||
<a href="docs/operations/monitoring.md">Operations</a> ·
|
||
<a href="#quick-start">Quick Start</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
quicprochat is a production-grade messenger where the server **never sees plaintext**. All traffic flows over QUIC/TLS 1.3, group keys are negotiated with the [MLS protocol](https://www.rfc-editor.org/rfc/rfc9420) (RFC 9420), and a hybrid X25519 + ML-KEM-768 KEM provides post-quantum confidentiality. Written in Rust. 45,000 lines of code. 301 tests.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Application / MLS ciphertext │ ← group key ratchet (RFC 9420)
|
||
├─────────────────────────────────────────────────┤
|
||
│ Protobuf RPC / Cap'n Proto (legacy) │ ← typed, schema-versioned framing
|
||
├─────────────────────────────────────────────────┤
|
||
│ QUIC + TLS 1.3 (quinn/rustls) │ ← mutual auth + transport secrecy
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Highlights
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Zero-knowledge server** | Routes opaque MLS ciphertexts by recipient key — never decrypts |
|
||
| **Post-quantum ready** | Hybrid X25519 + ML-KEM-768 KEM on both MLS and Noise layers |
|
||
| **Password auth** | OPAQUE — password never leaves the client, not even as a hash |
|
||
| **Forward secrecy** | MLS epoch ratchet: compromise today can't decrypt yesterday |
|
||
| **Multi-device** | Per-device keys, delivery fan-out, up to 5 devices per account |
|
||
| **Federation** | Server-to-server relay over QUIC with mTLS |
|
||
| **Offline-first** | Client-side outbox with idempotent retry and gap detection |
|
||
| **Sealed sender** | Optional anonymous enqueue — server can't see who sent a message |
|
||
| **7 SDKs** | Rust, Go, Python, TypeScript, Swift, Kotlin/Java, Ruby |
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Build (no system dependencies — protoc is vendored)
|
||
cargo build --workspace
|
||
|
||
# Run tests
|
||
cargo test --workspace
|
||
|
||
# Start the server (auto-generates self-signed TLS cert)
|
||
cargo run --bin qpc-server -- --allow-insecure-auth
|
||
|
||
# Interactive REPL (registers + logs in automatically)
|
||
cargo run --bin qpc -- repl --username alice --password secret
|
||
```
|
||
|
||
**Two-terminal demo:**
|
||
|
||
```bash
|
||
# Terminal 1 # Terminal 2
|
||
qpc repl -u alice -p secretA qpc repl -u bob -p secretB
|
||
|
||
# Alice: # Bob sees:
|
||
/dm bob [alice] Hello, Bob!
|
||
Hello, Bob!
|
||
```
|
||
|
||
## Architecture
|
||
|
||
```
|
||
quicprochat/
|
||
├── crates/
|
||
│ ├── quicprochat-core # MLS, hybrid KEM, PQ Noise, OPAQUE, recovery, padding
|
||
│ ├── quicprochat-proto # Protobuf (prost) + Cap'n Proto generated types
|
||
│ ├── quicprochat-rpc # QUIC RPC framework (framing, dispatch, middleware)
|
||
│ ├── quicprochat-sdk # Client SDK (QpqClient, conversation store, outbox)
|
||
│ ├── quicprochat-server # QUIC server, 33 RPC methods, domain services, plugins
|
||
│ ├── quicprochat-client # CLI + REPL + TUI (Ratatui)
|
||
│ ├── quicprochat-kt # Key transparency (Merkle-log, revocation)
|
||
│ ├── quicprochat-p2p # iroh P2P, mesh identity, store-and-forward
|
||
│ ├── meshservice # Decentralized service layer (FAPP, housing, wire format)
|
||
│ ├── quicprochat-ffi # C FFI (libquicprochat_ffi.so)
|
||
│ └── quicprochat-plugin-api # Dynamic plugin hooks (C ABI)
|
||
├── proto/qpc/v1/ # 15 .proto schema files
|
||
├── sdks/ # Go, Python, TypeScript, Swift, Kotlin, Java, Ruby
|
||
├── docs/ # mdBook docs, SDK guides, operational runbooks
|
||
└── packaging/ # OpenWrt, Docker, cross-compilation
|
||
```
|
||
|
||
### Security Properties
|
||
|
||
| Property | Mechanism |
|
||
|---|---|
|
||
| Transport confidentiality | TLS 1.3 over QUIC (rustls) |
|
||
| Group key agreement | MLS `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` |
|
||
| Post-quantum confidentiality | X25519 + ML-KEM-768 hybrid KEM (MLS + Noise layers) |
|
||
| Forward secrecy | MLS epoch ratchet + per-epoch key schedule |
|
||
| Post-compromise security | MLS Update proposals rotate leaf material |
|
||
| Identity | Ed25519 long-term keys (MLS credential + leaf signature) |
|
||
| Password authentication | OPAQUE-ke (augmented PAKE, no password on wire) |
|
||
| Local storage | SQLCipher + Argon2id + ChaCha20-Poly1305 |
|
||
| Key transparency | Append-only Merkle log with inclusion proofs + revocation |
|
||
| Traffic analysis resistance | Uniform padding + configurable decoy traffic |
|
||
|
||
## Features
|
||
|
||
### Messaging
|
||
- **1:1 DMs** and **N-party groups** with full MLS lifecycle (add, remove, key rotation)
|
||
- **Rich messaging** — reactions, read receipts, typing indicators, edit, delete
|
||
- **File transfer** — chunked upload/download, SHA-256 content addressing, 50 MB limit
|
||
- **Disappearing messages** — per-conversation TTL with server-side GC
|
||
- **Offline queue** — messages queued locally when disconnected, flushed on reconnect
|
||
- **Delivery proofs** — server-signed Ed25519 receipts for cryptographic send confirmation
|
||
- **Transcript export** — encrypted, tamper-evident archives with Merkle chain verification
|
||
|
||
### Infrastructure
|
||
- **Multi-device** — per-device keys and delivery fan-out (up to 5 devices)
|
||
- **Account recovery** — 8 recovery codes, encrypted bundles, zero-knowledge server
|
||
- **Federation** — server-to-server relay with mTLS and cross-server user resolution
|
||
- **Abuse prevention** — user blocking, message reporting, ban enforcement, admin tools
|
||
- **Graceful shutdown** — SIGTERM drain with configurable timeout, health endpoint awareness
|
||
- **Rate limiting** — sliding window algorithm, trait-based for Redis swap
|
||
- **Observability** — request correlation IDs, per-endpoint latency histograms, structured audit log
|
||
- **Dynamic plugins** — load `.so`/`.dylib` at runtime via `--plugin-dir` (6 hook points)
|
||
- **Mesh networking** — iroh P2P, mDNS discovery, store-and-forward, broadcast channels
|
||
|
||
### Mesh & P2P Features
|
||
|
||
The `quicprochat-p2p` crate provides a full **serverless mesh networking stack**:
|
||
|
||
| Feature | Module | Description |
|
||
|---------|--------|-------------|
|
||
| **P2P Transport** | `P2pNode` | Direct QUIC connections via iroh with NAT traversal |
|
||
| **Mesh Identity** | `MeshIdentity` | Ed25519 keypairs with 16-byte truncated addresses |
|
||
| **Mesh Envelope** | `MeshEnvelope` | Encrypted, signed, TTL-aware message containers |
|
||
| **Store-and-Forward** | `MeshStore` | Queue messages for offline recipients |
|
||
| **Multi-Hop Routing** | `MeshRouter` | Distributed routing table, forward through intermediaries |
|
||
| **Announce Protocol** | `MeshAnnounce` | Signed peer discovery with capability flags |
|
||
| **Broadcast Channels** | `BroadcastManager` | Pub/sub with symmetric key encryption |
|
||
| **Transport Abstraction** | `TransportManager` | Iroh, TCP, LoRa — route by address type |
|
||
| **LoRa Transport** | `transport_lora` | Duty-cycle aware, fragmentation, SF12 support |
|
||
| **MLS-Lite** | `mls_lite` | Lightweight symmetric mode for constrained links |
|
||
| **FAPP** | `fapp` + `fapp_router` | Free Appointment Propagation Protocol (see below) |
|
||
|
||
#### FAPP — Decentralized Appointment Discovery
|
||
|
||
**Problem:** In Germany, finding a psychotherapist takes 3–6 months due to artificial slot visibility limits.
|
||
|
||
**Solution:** FAPP lets licensed therapists announce free slots into the mesh. Patients discover and reserve slots anonymously — no central registry.
|
||
|
||
```rust
|
||
// Therapist publishes slots
|
||
let announce = SlotAnnounce::new(
|
||
&therapist_identity,
|
||
vec![Fachrichtung::Verhaltenstherapie],
|
||
vec![Modalitaet::Praxis, Modalitaet::Video],
|
||
vec![Kostentraeger::GKV],
|
||
"80331", // PLZ only, never exact address
|
||
slots,
|
||
approbation_hash,
|
||
sequence,
|
||
);
|
||
fapp_router.broadcast_announce(announce)?;
|
||
|
||
// Patient queries anonymously
|
||
let query = SlotQuery {
|
||
fachrichtung: Some(Fachrichtung::Verhaltenstherapie),
|
||
plz_prefix: Some("803".into()),
|
||
kostentraeger: Some(Kostentraeger::GKV),
|
||
..Default::default()
|
||
};
|
||
fapp_router.send_query(query)?;
|
||
```
|
||
|
||
**Privacy model:**
|
||
- Therapist identity is **public** (bound to Approbation hash)
|
||
- Patient queries are **anonymous** (no identifying information)
|
||
- Reservations use **E2E encryption** to therapist's key
|
||
|
||
See [`docs/specs/fapp-protocol.md`](docs/specs/fapp-protocol.md) for the full protocol spec.
|
||
|
||
### Client SDKs
|
||
|
||
| Language | Location | Transport | Notes |
|
||
|---|---|---|---|
|
||
| **Rust** | `crates/quicprochat-sdk` | QUIC (quinn) | Reference implementation |
|
||
| **Go** | `sdks/go/` | QUIC (quic-go) | Cap'n Proto RPC, full API |
|
||
| **Python** | `sdks/python/` | QUIC (aioquic) + FFI | Async client, PyPI-ready |
|
||
| **TypeScript** | `sdks/typescript/` | WebSocket + WASM crypto | 175 KB WASM bundle, browser demo |
|
||
| **Swift** | `sdks/swift/` | C FFI wrapper | iOS 15+ / macOS 13+ |
|
||
| **Kotlin/Java** | `sdks/kotlin/`, `sdks/java/` | JNI + C FFI | Android + JVM |
|
||
| **Ruby** | `sdks/ruby/` | C FFI gem | Block-form auto-disconnect |
|
||
|
||
### REPL Commands
|
||
|
||
40+ slash commands including:
|
||
|
||
```
|
||
/dm <user> Start a 1:1 DM
|
||
/create-group <name> Create a group
|
||
/invite <user> Add member to group
|
||
/remove <user> Remove member
|
||
/send-file <path> Upload and send a file
|
||
/verify <user> Compare safety numbers
|
||
/rotate-keys Rotate MLS key material
|
||
/disappear <duration> Set message TTL
|
||
/export <path> Export encrypted transcript
|
||
/devices list|add|rm Manage devices
|
||
/block <user> Block a user
|
||
/recovery setup Generate recovery codes
|
||
/help Full command reference
|
||
```
|
||
|
||
## Deployment
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
docker build -t quicprochat -f docker/Dockerfile .
|
||
docker run -p 7000:7000 -v qpc-data:/data quicprochat
|
||
```
|
||
|
||
### Production (Docker Compose)
|
||
|
||
```bash
|
||
# Includes server + Prometheus + Grafana with pre-configured dashboards
|
||
docker compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
### OpenWrt
|
||
|
||
Cross-compiled static binaries for mesh/embedded deployments:
|
||
|
||
```bash
|
||
./scripts/cross-compile.sh # builds for x86_64, armv7, aarch64 (musl)
|
||
```
|
||
|
||
See [docs/openwrt.md](docs/openwrt.md) for `opkg` packaging and `procd` init scripts.
|
||
|
||
### Configuration
|
||
|
||
```bash
|
||
# Environment variables (see .env.example for full list)
|
||
QPC_LISTEN=0.0.0.0:7000
|
||
QPC_AUTH_TOKEN=your-strong-token
|
||
QPC_DB_KEY=your-db-encryption-key
|
||
QPC_STORE_BACKEND=sql
|
||
QPC_METRICS_LISTEN=0.0.0.0:9090
|
||
QPC_DRAIN_TIMEOUT=30
|
||
QPC_RPC_TIMEOUT=30
|
||
```
|
||
|
||
## Documentation
|
||
|
||
```bash
|
||
mdbook serve docs # http://localhost:3000
|
||
```
|
||
|
||
- [SDK Integration Guide](docs/sdk/index.md) — wire format, per-language guides, "build your own SDK"
|
||
- [Operational Runbook](docs/operations/backup-restore.md) — backup/restore, key rotation, incident response
|
||
- [Scaling Guide](docs/operations/scaling-guide.md) — resource sizing, horizontal scaling, capacity planning
|
||
- [Monitoring](docs/operations/monitoring.md) — Prometheus metrics, Grafana dashboards, alert rules
|
||
|
||
## Security Status
|
||
|
||
> **This software has not undergone an independent security audit.** While it implements cryptographic best practices (MLS RFC 9420, OPAQUE, zeroization, constant-time comparisons), no third-party firm has reviewed the implementation. Do not rely on it for high-risk communications until an audit is completed. See [SECURITY.md](SECURITY.md) for our vulnerability disclosure policy.
|
||
|
||
## License
|
||
|
||
MIT
|