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

docs: rewrite mdBook documentation for v2 architecture

Browse Source 
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:
Christian Nennemann
2026-03-04 22:02:31 +01:00
parent f7a7f672b4
commit d073f614b3
31 changed files with 4423 additions and 2379 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/src/architecture/overview.md
View File

@@ -8,21 +8,20 @@ system, the dual-key cryptographic model, and how the pieces fit together.
## Two-Service Model
The server exposes two logical services through a single **NodeService** RPC
interface, bound to **port 7000** over QUIC + TLS 1.3:
The server exposes two logical services through a unified RPC endpoint
bound to **port 5001** over QUIC + TLS 1.3:
| Logical Service | Responsibility |
|--------------------------|-----------------------------------------------------------------|
| **Authentication Service (AS)** | Stores and distributes single-use MLS KeyPackages. Clients upload KeyPackages after identity generation; peers fetch them to add new members to a group. |
| **Authentication Service (AS)** | Stores and distributes single-use MLS KeyPackages. Clients upload KeyPackages after identity generation; peers fetch them to add new members to a group. Also manages hybrid PQ public keys and identity resolution. |
| **Delivery Service (DS)** | Store-and-forward relay for opaque payloads. The DS never inspects MLS ciphertext -- it routes solely by recipient Ed25519 public key (and optional channel ID). |
Combining both services into a single endpoint simplifies deployment and
reduces round-trips. The schema is defined in
[`schemas/node.capnp`](../wire-format/node-service-schema.md) as a unified
`NodeService` interface.
Both services are accessed through a single QUIC connection using the v2
Protobuf framing protocol. Each RPC call gets a dedicated QUIC bidirectional
stream to prevent head-of-line blocking.
See [Service Architecture](service-architecture.md) for per-method details,
connection lifecycle, and the long-polling `fetchWait` mechanism.
connection lifecycle, and push event delivery.
---
@@ -33,17 +32,17 @@ as its long-term identity:
```text
quicproquo Key Model
┌──────────────────────────────────────────────────┐
│ │
│ Ed25519 signing keypair (MLS identity) │
│ ────────────────────────────────────── │
│ - Generated once per user/device │
│ - Embedded in MLS BasicCredential │
│ - Signs KeyPackages, Commits, and group ops │
│ - Raw 32-byte public key is the AS index │
│ - Managed by IdentityKeypair, zeroize-on-drop │
│ │
└──────────────────────────────────────────────────┘
+--------------------------------------------------+
| |
| Ed25519 signing keypair (MLS identity) |
| ------------------------------------------ |
| - Generated once per user/device |
| - Embedded in MLS BasicCredential |
| - Signs KeyPackages, Commits, and group ops |
| - Raw 32-byte public key is the AS index |
| - Managed by IdentityKeypair, zeroize-on-drop |
| |
+--------------------------------------------------+
```
| Property | Ed25519 (MLS) |
@@ -52,7 +51,7 @@ as its long-term identity:
| Purpose | Identity binding, signing, MLS credentials |
| Crate | `ed25519-dalek` |
| Zeroize on drop | Yes (`Zeroizing<[u8; 32]>`) |
| PQ protection | MLS key schedule uses DHKEM(X25519); hybrid PQ KEM available at envelope level |
| PQ protection | MLS key schedule uses DHKEM(X25519); hybrid X25519+ML-KEM-768 KEM available at envelope level |
For details on the cryptographic properties, see
[Ed25519 Identity Keys](../cryptography/identity-keys.md).
@@ -62,37 +61,41 @@ For details on the cryptographic properties, see
## System Diagram
```text
┌─────────────────┐ ┌─────────────────┐
│ Alice Client │ │ Bob Client │
│ │ │ │
│ IdentityKeypair │ │ IdentityKeypair │
│ (Ed25519) │ │ (Ed25519) │
│ │ │ │
│ GroupMember │ │ GroupMember │
│ (MLS state) │ │ (MLS state) │
└────────┬─────────┘ └────────┬─────────┘
│ │
│ QUIC + TLS 1.3 (quinn/rustls) │
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ NodeService (port 7000) │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Authentication Service │ │ Delivery Service │ │
│ │ │ │ │ │
│ │ uploadKeyPackage() │ │ enqueue(recipientKey, payload) │ │
│ │ fetchKeyPackage() │ │ fetch(recipientKey) │ │
│ │ uploadHybridKey() │ │ fetchWait(recipientKey, timeout) │ │
│ │ fetchHybridKey() │ │ │ │
│ │ │ │ Queues: DashMap + FileBackedStore│ │
│ │ Store: DashMap + │ │ │ │
│ │ FileBackedStore │ │ │ │
│ └──────────────────────────┘ └───────────────────────────────────┘ │
│ │
│ health() │
│ │
└────────────────────────────────────────────────────────────────────────────┘
+-----------------+ +-----------------+
| Alice Client | | Bob Client |
| | | |
| IdentityKeypair | | IdentityKeypair |
| (Ed25519) | | (Ed25519) |
| | | |
| QpqClient | | QpqClient |
| (SDK) | | (SDK) |
+--------+---------+ +--------+---------+
| |
| QUIC + TLS 1.3 (quinn/rustls) ALPN: "qpq" |
| |
v v
+------------------------------------------------------------------------+
| quicproquo-server (port 5001) |
| |
| +---------------------------+ +--------------------------------+ |
| | Authentication Service | | Delivery Service | |
| | | | | |
| | OpaqueRegisterStart(100) | | Enqueue(200) | |
| | OpaqueRegisterFinish(101)| | Fetch(201) | |
| | OpaqueLoginStart(102) | | FetchWait(202) | |
| | OpaqueLoginFinish(103) | | Peek(203) | |
| | | | Ack(204) | |
| | UploadKeyPackage(300) | | BatchEnqueue(205) | |
| | FetchKeyPackage(301) | | | |
| | UploadHybridKey(302) | | Store: SQLCipher | |
| | FetchHybridKey(303) | | DashMap waiters | |
| | FetchHybridKeys(304) | +--------------------------------+ |
| +---------------------------+ |
| |
| + 34 more methods: Keys, Channel, Group, User, KT, Blob, Device, |
| P2P, Federation, Moderation, Recovery, Account (see method_ids) |
| |
+------------------------------------------------------------------------+
```
**Key observations:**
@@ -103,7 +106,11 @@ For details on the cryptographic properties, see
2. KeyPackages are single-use (RFC 9420 requirement). The AS atomically removes
a KeyPackage on fetch to enforce this invariant.
3. QUIC + TLS 1.3 is the sole transport layer.
3. QUIC + TLS 1.3 is the sole transport layer. The ALPN identifier is `qpq`.
4. Push events (new messages, typing, presence, membership changes) are
delivered server-to-client on QUIC uni-streams using a separate push frame
format.
---
@@ -114,14 +121,14 @@ The system stacks three protocol layers:
1. **Transport** -- QUIC + TLS 1.3. Provides confidentiality, integrity, and
server authentication. See [Protocol Stack](protocol-stack.md).
2. **Framing / RPC** -- Cap'n Proto serialisation and RPC. Provides zero-copy
typed messages, schema versioning, and async method dispatch.
See [Cap'n Proto Serialisation and RPC](../protocol-layers/capn-proto.md).
2. **Framing / RPC** -- Custom binary header + Protobuf serialisation. Each
request frame is `[method_id: u16][request_id: u32][payload_len: u32][protobuf]`.
Responses are `[status: u8][request_id: u32][payload_len: u32][protobuf]`.
See [Protobuf Framing](../protocol-layers/capn-proto.md).
3. **End-to-End Encryption** -- MLS (RFC 9420). Provides group key agreement,
forward secrecy, and post-compromise security. The server never holds group
keys.
See [MLS (RFC 9420)](../protocol-layers/mls.md).
keys. See [MLS (RFC 9420)](../protocol-layers/mls.md).
An optional fourth layer -- the **hybrid KEM envelope** (X25519 + ML-KEM-768)
-- wraps MLS payloads for post-quantum confidentiality at the per-message level.
@@ -131,14 +138,19 @@ See [Hybrid KEM](../protocol-layers/hybrid-kem.md).
## Crate Map
The implementation is split across four workspace crates:
The implementation is split across nine workspace crates:
| Crate | Role |
|----------------------------|-------------------------------------------------------------------|
| `quicproquo-core` | Crypto primitives, MLS state machine, hybrid KEM |
| `quicproquo-proto` | Cap'n Proto schemas, codegen, and serialisation helpers |
| `quicproquo-server` | QUIC listener, NodeService RPC, storage |
| `quicproquo-client` | QUIC client, CLI subcommands, state persistence |
| Crate | Role |
|------------------------------|-------------------------------------------------------------------|
| `quicproquo-core` | Crypto primitives, MLS state machine, hybrid KEM |
| `quicproquo-proto` | Cap'n Proto legacy types + Protobuf (prost) v2 generated types |
| `quicproquo-kt` | Key transparency (append-only log, revocation) |
| `quicproquo-plugin-api` | `#![no_std]` C-ABI plugin interface |
| `quicproquo-rpc` | QUIC RPC framework: framing, server dispatch, client, middleware |
| `quicproquo-sdk` | Client SDK: `QpqClient`, event broadcast, `ConversationStore` |
| `quicproquo-server` | RPC server + domain services |
| `quicproquo-client` | CLI/TUI client binary |
| `quicproquo-p2p` | iroh P2P endpoint publish/resolve (feature-flagged) |
See [Crate Responsibilities](crate-responsibilities.md) for a full breakdown
and dependency diagram.
@@ -148,7 +160,7 @@ and dependency diagram.
## Further Reading
- [Protocol Stack](protocol-stack.md) -- layered protocol stack description
- [Service Architecture](service-architecture.md) -- NodeService RPC methods, connection lifecycle, long-polling
- [Service Architecture](service-architecture.md) -- 44 RPC methods, connection lifecycle, push events
- [End-to-End Data Flow](data-flow.md) -- registration, group creation, and message exchange sequence diagrams
- [Wire Format Overview](../wire-format/overview.md) -- Cap'n Proto schema reference
- [Wire Format Reference](../wire-format/overview.md) -- Protobuf schema reference and method ID table
- [Cryptography Overview](../cryptography/overview.md) -- detailed cryptographic properties and threat model