From 189534c51127b18d00380b401d052593e6188f1b Mon Sep 17 00:00:00 2001 From: Christian Nennemann Date: Wed, 4 Mar 2026 21:36:42 +0100 Subject: [PATCH] docs: rewrite README as professional project overview Replace outdated milestone-tracking README with a polished project overview: centered header, highlights table, quick-start demo, architecture tree, security properties, feature matrix, SDK comparison, deployment guides, and configuration reference. --- README.md | 464 ++++++++++++++++++++---------------------------------- 1 file changed, 172 insertions(+), 292 deletions(-) diff --git a/README.md b/README.md index 42aa0d3..77d529e 100644 --- a/README.md +++ b/README.md @@ -1,340 +1,220 @@

- QPQ logo + quicproquo

-# QPQ — quicproquo +

quicproquo

-[![CI](https://github.com/xorwell/quicproquo/actions/workflows/ci.yml/badge.svg)](https://github.com/xorwell/quicproquo/actions/workflows/ci.yml) +

+ End-to-end encrypted group messaging over QUIC, powered by MLS and post-quantum cryptography. +

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

+ Roadmap · + SDK Docs · + Operations · + Quick Start +

--- +quicproquo 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 qpq-server -- --allow-insecure-auth + +# Interactive REPL (registers + logs in automatically) +cargo run --bin qpq -- repl --username alice --password secret +``` + +**Two-terminal demo:** + +```bash +# Terminal 1 # Terminal 2 +qpq repl -u alice -p secretA qpq repl -u bob -p secretB + +# Alice: # Bob sees: +/dm bob [alice] Hello, Bob! +Hello, Bob! +``` + +## Architecture + +``` +quicproquo/ +├── crates/ +│ ├── quicproquo-core # MLS, hybrid KEM, PQ Noise, OPAQUE, recovery, padding +│ ├── quicproquo-proto # Protobuf (prost) + Cap'n Proto generated types +│ ├── quicproquo-rpc # QUIC RPC framework (framing, dispatch, middleware) +│ ├── quicproquo-sdk # Client SDK (QpqClient, conversation store, outbox) +│ ├── quicproquo-server # QUIC server, 33 RPC methods, domain services, plugins +│ ├── quicproquo-client # CLI + REPL + TUI (Ratatui) +│ ├── quicproquo-kt # Key transparency (Merkle-log, revocation) +│ ├── quicproquo-p2p # iroh P2P, mesh identity, store-and-forward +│ ├── quicproquo-ffi # C FFI (libquicproquo_ffi.so) +│ └── quicproquo-plugin-api # Dynamic plugin hooks (C ABI) +├── proto/qpq/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 -### Core +### 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 -- **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 +### 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 ### 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 +| Language | Location | Transport | Notes | +|---|---|---|---| +| **Rust** | `crates/quicproquo-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 slash commands +### REPL 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 | +40+ slash commands including: -**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 +``` +/dm Start a 1:1 DM +/create-group Create a group +/invite Add member to group +/remove Remove member +/send-file Upload and send a file +/verify Compare safety numbers +/rotate-keys Rotate MLS key material +/disappear Set message TTL +/export Export encrypted transcript +/devices list|add|rm Manage devices +/block Block a user +/recovery setup Generate recovery codes +/help Full command reference ``` -### REPL quickstart (two terminals) +## Deployment + +### Docker ```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! +docker build -t quicproquo -f docker/Dockerfile . +docker run -p 7000:7000 -v qpq-data:/data quicproquo ``` -### Server configuration (TOML) +### Production (Docker Compose) ```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 +# Includes server + Prometheus + Grafana with pre-configured dashboards +docker compose -f docker-compose.prod.yml up -d ``` -> **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). +### OpenWrt -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: +Cross-compiled static binaries for mesh/embedded deployments: ```bash -cargo build --bin qpq-server --bin qpq +./scripts/cross-compile.sh # builds for x86_64, armv7, aarch64 (musl) ``` -To build the client with mesh/P2P support: +See [docs/openwrt.md](docs/openwrt.md) for `opkg` packaging and `procd` init scripts. + +### Configuration ```bash -cargo build -p quicproquo-client --features mesh +# Environment variables (see .env.example for full list) +QPQ_LISTEN=0.0.0.0:7000 +QPQ_AUTH_TOKEN=your-strong-token +QPQ_DB_KEY=your-db-encryption-key +QPQ_STORE_BACKEND=sql +QPQ_METRICS_LISTEN=0.0.0.0:9090 +QPQ_DRAIN_TIMEOUT=30 +QPQ_RPC_TIMEOUT=30 ``` ---- - ## Documentation -Full documentation is available as an **mdBook** in [`docs/`](docs/): - ```bash -cargo install mdbook # once -mdbook serve docs # http://localhost:3000 +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 - ---- +- [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 -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. +This project has **not undergone a formal third-party audit**. See the [threat model](docs/src/cryptography/threat-model.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. - ---- +If you discover a security vulnerability, please report it privately. ## License