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:
2026-03-04 22:02:31 +01:00
parent f7a7f672b4
commit d073f614b3
31 changed files with 4423 additions and 2379 deletions

View File

@@ -182,29 +182,22 @@ could provide an additional detection mechanism.
### No Client Authentication on the Delivery Service
The Delivery Service does not currently authenticate clients. Anyone who knows
a recipient's Ed25519 public key can enqueue messages for that recipient. This
enables spam and potential denial-of-service by flooding a recipient's queue.
The Delivery Service requires a valid OPAQUE session token for all DS
operations. The session token is bound to the client's identity key, and the
server rejects enqueue and fetch operations that lack a valid token.
**Impact:** Queue flooding, spam delivery. MLS provides its own authentication
(the recipient will reject messages not signed by a group member), so forged
content will not be accepted, but the recipient must still download and attempt
to process the spam.
**Status:** Mitigated. Token-based authentication is enforced via the OPAQUE
login flow (methods 100-103). Unauthenticated enqueue attempts are rejected.
**Mitigation path:** The AUTHZ\_PLAN introduces token-based authentication,
binding identityKey to accounts and requiring valid access tokens for all
DS operations.
### Rate Limiting
### No Rate Limiting
The server enforces a sliding window rate limit on all RPC methods. Requests
exceeding the configured threshold per IP or per account are rejected with a
rate-limit error response.
The server does not currently enforce per-client or per-IP rate limits. A
malicious client could flood the server with requests, consuming resources and
degrading service for other users.
**Impact:** Denial of service.
**Mitigation path:** The AUTHZ\_PLAN specifies per-IP and per-account/device
rate limits (e.g., 50 requests/second, 5 MB payload cap).
**Status:** Mitigated. Rate limiting is active (sliding window, configurable
threshold, default 50 requests/second per IP). The `rate_limit_hit_total`
Prometheus metric tracks rejections. See [Monitoring](../operations/monitoring.md).
### BasicCredential Only
@@ -234,18 +227,30 @@ hybrid KEM is active for MLS).
**Mitigation path:** Adopt post-quantum TLS (ML-KEM in TLS 1.3 handshake) when
`rustls` supports it.
## Future Mitigations
## Implemented Mitigations
### Sealed Sender
**Goal:** Hide the sender's identity from the server.
**Status:** Implemented. The `--sealed-sender` flag encrypts the sender's
identity inside the MLS ciphertext. When enabled, the server routes by recipient
queue index only and cannot determine who sent the message. This reduces server
metadata visibility from "who sent to whom" to "someone sent to this recipient."
**Approach:** Encrypt the sender's identity inside the MLS ciphertext. The
server cannot determine who sent a message -- it only knows the recipient
(delivery queue index). Signal implements a version of this as "Sealed Sender."
### OPAQUE Authentication
**Benefit:** Reduces the server's metadata visibility from "who sent to whom"
to "someone sent to this recipient."
**Status:** Implemented. The OPAQUE protocol (RFC 9497) is the only supported
login mechanism. The server stores OPAQUE registration records; it never receives
or stores the client's password. Session tokens issued on login are required for
all authenticated RPCs.
### Username Enumeration Protection
**Status:** Implemented. All auth responses (including failures) are subject to
a 5ms timing floor, preventing timing-based username enumeration.
---
## Future Mitigations
### Private Information Retrieval (PIR)
@@ -272,17 +277,6 @@ verify that their public key has not been replaced by an attacker.
**Benefit:** Detects attacks where the server (or an attacker who compromised
the server) substitutes a victim's public key with the attacker's key.
### OPAQUE Authentication
**Goal:** Zero-knowledge password authentication.
**Approach:** Use the OPAQUE protocol (RFC 9497) for client-server
authentication. OPAQUE allows the client to prove knowledge of a password
without revealing it to the server, even during registration.
**Benefit:** The server never learns the client's password, preventing
credential theft in a server compromise.
### Tor/I2P Integration
**Goal:** Hide client IP addresses from the server and network adversaries.
@@ -315,11 +309,12 @@ communication patterns from traffic analysis.
|--------|-------------------|-----|-------------|
| Passive eavesdropper | TLS 1.3 + MLS (2 layers) | Traffic analysis | Padding, Tor |
| Active MITM | TLS 1.3 (QUIC) | Self-signed certs | Cert pinning, CA |
| Compromised server | MLS E2E encryption | Metadata visible | Sealed Sender, PIR |
| Compromised server | MLS E2E encryption + Sealed Sender | Metadata partially visible | PIR |
| Compromised client | FS + PCS | Current epoch exposed | Periodic Updates |
| Spam/flooding | None | No auth on DS | AUTHZ\_PLAN |
| Spam/flooding | Rate limiting + OPAQUE session tokens | -- | -- |
| Username enumeration | 5ms timing floor on all auth responses | -- | -- |
| Key substitution | None | BasicCredential only | Key Transparency |
| Quantum adversary (content) | Hybrid KEM (M5+) | Pre-M5 messages | Deploy hybrid ASAP |
| Quantum adversary (content) | Hybrid KEM (X25519 + ML-KEM-768) | Pre-v2 messages | -- |
| Quantum adversary (transport) | None | Classical TLS (ECDHE) | PQ TLS |
## Related Pages