diff --git a/README.md b/README.md index 24f5776..ee82830 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,16 @@ -# quicproquo +

+ QPQ logo +

-> End-to-end encrypted group messaging over **QUIC + TLS 1.3 + MLS** (RFC 9420), written in Rust. +# QPQ — quicproquo -Every byte on the wire is protected by a QUIC transport secured with TLS 1.3 -(`quinn` + `rustls`). The inner **MLS** layer provides post-compromise security -and ratcheted group key agreement across any number of participants. Messages -are framed with **Cap'n Proto**, keeping serialisation zero-copy and -schema-versioned. +> 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. ``` ┌─────────────────────────────────────────────┐ @@ -21,37 +25,53 @@ schema-versioned. | Property | Mechanism | |---|---| | Transport confidentiality | TLS 1.3 over QUIC (rustls) | -| Transport authentication | TLS 1.3 server cert (self-signed by default) | +| 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) | --- -## Documentation +## Features -Full documentation is available as an **mdBook** wiki in [`docs/`](docs/): +### Working -```bash -# Install mdBook (once) -cargo install mdbook +- **Interactive REPL** — multi-conversation chat with auto-register, auto-login, 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 +- **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 +- **18 CLI subcommands** — `register-user`, `login`, `create-group`, `invite`, `join`, `send`, `recv`, `chat`, `repl`, and more -# Build and serve locally -mdbook serve docs -# Open http://localhost:3000 -``` +### REPL slash commands -### Highlights +| Command | Description | +|---|---| +| `/dm ` | Start a 1:1 DM with a peer | +| `/create-group ` | Create a new group | +| `/invite ` | Add a member to the current group | +| `/join` | Join a pending group invitation | +| `/switch @user` or `/switch #group` | Switch active conversation | +| `/list` or `/ls` | List all conversations | +| `/members` | Show group members | +| `/history [count]` | Show message history (default 20) | +| `/whoami` | Show identity and group status | +| `/help` | Command reference | +| `/quit` | Exit | -- **[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 all 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, reliability, and feature improvements +### 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 (excluded from default build) --- @@ -62,80 +82,157 @@ mdbook serve docs brew install capnp # macOS # apt-get install capnproto # Debian/Ubuntu -# GUI prerequisites (Linux only) — WebKitGTK + GTK3 for Tauri 2 -# sudo apt install -y libwebkit2gtk-4.1-dev libgtk-3-dev libglib2.0-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf - # Build and test cargo build --workspace cargo test --workspace # Start the server (port 7000 by default) -cargo run -p quicproquo-server +cargo run --bin qpq-server -# Or via a config file (TOML) -# Note: auth_token = "devtoken" and db_key = "" are for development only. -# Production: set QPQ_AUTH_TOKEN to a strong secret and (when store_backend = "sql") -# set QPQ_DB_KEY so the database is encrypted. Empty db_key = plaintext DB (insecure). +# Run the two-party demo +cargo run --bin qpq -- demo-group --server 127.0.0.1:7000 + +# 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 = "devtoken" -store_backend = "file" # or "sql" +store_backend = "sql" # or "file" db_path = "data/qpq.db" -db_key = "" +db_key = "" # set for SQLCipher encryption EOF -cargo run -p quicproquo-server -- --config qpq-server.toml - -# Run the two-party demo -cargo run -p quicproquo-client -- demo-group \ - --server 127.0.0.1:7000 - -# Interactive 1:1 chat (after creating a group and inviting a peer) -# Terminal 1: qpq chat --peer-key -# Terminal 2: qpq chat --peer-key -# Type messages and press Enter; incoming messages appear as [peer] . Ctrl+D to exit. +cargo run --bin qpq-server -- --config qpq-server.toml ``` +> **Production:** set `QPQ_PRODUCTION=1`, use a strong `QPQ_AUTH_TOKEN` (not `devtoken`), and set `QPQ_DB_KEY` when using `store_backend = "sql"`. + 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 | +| `quicproquo-proto` | Cap'n Proto schemas and generated RPC code | +| `quicproquo-server` | QUIC server, NodeService RPC, storage backends | +| `quicproquo-client` | CLI + REPL, session management, conversation store | +| `quicproquo-gui` | Tauri 2 desktop app (experimental) | +| `quicproquo-mobile` | C FFI for mobile connection migration (experimental) | +| `quicproquo-p2p` | iroh-based P2P transport (experimental, excluded from workspace) | + +--- + ## 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 (`create-group`, `invite`, `join`, `send`, `recv`), OPAQUE login | -| M5 | Multi-party groups | Done | N > 2 members, Commit fan-out, send --all, epoch sync | -| M6 | Persistence | Done | SQLite/SQLCipher, migrations, durable server + client state | -| M7 | Post-quantum | Next | PQ hybrid for MLS/HPKE (X25519 + ML-KEM-768) | +| 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, 18 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 | **Next** | 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 + +### Next up + +- **Post-quantum MLS integration** (M7) — hybrid KEM into the MLS key schedule +- **Full MLS lifecycle** — member removal, credential updates, proposal handling +- **CI pipeline** — GitHub Actions (test, clippy, fmt, audit) +- **Accounts & devices model** — per-account rate limits, multi-device support +- **Client offline queue** — idempotent message IDs, gap detection, retry + +### Planned + +- Server-to-server federation (mTLS relay, in progress) +- CA-signed TLS / Let's Encrypt support +- HTTP health endpoint for load balancers +- Connection draining and graceful shutdown +- Wire versioning and N-1 compatibility + +### Research + +- Sealed sender (metadata resistance) — foundation exists +- Traffic analysis resistance (padding + shaping) +- P2P / NAT traversal via iroh — crate started +- WebTransport for browser clients +- Tor / I2P routing +- Private information retrieval for message fetch --- ## Building without the GUI -To build only the server and CLI client (faster, no Tauri/WebKit): - ```bash -cargo build -p quicproquo-server -p quicproquo-client +cargo build --bin qpq-server --bin qpq ``` -Core and proto crates are built as dependencies. Omit `quicproquo-gui` and `quicproquo-p2p` if you don't need them. +Core and proto crates are built as dependencies automatically. --- -## Security notes +## Documentation -This is a **proof-of-concept research project**. It has not undergone a formal third-party audit. See the [threat model](docs/src/cryptography/threat-model.md) for what is and isn't protected, and the [security audit](docs/SECURITY-AUDIT.md) for an internal review of authentication, crypto, transport, and authorization. +Full documentation is available as an **mdBook** in [`docs/`](docs/): -- **Dependency checks:** Run `cargo install cargo-audit && cargo audit` to check for known vulnerabilities. -- **Certificate pinning:** Use the server's certificate as `--ca-cert` (e.g. copy `server-cert.der` from the server) so the client only trusts that server; see [Certificate pinning](docs/SECURITY-AUDIT.md#certificate-pinning) in the security audit. +```bash +cargo install mdbook # once +mdbook serve docs # http://localhost:3000 +``` -**Production deployment:** Set `QPQ_PRODUCTION=1` and provide a strong `QPQ_AUTH_TOKEN` (not `devtoken`). When using `store_backend = "sql"`, set `QPQ_DB_KEY`; an empty key leaves the database unencrypted on disk. +- **[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 + +--- + +## 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. +- **Dependency checks:** `cargo install cargo-audit && cargo audit` --- diff --git a/assets/logo.png b/assets/logo.png new file mode 100644 index 0000000..b7bb827 Binary files /dev/null and b/assets/logo.png differ