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 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user