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

feat: Sprint 3 — C FFI bindings, WASM compilation, Python example, SDK docs

Browse Source 
- Create quicproquo-ffi crate with 7 extern "C" functions: connect,
  login, send, receive, disconnect, last_error, free_string
  (produces libquicproquo_ffi.so and .a)
- Feature-gate quicproquo-core for WASM: identity, hybrid_kem,
  safety_numbers, sealed_sender, app_message, padding, transcript
  all compile to wasm32-unknown-unknown
- Add Python ctypes example (examples/python/qpq_client.py) with
  QpqClient wrapper class and CLI
- Add SDK documentation: FFI reference, WASM guide, qpq-gen generators
- Update Dockerfile for quicproquo-ffi workspace member
This commit is contained in:
Chris Nennemann
2026-03-03 23:47:40 +01:00
parent 9ab306d891
commit db46b72f58
16 changed files with 1402 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
README.md
View File

@@ -41,7 +41,7 @@ agreement across any number of participants. Messages are framed with
## Features
### Working
### Core
- **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
@@ -51,20 +51,33 @@ agreement across any number of participants. Messages are framed with
- **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
- **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
- **20 CLI subcommands** — `register-user`, `login`, `create-group`, `invite`, `join`, `send`, `recv`, `chat`, `repl`, `export`, `export-verify`, and more
### REPL slash commands
| Command | Description |
|---|---|
| `/dm <username>` | Start a 1:1 DM with a peer |
| `/create-group <name>` | Create a new group |
| `/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 |
| `/history [count]` | Show message history (default 20) |
| `/history [count]` (or `/hist`) | Show message history (default 20) |
| `/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 |
| `/whoami` | Show identity and group status |
| `/help` | Command reference |
| `/quit` | Exit |
@@ -73,7 +86,8 @@ agreement across any number of participants. Messages are framed with
- **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)
- **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
---
@@ -84,15 +98,14 @@ agreement across any number of participants. Messages are framed with
brew install capnp # macOS
# apt-get install capnproto # Debian/Ubuntu
# Build and test
cargo build --workspace
cargo test --workspace
# Build (excludes GUI — requires GTK system libs)
cargo build --bin qpq-server --bin qpq
# Start the server (port 7000 by default)
cargo run --bin qpq-server
# Run tests
cargo test --workspace --exclude quicproquo-gui
# Run the two-party demo
cargo run --bin qpq -- demo-group --server 127.0.0.1:7000
# 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
@@ -122,15 +135,23 @@ listen = "0.0.0.0:7000"
data_dir = "data"
tls_cert = "data/server-cert.der"
tls_key = "data/server-key.der"
auth_token = "devtoken"
auth_token = "your-strong-token-here"
store_backend = "sql" # or "file"
db_path = "data/qpq.db"
db_key = "" # set for SQLCipher encryption
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:** set `QPQ_PRODUCTION=1`, use a strong `QPQ_AUTH_TOKEN` (not `devtoken`), and set `QPQ_DB_KEY` when using `store_backend = "sql"`.
> **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.
@@ -142,11 +163,30 @@ See the [full demo walkthrough](docs/src/getting-started/demo-walkthrough.md) fo
|---|---|
| `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-server` | QUIC server, NodeService RPC, storage backends, federation, plugins |
| `quicproquo-client` | CLI + REPL, session management, conversation store |
| `quicproquo-gui` | Tauri 2 desktop app (experimental) |
| `quicproquo-plugin-api` | C-compatible plugin hook API (`HookVTable`) |
| `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 (experimental, excluded from workspace) |
| `quicproquo-p2p` | iroh-based P2P transport (feature-gated, `--features mesh`) |
---
## CI pipeline
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 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
---
@@ -157,10 +197,10 @@ See the [full demo walkthrough](docs/src/getting-started/demo-walkthrough.md) fo
| 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 |
| 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 | **Next** | Hybrid X25519 + ML-KEM-768 integrated into MLS ciphersuite |
| 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.
@@ -168,40 +208,45 @@ M7 note: the hybrid KEM envelope is already implemented and tested (10 tests pas
## Roadmap
### Next up
See [ROADMAP.md](ROADMAP.md) for the full phased plan. Summary:
- **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
| Phase | Focus | Status |
|-------|-------|--------|
| 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 |
| 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 |
### Planned
### Recently completed
- 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
- **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
---
## 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
```
Core and proto crates are built as dependencies automatically.
To build the client with mesh/P2P support:
```bash
cargo build -p quicproquo-client --features mesh
```
---
@@ -234,7 +279,8 @@ This is a **research project** and has not undergone a formal third-party audit.
- 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`
- **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.
---