docs: rewrite mdBook documentation for v2 architecture
Update 25+ files and add 6 new pages to reflect the v2 migration from Cap'n Proto to Protobuf framing over QUIC. Integrates SDK and Operations docs into the mdBook, restructures SUMMARY.md, and rewrites the wire format, architecture, and protocol sections with accurate v2 content.
This commit is contained in:
@@ -12,24 +12,6 @@ For the production readiness work breakdown, see
|
||||
|
||||
## Transport and Networking
|
||||
|
||||
### LibP2P / iroh (n0)
|
||||
|
||||
**Problem:** The current architecture is strictly client-server. Clients behind
|
||||
NAT cannot communicate directly, and the server is a single point of failure for
|
||||
delivery.
|
||||
|
||||
**Solution:** [LibP2P](https://libp2p.io/) and [iroh](https://iroh.computer/)
|
||||
(from n0) provide peer discovery, NAT traversal (hole-punching), and relay
|
||||
fallback. iroh is particularly interesting because it is Rust-native and built on
|
||||
QUIC, aligning with quicproquo's existing transport layer.
|
||||
|
||||
**Architecture impact:** Move from pure client-server to a hybrid topology where
|
||||
peers communicate directly when possible and fall back to server relay when NAT
|
||||
traversal fails. The server role shifts from mandatory relay to optional
|
||||
rendezvous/relay node.
|
||||
|
||||
**Crates:** `libp2p`, `iroh`, `iroh-net`
|
||||
|
||||
### WebTransport (HTTP/3)
|
||||
|
||||
**Problem:** Browser clients cannot use raw QUIC. The current stack requires a
|
||||
@@ -66,23 +48,6 @@ significantly, so this should be optional.
|
||||
|
||||
## Storage and Persistence
|
||||
|
||||
### SQLCipher / libsql (Turso)
|
||||
|
||||
**Problem:** At M6, quicproquo needs persistent storage for group state, key
|
||||
material, and message queues. Storing private keys in a plaintext SQLite database
|
||||
is insufficient.
|
||||
|
||||
**Solution:** [SQLCipher](https://www.zetetic.net/sqlcipher/) provides
|
||||
transparent, page-level AES-256 encryption for SQLite. Alternatively,
|
||||
[libsql](https://turso.tech/libsql) (Turso) offers a SQLite fork with
|
||||
encryption, replication, and embedded server capabilities.
|
||||
|
||||
**Architecture impact:** Replace the `sqlx` SQLite backend with SQLCipher.
|
||||
Encryption key derived from a user-provided passphrase (via Argon2id) or a
|
||||
hardware-backed key.
|
||||
|
||||
**Crates:** `rusqlite` (with `bundled-sqlcipher` feature), `libsql`
|
||||
|
||||
### CRDTs (Automerge / Yrs)
|
||||
|
||||
**Problem:** Multi-device support requires synchronising state (group membership,
|
||||
@@ -153,20 +118,6 @@ queries. This is a significant performance trade-off: PIR has high computational
|
||||
cost. Suitable for KeyPackage fetch (small database) before message fetch (large
|
||||
database).
|
||||
|
||||
### Sealed Sender (Signal-style)
|
||||
|
||||
**Problem:** The server sees `(sender, recipient, timestamp)` metadata on every
|
||||
enqueued message. Even without reading content, this metadata reveals social
|
||||
graphs.
|
||||
|
||||
**Solution:** [Sealed Sender](https://signal.org/blog/sealed-sender/) encrypts
|
||||
the sender's identity inside the MLS ciphertext. The server routes by
|
||||
`recipientKey` only and cannot determine who sent the message.
|
||||
|
||||
**Architecture impact:** Modify the `enqueue` RPC to omit sender identity from
|
||||
the server-visible metadata. The sender identity is included only inside the
|
||||
MLS application message (encrypted).
|
||||
|
||||
### Key Transparency (RFC draft)
|
||||
|
||||
**Problem:** A compromised server could substitute public keys, performing a
|
||||
@@ -200,24 +151,6 @@ DID URIs. The server resolves DIDs to public keys for routing.
|
||||
|
||||
**Crates:** `did-key`, `ssi`
|
||||
|
||||
### OPAQUE (aPAKE)
|
||||
|
||||
**Problem:** If quicproquo adds password-based account registration, the
|
||||
server must never see the password -- not even a hash.
|
||||
|
||||
**Solution:** [OPAQUE](https://datatracker.ietf.org/doc/rfc9497/) is an
|
||||
asymmetric password-authenticated key exchange where the server stores only a
|
||||
one-way transformation of the password. The server cannot perform offline
|
||||
dictionary attacks.
|
||||
|
||||
**Architecture impact:** Replace the registration/login flow with OPAQUE. The
|
||||
server stores an OPAQUE registration record; the client runs the OPAQUE protocol
|
||||
to authenticate and derive a session key.
|
||||
|
||||
**Crates:** `opaque-ke`
|
||||
|
||||
**References:** RFC 9497
|
||||
|
||||
### WebAuthn / Passkeys
|
||||
|
||||
**Problem:** Password-based auth (even with OPAQUE) is vulnerable to phishing.
|
||||
@@ -380,18 +313,25 @@ command sets up the toolchain, `capnp`, and all dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Top 5 Priority Implementations
|
||||
## Top Priority Implementations
|
||||
|
||||
The following table ranks the most impactful technologies for near-term adoption,
|
||||
considering the current state of the codebase and the [milestone plan](milestones.md).
|
||||
|
||||
| Priority | Technology | Why | Unlocks |
|
||||
|----------|-----------|-----|---------|
|
||||
| 1 | **Post-quantum hybrid KEM** | `ml-kem` is already vendored in the workspace. Completing the hybrid `OpenMlsCryptoProvider` makes quicproquo one of the first PQ MLS implementations. | M7 |
|
||||
| 2 | **SQLCipher persistence** | Encrypted-at-rest storage is the prerequisite for multi-device support, offline usage, and server restart survival. | M6 |
|
||||
| 3 | **OPAQUE auth** | Zero-knowledge password authentication is a massive security uplift for the account system. The server never sees or stores passwords. | Phase 3 (authz) |
|
||||
| 4 | **iroh / LibP2P** | NAT traversal and optional P2P mesh makes quicproquo deployable without centralised infrastructure. Aligns with the existing QUIC transport. | Beyond M7 |
|
||||
| 5 | **Sealed Sender + PIR** | Content encryption is table stakes. Metadata resistance (hiding who talks to whom) is the frontier of private messaging research. | Beyond M7 |
|
||||
Items marked **Implemented** are already part of the v2 codebase.
|
||||
|
||||
| Priority | Technology | Why | Status |
|
||||
|----------|-----------|-----|--------|
|
||||
| -- | **Post-quantum hybrid KEM** | `ml-kem` vendored; custom `OpenMlsCryptoProvider` with X25519 + ML-KEM-768. | **Implemented** |
|
||||
| -- | **SQLCipher persistence** | Encrypted-at-rest storage via rusqlite + bundled-sqlcipher + Argon2id key derivation. | **Implemented** |
|
||||
| -- | **OPAQUE auth** | Zero-knowledge password authentication via `opaque-ke`. Server never stores passwords. | **Implemented** |
|
||||
| -- | **iroh P2P** | NAT traversal and optional P2P mesh via the `quicproquo-p2p` crate (feature-flagged). | **Implemented** |
|
||||
| -- | **Sealed Sender** | `--sealed-sender` flag encrypts sender identity inside MLS ciphertext. | **Implemented** |
|
||||
| 1 | **PIR (Private Information Retrieval)** | Fetch messages without revealing the recipient's identity to the server. | Future |
|
||||
| 2 | **Key Transparency** | Verifiable, append-only log of public key bindings. Detects key substitution attacks. | Future |
|
||||
| 3 | **WebTransport (HTTP/3)** | Enables browser clients without a WebSocket bridge. | Future |
|
||||
| 4 | **OpenTelemetry** | Distributed tracing and structured metrics for production observability. | Future |
|
||||
| 5 | **WebAuthn / Passkeys** | Hardware-backed authentication to replace password-based login. | Future |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ for what that means in practice.
|
||||
| M4 | Group CLI Subcommands | **Complete** | Persistent CLI (create-group, invite, join, send, recv), OPAQUE login |
|
||||
| M5 | Multi-party Groups | **Complete** | N > 2 members, Commit fan-out, send --all, epoch sync |
|
||||
| M6 | Persistence | **Complete** | SQLite/SQLCipher, migrations, durable server + client state |
|
||||
| M7 | Post-quantum | **Next** | PQ hybrid for MLS/HPKE (X25519 + ML-KEM-768) |
|
||||
| M7 | Post-quantum | **Complete** | PQ hybrid for MLS/HPKE (X25519 + ML-KEM-768) |
|
||||
|
||||
---
|
||||
|
||||
@@ -129,14 +129,13 @@ optional follow-ups.
|
||||
|
||||
**Goal:** Server survives restart. Client state persists across sessions.
|
||||
|
||||
**Deliverables:** SQLite/SQLCipher via rusqlite, `migrations/` directory and
|
||||
migration runner; client state file and DiskKeyStore (encrypted QPCE optional).
|
||||
See [Future Research: SQLCipher](future-research.md#storage--persistence) for
|
||||
encrypted-at-rest options.
|
||||
**Deliverables:** SQLCipher via rusqlite (bundled-sqlcipher feature), `migrations/`
|
||||
directory and migration runner; client state file and DiskKeyStore with
|
||||
Argon2id key derivation and ChaCha20-Poly1305 encryption at rest.
|
||||
|
||||
---
|
||||
|
||||
## M7 -- Post-quantum (Next)
|
||||
## M7 -- Post-quantum (Complete)
|
||||
|
||||
**Goal:** Replace the MLS crypto backend with a hybrid X25519 + ML-KEM-768 KEM,
|
||||
providing post-quantum confidentiality for all group key material.
|
||||
|
||||
@@ -36,14 +36,14 @@ The following legacy behaviour has been removed; only current behaviour is suppo
|
||||
|
||||
| Deliverable | Status |
|
||||
|-------------|--------|
|
||||
| `create-group` | Planned |
|
||||
| `invite <identity>` | Planned |
|
||||
| `join` | Planned |
|
||||
| `send <message>` | Planned |
|
||||
| `recv` | Planned |
|
||||
| Keep `demo-group` | Existing |
|
||||
| `create-group` | **Complete** |
|
||||
| `invite <identity>` | **Complete** |
|
||||
| `join` | **Complete** |
|
||||
| `send <message>` | **Complete** |
|
||||
| `recv` | **Complete** |
|
||||
| Keep `demo-group` | **Complete** |
|
||||
|
||||
See [Milestones](milestones.md#m4--group-cli-subcommands-next).
|
||||
See [Milestones](milestones.md#m4--group-cli-subcommands-complete).
|
||||
|
||||
---
|
||||
|
||||
@@ -53,10 +53,10 @@ See [Milestones](milestones.md#m4--group-cli-subcommands-next).
|
||||
|
||||
| Deliverable | Status |
|
||||
|-------------|--------|
|
||||
| Commit fan-out via DS | Planned |
|
||||
| Proposal handling (Add, Remove, Update) | Planned |
|
||||
| Epoch sync across N members | Planned |
|
||||
| Benchmarks | Planned |
|
||||
| Commit fan-out via DS | **Complete** |
|
||||
| Proposal handling (Add, Remove, Update) | **Complete** |
|
||||
| Epoch sync across N members | **Complete** |
|
||||
| Benchmarks | **Complete** |
|
||||
|
||||
---
|
||||
|
||||
@@ -66,10 +66,10 @@ See [Milestones](milestones.md#m4--group-cli-subcommands-next).
|
||||
|
||||
| Deliverable | Status |
|
||||
|-------------|--------|
|
||||
| SQLite/SQLCipher (AS + DS) | Partial (SqlStore exists) |
|
||||
| `migrations/` | Planned |
|
||||
| Client reconnect + session resume | Planned |
|
||||
| Docker + healthcheck | Partial (Dockerfile exists) |
|
||||
| SQLCipher (AS + DS) | **Complete** |
|
||||
| `migrations/` | **Complete** |
|
||||
| Client reconnect + session resume | **Complete** |
|
||||
| Docker + healthcheck | **Complete** |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ how they are enforced in code.
|
||||
### Transport Policy
|
||||
|
||||
- TLS 1.3 only (`rustls` configured with `TLS13` cipher suites exclusively).
|
||||
- ALPN token `b"capnp"` required; reject connections with mismatched ALPN.
|
||||
- ALPN token `b"qpq"` required; reject connections with mismatched ALPN.
|
||||
- Self-signed certificates acceptable for development; production deployments
|
||||
must use a CA-signed certificate or certificate pinning.
|
||||
- Connection draining on shutdown (QUIC `CONNECTION_CLOSE`).
|
||||
@@ -60,7 +60,7 @@ how they are enforced in code.
|
||||
|
||||
### Input Validation
|
||||
|
||||
- All incoming Cap'n Proto messages validated against schema before processing.
|
||||
- All incoming Protobuf messages validated against schema before processing.
|
||||
- Maximum payload size: 5 MB per RPC call.
|
||||
- Group ID, identity key, and channel ID fields validated for correct length
|
||||
(32 bytes, 32 bytes, 16 bytes respectively).
|
||||
@@ -101,7 +101,7 @@ how they are enforced in code.
|
||||
- Integration tests for every RPC method.
|
||||
- Negative tests: malformed input, expired tokens, wrong identity, replay attempts.
|
||||
- N-1 compatibility tests (old client against new server).
|
||||
- Fuzzing targets for Cap'n Proto parsers and MLS message handling (Phase 5).
|
||||
- Fuzzing targets for Protobuf parsers and MLS message handling (Phase 5).
|
||||
|
||||
---
|
||||
|
||||
@@ -125,10 +125,10 @@ how they are enforced in code.
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| Wire versioning | Add `version` field to all Cap'n Proto structs; reject unknown versions |
|
||||
| Wire versioning | Version field in all Protobuf frames; reject unknown versions |
|
||||
| Ciphersuite allowlist | Server rejects KeyPackages outside the allowed set |
|
||||
| Downgrade guards | Prevent epoch rollback; reject Commits with weaker ciphersuites |
|
||||
| ALPN enforcement | Reject connections without `b"capnp"` ALPN token |
|
||||
| ALPN enforcement | Reject connections without `b"qpq"` ALPN token |
|
||||
| Connection draining | Graceful QUIC `CONNECTION_CLOSE` on server shutdown |
|
||||
| KeyPackage rotation | Client-side timer to upload fresh KeyPackages before TTL expiry |
|
||||
|
||||
@@ -172,7 +172,7 @@ See [1:1 Channel Design](dm-channels.md) for the DM-specific design.
|
||||
| Positive E2E tests | Full group lifecycle: register, create, invite, join, send, recv, leave |
|
||||
| Negative E2E tests | Expired tokens, wrong identity, replay, malformed messages |
|
||||
| Compat matrix | N-1 client/server version testing |
|
||||
| Fuzz targets | `cargo-fuzz` targets for Cap'n Proto parsers, MLS message handlers |
|
||||
| Fuzz targets | `cargo-fuzz` targets for Protobuf parsers, MLS message handlers |
|
||||
| Golden-wire fixtures | Serialised test vectors for regression testing across versions |
|
||||
|
||||
### Phase 6 -- Reliability, Performance, and Operations
|
||||
|
||||
Reference in New Issue
Block a user