c/quicproquo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive update for sprints 1-9

Browse Source 
Update README, ROADMAP, and mdBook to reflect all sprint deliverables:
rich messaging, file transfer, disappearing messages, Go/TypeScript SDKs,
C FFI, mesh networking (identity, store-and-forward, broadcast), and
security hardening. Add 6 new mdBook guides (REPL reference, Go SDK,
TypeScript SDK + browser demo, rich messaging, file transfer, mesh
networking). Check off 16 completed ROADMAP items across phases 3-9.
This commit is contained in:
Christian Nennemann
2026-03-04 02:10:20 +01:00
parent 4454458e38
commit 4694a3098b
13 changed files with 1084 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@@ -4,7 +4,7 @@
# QPQ — quicproquo
[![CI](https://github.com/nickvidal/quicproquo/actions/workflows/ci.yml/badge.svg)](https://github.com/nickvidal/quicproquo/actions/workflows/ci.yml)
[![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 messaging over **QUIC + TLS 1.3 + MLS** (RFC 9420), written in Rust.
@@ -43,12 +43,16 @@ agreement across any number of participants. Messages are framed with
### Core
- **Interactive REPL** — multi-conversation chat with auto-register, auto-login, slash commands, background polling, and message history
- **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
@@ -58,7 +62,14 @@ agreement across any number of participants. Messages are framed with
- **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
- **20 CLI subcommands** — `register-user`, `login`, `create-group`, `invite`, `join`, `send`, `recv`, `chat`, `repl`, `export`, `export-verify`, and more
- **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
@@ -72,21 +83,51 @@ agreement across any number of participants. Messages are framed with
| `/leave` | Leave the current group |
| `/switch @user` or `/switch #group` | Switch active conversation |
| `/list` or `/ls` | List all conversations |
| `/members` | Show group members |
| `/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 |
| `/mesh peers` | Scan for nearby qpq nodes via mDNS |
| `/mesh server <host:port>` | Note a discovered server address |
| `/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)
- **P2P transport** (`quicproquo-p2p`) — iroh-based direct peer-to-peer messaging with NAT traversal (feature-gated behind `--features mesh`)
- **Bot framework** (`quicproquo-bot`) — programmable bot client
---
@@ -161,17 +202,18 @@ See the [full demo walkthrough](docs/src/getting-started/demo-walkthrough.md) fo
| Crate | Purpose |
|---|---|
| `quicproquo-core` | MLS group operations, hybrid KEM, OPAQUE auth, crypto primitives |
| `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, storage backends, federation, plugins |
| `quicproquo-client` | CLI + REPL, session management, conversation store |
| `quicproquo-plugin-api` | C-compatible plugin hook API (`HookVTable`) |
| `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 (feature-gated, `--features mesh`) |
| `quicproquo-p2p` | iroh-based P2P transport, mesh identity, store-and-forward, broadcast channels |
---
@@ -181,7 +223,7 @@ GitHub Actions runs on every push and PR:
- `cargo fmt --check` — formatting
- `cargo build --workspace` — full build
- `cargo test --workspace` — 103+ tests (core, server, client, E2E, doctests)
- `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
@@ -214,23 +256,27 @@ See [ROADMAP.md](ROADMAP.md) for the full phased plan. Summary:
|-------|-------|--------|
| 1 | Production hardening (unwrap removal, secure defaults, Docker) | In progress |
| 2 | Test and CI maturity | Partially done |
| 3 | Client SDKs (Go, Python, WASM, FFI, WebTransport) | Planned |
| 4 | Trust and security (audit, key transparency, PQ MLS) | Planned |
| 5 | Features and UX (multi-device, offline queue, file transfer) | Planned |
| 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) | Planned |
| 8 | Freifunk / community mesh networking | F0-F2 done |
| 9 | Developer experience and community growth | 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
### Recently completed (Sprints 1-9)
- **Federation routing** — server-to-server message relay with mTLS
- **mDNS discovery** — servers advertise on local network, clients discover peers
- **P2P transport** — iroh-based direct messaging re-included in workspace (`--features mesh`)
- **CI pipeline** — fmt, build, test, clippy, deny, audit, coverage, Docker build
- **Plugin system** — dynamic `.so`/`.dylib` loading with C-compatible hook API
- **Safety numbers** — Signal-style 60-digit verification codes
- **Transcript export** — encrypted, hash-chained message archives
- **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
---
@@ -259,12 +305,18 @@ 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
- **[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, and feature improvements