<p align="center">
  <img src="assets/logo.png" alt="QPQ logo" width="200">
</p>

# QPQ — 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 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

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

### 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 = "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](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:

```bash
cargo build --bin qpq-server --bin qpq
```

To build the client with mesh/P2P support:

```bash
cargo build -p quicproquo-client --features mesh
```

---

## Documentation

Full documentation is available as an **mdBook** in [`docs/`](docs/):

```bash
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
- **[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.
- **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
