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

chore: rename quicproquo → quicprochat in docs, Docker, CI, and packaging

Browse Source 
Rename all project references from quicproquo/qpq to quicprochat/qpc
across documentation, Docker configuration, CI workflows, packaging
scripts, operational configs, and build tooling.

- Docker: crate paths, binary names, user/group, data dirs, env vars
- CI: workflow crate references, binary names, artifact names
- Docs: all markdown files under docs/, SDK READMEs, book.toml
- Packaging: OpenWrt Makefile, init script, UCI config (file renames)
- Scripts: justfile, dev-shell, screenshot, cross-compile, ai_team
- Operations: Prometheus config, alert rules, Grafana dashboard
- Config: .env.example (QPQ_* → QPC_*), CODEOWNERS paths
- Top-level: README, CONTRIBUTING, ROADMAP, CLAUDE.md
This commit is contained in:
Christian Nennemann
2026-03-07 18:46:43 +01:00
parent a710037dde
commit 2e081ead8e
179 changed files with 1645 additions and 1645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/src/design-rationale/adr-002-capnproto.md
View File

@@ -6,7 +6,7 @@
## Context
quicproquo needs an efficient, typed wire format for client-server communication. The format must support:
quicprochat needs an efficient, typed wire format for client-server communication. The format must support:
1. **Typed messages** with compile-time schema enforcement to eliminate hand-rolled serialisation bugs.
2. **Schema evolution** so that new fields and methods can be added without breaking existing clients.
@@ -105,7 +105,7 @@ The Cap'n Proto schemas are stored in the `schemas/` directory:
### Costs and trade-offs
- **Build-time code generation.** The `capnpc` compiler must run during the build (via `build.rs` in `quicproquo-proto`). This adds a build dependency and increases compile times slightly.
- **Build-time code generation.** The `capnpc` compiler must run during the build (via `build.rs` in `quicprochat-proto`). This adds a build dependency and increases compile times slightly.
- **Learning curve.** Cap'n Proto's builder/reader API is different from typical `serde`-based Rust serialisation. Developers must learn the Cap'n Proto programming model (builders for construction, readers for traversal, owned messages for storage).
- **Generated code verbosity.** The generated Rust code is verbose and not intended to be read directly. Application code interacts with it through the builder/reader traits.
- **Smaller ecosystem than Protobuf.** Cap'n Proto has fewer users, fewer tutorials, and fewer third-party tools than Protobuf. However, the core Rust crates are well-maintained.
@@ -114,7 +114,7 @@ The Cap'n Proto schemas are stored in the `schemas/` directory:
### Residual risks
- **Crate maintenance.** The `capnp` and `capnp-rpc` crates are maintained primarily by David Renshaw. If maintenance lapses, the project would need to fork or switch serialisation formats. Mitigated by the crates' maturity and the relatively stable Cap'n Proto specification.
- **RPC limitations.** The Rust `capnp-rpc` crate implements Level 1 of the Cap'n Proto RPC protocol. Level 3 features (three-party handoffs) are not supported. This has not been a limitation for quicproquo's client-server architecture.
- **RPC limitations.** The Rust `capnp-rpc` crate implements Level 1 of the Cap'n Proto RPC protocol. Level 3 features (three-party handoffs) are not supported. This has not been a limitation for quicprochat's client-server architecture.
---
@@ -126,8 +126,8 @@ The Cap'n Proto schemas are stored in the `schemas/` directory:
| `schemas/auth.capnp` | AuthenticationService RPC interface |
| `schemas/delivery.capnp` | DeliveryService RPC interface |
| `schemas/node.capnp` | NodeService unified RPC interface |
| `crates/quicproquo-proto/build.rs` | Build script that invokes `capnpc` for code generation |
| `crates/quicproquo-proto/src/lib.rs` | Re-exports generated Cap'n Proto modules |
| `crates/quicprochat-proto/build.rs` | Build script that invokes `capnpc` for code generation |
| `crates/quicprochat-proto/src/lib.rs` | Re-exports generated Cap'n Proto modules |
---

6
docs/src/design-rationale/adr-004-mls-unaware-ds.md
View File

@@ -40,7 +40,7 @@ The RFC explicitly envisions that the DS operates on opaque blobs, not on decryp
## Decision
The quicproquo Delivery Service is **MLS-unaware**. It routes opaque byte strings by `(recipientKey, channelId)` without parsing, inspecting, or validating any MLS content.
The quicprochat Delivery Service is **MLS-unaware**. It routes opaque byte strings by `(recipientKey, channelId)` without parsing, inspecting, or validating any MLS content.
### What the DS sees
@@ -109,8 +109,8 @@ This means that sending a message to a group of n members requires n-1 enqueue c
|---|---|
| `schemas/delivery.capnp` | DeliveryService RPC interface (opaque `Data` payloads) |
| `schemas/node.capnp` | NodeService: `enqueue`, `fetch`, `fetchWait` methods |
| `crates/quicproquo-server/src/storage.rs` | Server-side queue storage (DashMap-based FIFO queues) |
| `crates/quicproquo-server/src/main.rs` | NodeService RPC handler implementation |
| `crates/quicprochat-server/src/storage.rs` | Server-side queue storage (DashMap-based FIFO queues) |
| `crates/quicprochat-server/src/main.rs` | NodeService RPC handler implementation |
---

4
docs/src/design-rationale/adr-005-single-use-keypackages.md
View File

@@ -100,8 +100,8 @@ This is a defense-in-depth measure. In practice, MLS's own signature verificatio
|---|---|
| `schemas/auth.capnp` | `AuthenticationService` interface: `uploadKeyPackage`, `fetchKeyPackage` |
| `schemas/node.capnp` | `NodeService` interface: same methods with `Auth` parameter |
| `crates/quicproquo-server/src/storage.rs` | Server-side KeyPackage storage (DashMap-backed queue) |
| `crates/quicproquo-server/src/main.rs` | RPC handler: `fetchKeyPackage` implementation with atomic removal |
| `crates/quicprochat-server/src/storage.rs` | Server-side KeyPackage storage (DashMap-backed queue) |
| `crates/quicprochat-server/src/main.rs` | RPC handler: `fetchKeyPackage` implementation with atomic removal |
---

12
docs/src/design-rationale/adr-006-rest-gateway.md
View File

@@ -6,7 +6,7 @@ Accepted (supersedes earlier REST gateway proposal)
## Context
quicproquo uses QUIC + Cap'n Proto RPC as its native protocol. This
quicprochat uses QUIC + Cap'n Proto RPC as its native protocol. This
combination delivers zero-copy serialization, multiplexed streams, and
sub-RTT connection establishment — ideal for high-performance clients.
@@ -58,11 +58,11 @@ Both paths use QUIC transport. The project name stays honest.
### Crypto layer distribution
MLS encryption/decryption must happen client-side. The `quicproquo-core`
MLS encryption/decryption must happen client-side. The `quicprochat-core`
crate is compiled to:
- **WASM** — for browsers, Node.js, Deno
- **C FFI** (`libquicproquo`) — for Swift, Kotlin, Python, Go (via cgo)
- **C FFI** (`libquicprochat`) — for Swift, Kotlin, Python, Go (via cgo)
- **Native Rust** — for Rust clients (existing)
### Why not REST?
@@ -104,9 +104,9 @@ gRPC may be reconsidered for server-to-server federation (Phase 7.3).
### Neutral
- SDKs live in separate repositories (e.g., `quicproquo-go`,
`quicproquo-py`) to avoid bloating the core workspace.
- The C FFI crate (`quicproquo-ffi`) bundles both crypto and transport,
- SDKs live in separate repositories (e.g., `quicprochat-go`,
`quicprochat-py`) to avoid bloating the core workspace.
- The C FFI crate (`quicprochat-ffi`) bundles both crypto and transport,
so language bindings only need to call C functions.
## Related

20
docs/src/design-rationale/overview.md
View File

@@ -1,6 +1,6 @@
# Design Decisions Overview
This section collects the Architecture Decision Records (ADRs) that document the key design choices in quicproquo. Each ADR follows a standard format: context (why the decision was needed), decision (what was chosen), and consequences (trade-offs, benefits, and residual risks).
This section collects the Architecture Decision Records (ADRs) that document the key design choices in quicprochat. Each ADR follows a standard format: context (why the decision was needed), decision (what was chosen), and consequences (trade-offs, benefits, and residual risks).
These decisions are not immutable. Each ADR has a status field and can be superseded by a later ADR if circumstances change. The goal is to preserve the reasoning behind each choice so that future contributors understand *why* the system works the way it does, not just *how*.
@@ -19,7 +19,7 @@ These decisions are not immutable. Each ADR has a status field and can be supers
## Design comparison
For a broader comparison of quicproquo's design against alternative messaging protocols (Signal, Matrix/Olm/Megolm), see [Why This Design, Not Signal/Matrix/...](why-not-signal.md).
For a broader comparison of quicprochat's design against alternative messaging protocols (Signal, Matrix/Olm/Megolm), see [Why This Design, Not Signal/Matrix/...](why-not-signal.md).
---
@@ -41,7 +41,7 @@ Each ADR page follows this structure:
**Context**
quicproquo v1 used Cap'n Proto for both serialisation and RPC dispatch via
quicprochat v1 used Cap'n Proto for both serialisation and RPC dispatch via
`capnp-rpc`. This worked well for the initial 8-method `NodeService` interface
but had several limitations as the protocol expanded:
@@ -60,15 +60,15 @@ but had several limitations as the protocol expanded:
**Decision**
Replace `capnp-rpc` with a custom binary framing layer (`quicproquo-rpc`) and
Replace `capnp-rpc` with a custom binary framing layer (`quicprochat-rpc`) and
Protocol Buffers (`prost`) for payload serialisation:
- Three frame types: Request (10-byte header), Response (9-byte header), Push
(6-byte header), all carrying Protobuf-encoded payloads.
- Method IDs are numeric `u16` constants dispatched via a handler registry.
One QUIC bidirectional stream per RPC call; push events on QUIC uni-streams.
- ALPN changed from `b"capnp"` to `b"qpq"`. Default port changed from 7000 to 5001.
- Cap'n Proto legacy types are retained in `quicproquo-proto` for v1 compatibility
- ALPN changed from `b"capnp"` to `b"qpc"`. Default port changed from 7000 to 5001.
- Cap'n Proto legacy types are retained in `quicprochat-proto` for v1 compatibility
but are no longer used for RPC dispatch.
**Consequences**
@@ -90,9 +90,9 @@ Costs:
**Code references**
- Frame format: `crates/quicproquo-rpc/src/framing.rs`
- Method IDs: `crates/quicproquo-proto/src/lib.rs` (`method_ids` module)
- Proto schemas: `proto/qpq/v1/*.proto`
- Frame format: `crates/quicprochat-rpc/src/framing.rs`
- Method IDs: `crates/quicprochat-proto/src/lib.rs` (`method_ids` module)
- Proto schemas: `proto/qpc/v1/*.proto`
---
@@ -109,7 +109,7 @@ ADR-004 and ADR-005 reflect a design philosophy where the server does as little
### Schema-first design
The v2 protocol defines all messages and method IDs in checked-in source files
(`proto/qpq/v1/*.proto` and `crates/quicproquo-proto/src/lib.rs`). Every wire
(`proto/qpc/v1/*.proto` and `crates/quicprochat-proto/src/lib.rs`). Every wire
type is documented, versioned, and evolvable through the standard Protobuf
schema evolution rules (adding optional fields, reserving removed field numbers).

64
docs/src/design-rationale/protocol-comparison.md
View File

@@ -1,6 +1,6 @@
# Comparison with Classical Chat Protocols
This page compares quicproquo against **classical and legacy chat protocols** -- IRC+SSL, XMPP (with and without OMEMO), Telegram's MTProto, and plain TCP/TLS chat systems -- to demonstrate what a modern, cryptographically rigorous design provides over protocols that were designed before end-to-end encryption, post-compromise security, and post-quantum readiness were practical concerns.
This page compares quicprochat against **classical and legacy chat protocols** -- IRC+SSL, XMPP (with and without OMEMO), Telegram's MTProto, and plain TCP/TLS chat systems -- to demonstrate what a modern, cryptographically rigorous design provides over protocols that were designed before end-to-end encryption, post-compromise security, and post-quantum readiness were practical concerns.
For a comparison against modern E2E-encrypted protocols (Signal, Matrix/Olm/Megolm), see [Why This Design, Not Signal/Matrix/...](why-not-signal.md).
@@ -9,7 +9,7 @@ For a comparison against modern E2E-encrypted protocols (Signal, Matrix/Olm/Mego
## At a glance
```
Classical IRC+SSL quicproquo
Classical IRC+SSL quicprochat
───────────────── ──────────────
You ──TLS──▶ Server ──TLS──▶ Bob You ──QUIC/TLS──▶ Server ──QUIC/TLS──▶ Bob
@@ -19,13 +19,13 @@ For a comparison against modern E2E-encrypted protocols (Signal, Matrix/Olm/Mego
messages (cannot decrypt)
```
The fundamental difference: **classical protocols trust the server with your plaintext**. quicproquo's server is cryptographically excluded from reading message content.
The fundamental difference: **classical protocols trust the server with your plaintext**. quicprochat's server is cryptographically excluded from reading message content.
---
## Protocol comparison matrix
| Property | IRC+SSL | XMPP+TLS | XMPP+OMEMO | Telegram (MTProto) | quicproquo |
| Property | IRC+SSL | XMPP+TLS | XMPP+OMEMO | Telegram (MTProto) | quicprochat |
|---|---|---|---|---|---|
| **Transport encryption** | TLS (server-to-server optional) | STARTTLS / direct TLS | STARTTLS / direct TLS | MTProto 2.0 (custom) | QUIC + TLS 1.3 |
| **End-to-end encryption** | None | None | Double Ratchet (1:1) | "Secret chats" only (1:1) | MLS RFC 9420 (groups native) |
@@ -41,7 +41,7 @@ The fundamental difference: **classical protocols trust the server with your pla
---
## Deep dive: IRC+SSL vs. quicproquo
## Deep dive: IRC+SSL vs. quicprochat
IRC (Internet Relay Chat) is the archetypal chat protocol, designed in 1988. Adding SSL/TLS wraps the TCP connection in transport encryption, but the protocol's security model remains fundamentally unchanged.
@@ -66,7 +66,7 @@ IRC (Internet Relay Chat) is the archetypal chat protocol, designed in 1988. Add
4. **No post-compromise security.** There is no mechanism to recover from a key compromise. If a server is breached, all messages flowing through it are exposed indefinitely.
5. **No identity binding.** NickServ password authentication is plaintext over the IRC protocol (inside TLS, but visible to the server). There is no cryptographic binding between a user's identity and their messages.
### What happens when Alice sends a message on quicproquo
### What happens when Alice sends a message on quicprochat
```
┌───────┐ ┌────────┐ ┌─────┐
@@ -93,7 +93,7 @@ IRC (Internet Relay Chat) is the archetypal chat protocol, designed in 1988. Add
---
## Deep dive: XMPP+OMEMO vs. quicproquo
## Deep dive: XMPP+OMEMO vs. quicprochat
XMPP with OMEMO (XEP-0384) adds end-to-end encryption via the Signal Double Ratchet protocol. This is a significant improvement over plain XMPP, but OMEMO inherits the limitations of the Signal Protocol for group messaging.
@@ -109,7 +109,7 @@ XMPP with OMEMO (XEP-0384) adds end-to-end encryption via the Signal Double Ratc
3 encryptions per message
O(n) cost per send
quicproquo MLS group (4 members)
quicprochat MLS group (4 members)
Alice encrypts once with group epoch key:
┌───────┐ ── MLS_encrypt(epoch_key) ──▶ Server
@@ -120,7 +120,7 @@ XMPP with OMEMO (XEP-0384) adds end-to-end encryption via the Signal Double Ratc
(all decrypt with same epoch key)
```
| Property | XMPP+OMEMO groups | quicproquo MLS groups |
| Property | XMPP+OMEMO groups | quicprochat MLS groups |
|---|---|---|
| **Encryption per message** | O(n) -- encrypt once per recipient | O(1) -- single MLS application message |
| **Add member** | O(n) -- distribute sender keys to all | O(log n) -- single MLS Commit |
@@ -131,7 +131,7 @@ XMPP with OMEMO (XEP-0384) adds end-to-end encryption via the Signal Double Ratc
---
## Deep dive: Telegram (MTProto) vs. quicproquo
## Deep dive: Telegram (MTProto) vs. quicprochat
Telegram is often perceived as a "secure" messenger, but its default mode provides **no end-to-end encryption**. Only "Secret Chats" (1:1 only, not available on desktop) use E2E encryption.
@@ -163,7 +163,7 @@ Telegram is often perceived as a "secure" messenger, but its default mode provid
### Comparison
| Property | Telegram Cloud Chats | Telegram Secret Chats | quicproquo |
| Property | Telegram Cloud Chats | Telegram Secret Chats | quicprochat |
|---|---|---|---|
| **Server reads plaintext** | Yes | No | No |
| **Group E2E** | No | N/A (1:1 only) | Yes (MLS) |
@@ -173,7 +173,7 @@ Telegram is often perceived as a "secure" messenger, but its default mode provid
| **Open source server** | No | No | Yes (MIT license) |
| **Post-quantum** | None | None | Hybrid KEM (X25519 + ML-KEM-768) |
**Critical concern with Telegram:** MTProto is a custom, proprietary cryptographic protocol that has not undergone the same level of independent cryptographic review as standard protocols (TLS, MLS, Signal Protocol). Multiple academic papers have identified weaknesses in earlier versions. quicproquo exclusively uses IETF-standardized protocols (TLS 1.3, MLS RFC 9420) and widely reviewed cryptographic primitives.
**Critical concern with Telegram:** MTProto is a custom, proprietary cryptographic protocol that has not undergone the same level of independent cryptographic review as standard protocols (TLS, MLS, Signal Protocol). Multiple academic papers have identified weaknesses in earlier versions. quicprochat exclusively uses IETF-standardized protocols (TLS 1.3, MLS RFC 9420) and widely reviewed cryptographic primitives.
---
@@ -208,7 +208,7 @@ An attacker gains root access to the chat server.
│ sees metadata (who talks to whom, │
│ when, message sizes). │
│ │
│ quicproquo: │
│ quicprochat: │
│ Cannot read messages (MLS E2E). │
│ Sees metadata (recipient keys, │
│ timing, sizes). │
@@ -243,7 +243,7 @@ A state-level adversary records all encrypted traffic today, planning to decrypt
Telegram (MTProto / custom DH):
└── Quantum computer breaks DH → all recorded messages decrypted
quicproquo (Hybrid KEM):
quicprochat (Hybrid KEM):
└── Transport: QUIC/TLS with ECDHE → quantum computer breaks this layer
└── Inner layer: MLS content encrypted with group epoch keys
└── Hybrid KEM envelope: X25519 + ML-KEM-768
@@ -252,7 +252,7 @@ A state-level adversary records all encrypted traffic today, planning to decrypt
└── Combined key: STILL SECURE (both must be broken)
```
quicproquo's hybrid "belt and suspenders" design means that **even if X25519 falls to a quantum computer, ML-KEM-768 protects the content**. The adversary's recorded ciphertext remains useless.
quicprochat's hybrid "belt and suspenders" design means that **even if X25519 falls to a quantum computer, ML-KEM-768 protects the content**. The adversary's recorded ciphertext remains useless.
### Scenario 3: Device theft / compromise
@@ -279,7 +279,7 @@ An attacker steals Alice's unlocked device and extracts her key material.
Messages after T: all accessible (cloud sync)
Recovery: terminate session from another device
quicproquo:
quicprochat:
Messages before T: protected (MLS forward secrecy, past epoch keys deleted)
Messages after T: exposed only until next MLS epoch advance
Recovery: ANY group member issues an MLS Update proposal →
@@ -293,7 +293,7 @@ An attacker steals Alice's unlocked device and extracts her key material.
### Why QUIC over TCP
Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) blocking. quicproquo uses QUIC, which provides independent streams over UDP.
Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) blocking. quicprochat uses QUIC, which provides independent streams over UDP.
```
TCP (IRC/XMPP): all streams share one ordered byte stream
@@ -308,7 +308,7 @@ Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) b
└── ALL streams blocked until retransmit
QUIC (quicproquo): each stream is independent
QUIC (quicprochat): each stream is independent
──────────────────────────────────────────────────
Stream A: ████████░░██████████████ (only A waits)
@@ -334,7 +334,7 @@ Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) b
════════════════════════════════════════════════════
Total: 2-3 round trips before first message
quicproquo: QUIC integrates crypto into handshake = 1 RTT (or 0-RTT)
quicprochat: QUIC integrates crypto into handshake = 1 RTT (or 0-RTT)
──────────────────────────────────────────────────────────────────────────
Client ──Initial(ClientHello)──▶ Server │
Client ◀──Initial(ServerHello)── Server │ 1 RTT total
@@ -363,7 +363,7 @@ Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) b
Phone number + SMS OTP ← carrier and Telegram see phone number
(identity = phone number) ← no cryptographic identity
quicproquo (OPAQUE PAKE):
quicprochat (OPAQUE PAKE):
Client ──blinded_element──▶ Server │ Server never sees password
Client ◀──evaluated_element── Server │ Mutual authentication
Client ──finalization──▶ Server │ Session key derived
@@ -406,7 +406,7 @@ Classical protocols (IRC, XMPP) use TCP, which suffers from head-of-line (HOL) b
│ Schema via XSD exists but rarely enforced at runtime. │
└──────────────────────────────────────────────────────────┘
Cap'n Proto (quicproquo):
Cap'n Proto (quicprochat):
┌──────────────────────────────────────────────────────────┐
│ [8-byte aligned struct with pointers] │
│ │
@@ -434,7 +434,7 @@ The following diagram maps each protocol against the security properties it prov
Telegram Cloud · · · · · · · ·
Telegram Secret △ · ● · · ● · ·
Signal ● · ● ● △ ● · ·
quicproquo ● ● ● ● ● ● ● ●
quicprochat ● ● ● ● ● ● ● ●
Legend: ● = yes △ = partial · = no
FS = forward secrecy PCS = post-compromise security
@@ -446,12 +446,12 @@ The following diagram maps each protocol against the security properties it prov
---
## The quicproquo advantage: a layered defense
## The quicprochat advantage: a layered defense
Classical protocols rely on a **single layer** of security (transport TLS). quicproquo applies defense in depth with **three independent layers**, each of which must be broken separately:
Classical protocols rely on a **single layer** of security (transport TLS). quicprochat applies defense in depth with **three independent layers**, each of which must be broken separately:
```
IRC+SSL security layers: quicproquo security layers:
IRC+SSL security layers: quicprochat security layers:
┌─────────────────────────┐ ┌─────────────────────────────────┐
│ TLS (transport) │ │ Layer 3: Hybrid KEM envelope │
@@ -474,7 +474,7 @@ Classical protocols rely on a **single layer** of security (transport TLS). quic
To read a message, attacker must break:
IRC+SSL: TLS (1 layer)
quicproquo: TLS + MLS + Hybrid KEM (3 layers)
quicprochat: TLS + MLS + Hybrid KEM (3 layers)
```
---
@@ -483,7 +483,7 @@ Classical protocols rely on a **single layer** of security (transport TLS). quic
Fairness demands acknowledging where classical protocols genuinely excel:
| Advantage | IRC | quicproquo |
| Advantage | IRC | quicprochat |
|---|---|---|
| **Simplicity** | Telnet-compatible text protocol | Binary protocol requiring client implementation |
| **Maturity** | 35+ years of production use | Early-stage research project |
@@ -493,7 +493,7 @@ Fairness demands acknowledging where classical protocols genuinely excel:
| **Public channels** | Designed for open, unencrypted discussion | Designed for private, encrypted communication |
| **Anonymity** | No identity required | Requires Ed25519 identity keypair |
IRC remains an excellent choice for **public, open discussion** where encryption is not needed and simplicity is valued. quicproquo is designed for a different threat model: private communication where **confidentiality, forward secrecy, and post-compromise security** are requirements, not luxuries.
IRC remains an excellent choice for **public, open discussion** where encryption is not needed and simplicity is valued. quicprochat is designed for a different threat model: private communication where **confidentiality, forward secrecy, and post-compromise security** are requirements, not luxuries.
---
@@ -501,10 +501,10 @@ IRC remains an excellent choice for **public, open discussion** where encryption
For users and operators coming from classical chat systems, here is what changes practically:
| Concern | Classical (IRC/XMPP) | quicproquo |
| Concern | Classical (IRC/XMPP) | quicprochat |
|---|---|---|
| **Server setup** | Install IRCd, configure TLS cert | `cargo build && ./qpq-server` (auto-generates TLS cert) |
| **Client setup** | Install any IRC client | `./quicproquo-client register-user` (generates Ed25519 identity) |
| **Server setup** | Install IRCd, configure TLS cert | `cargo build && ./qpc-server` (auto-generates TLS cert) |
| **Client setup** | Install any IRC client | `./quicprochat-client register-user` (generates Ed25519 identity) |
| **Joining a group** | `/join #channel` | Receive MLS Welcome message from group creator |
| **Sending a message** | Type and press enter | Same -- client handles MLS encryption transparently |
| **Server admin sees messages** | Yes (always) | No (never -- server sees only ciphertext) |
@@ -518,7 +518,7 @@ For users and operators coming from classical chat systems, here is what changes
- [Why This Design, Not Signal/Matrix/...](why-not-signal.md) -- comparison with modern E2E-encrypted protocols
- [Protocol Layers Overview](../protocol-layers/overview.md) -- detailed protocol stack documentation
- [Threat Model](../cryptography/threat-model.md) -- what quicproquo does and does not protect against
- [Threat Model](../cryptography/threat-model.md) -- what quicprochat does and does not protect against
- [Post-Quantum Readiness](../cryptography/post-quantum-readiness.md) -- hybrid KEM design and rationale
- [MLS (RFC 9420)](../protocol-layers/mls.md) -- deep dive into the group key agreement protocol
- [Architecture Overview](../architecture/overview.md) -- system-level architecture

34
docs/src/design-rationale/why-not-signal.md
View File

@@ -1,6 +1,6 @@
# Why This Design, Not Signal/Matrix/...
This page compares quicproquo's protocol choices against two widely deployed secure messaging systems -- the Signal Protocol and the Matrix ecosystem (Olm/Megolm) -- to explain why a different architecture was chosen. The comparison covers four dimensions: group key agreement, transport, serialisation, and overall trade-offs.
This page compares quicprochat's protocol choices against two widely deployed secure messaging systems -- the Signal Protocol and the Matrix ecosystem (Olm/Megolm) -- to explain why a different architecture was chosen. The comparison covers four dimensions: group key agreement, transport, serialisation, and overall trade-offs.
---
@@ -26,11 +26,11 @@ The Signal Protocol was designed for **1:1 messaging** and later extended to gro
- Group membership changes require O(n) pairwise Sender Key distributions. Adding or removing a member requires the affected member to generate a new Sender Key and distribute it to all n-1 other members.
- The pairwise key exchange for initial setup is O(n^2): each of n members must establish a Double Ratchet session with each of the other n-1 members.
**Limitations for quicproquo's use case:**
**Limitations for quicprochat's use case:**
- O(n^2) pairwise setup cost limits practical group size.
- No post-compromise security for groups is a significant gap.
- The protocol requires a central server for X3DH prekey bundle distribution (similar to quicproquo's AS, but tightly coupled to the Signal server).
- The protocol requires a central server for X3DH prekey bundle distribution (similar to quicprochat's AS, but tightly coupled to the Signal server).
### Matrix / Olm / Megolm
@@ -54,15 +54,15 @@ The Matrix ecosystem uses two distinct cryptographic protocols:
- **Eventually consistent state** model means that room membership, key sharing, and message ordering can diverge between homeservers. The client must reconcile these inconsistencies, adding complexity to the state machine.
- **Device verification** is a persistent UX challenge. The cross-signing mechanism is powerful but difficult for users to understand.
**Limitations for quicproquo's use case:**
**Limitations for quicprochat's use case:**
- No post-compromise security for groups (same limitation as Signal's Sender Keys).
- Federation adds latency, metadata exposure, and state management complexity that quicproquo does not need.
- Federation adds latency, metadata exposure, and state management complexity that quicprochat does not need.
- JSON-based wire format is inefficient (see serialisation comparison below).
### quicproquo: MLS (RFC 9420)
### quicprochat: MLS (RFC 9420)
quicproquo uses the **Messaging Layer Security (MLS)** protocol, standardized as RFC 9420 by the IETF.
quicprochat uses the **Messaging Layer Security (MLS)** protocol, standardized as RFC 9420 by the IETF.
**Key properties:**
@@ -74,7 +74,7 @@ quicproquo uses the **Messaging Layer Security (MLS)** protocol, standardized as
**Cost of group operations:**
| Operation | Signal (Sender Keys) | Matrix (Megolm) | MLS (quicproquo) |
| Operation | Signal (Sender Keys) | Matrix (Megolm) | MLS (quicprochat) |
|---|---|---|---|
| Add member | O(n) Sender Key distributions | O(n) Megolm session shares | O(log n) tree update |
| Remove member | O(n) Sender Key rotations | O(n) new Megolm session | O(log n) tree update |
@@ -87,7 +87,7 @@ quicproquo uses the **Messaging Layer Security (MLS)** protocol, standardized as
The transport layer determines how encrypted payloads reach the server and how client-server authentication is performed.
| Property | Signal | Matrix | quicproquo |
| Property | Signal | Matrix | quicprochat |
|---|---|---|---|
| **Transport protocol** | TLS over TCP (HTTP/2) | HTTPS (TLS over TCP) | QUIC (UDP) + TLS 1.3 |
| **Multiplexing** | HTTP/2 stream multiplexing | HTTP/1.1 or HTTP/2 | Native QUIC stream multiplexing |
@@ -106,7 +106,7 @@ QUIC eliminates TCP head-of-line blocking, which is particularly important for a
The serialisation format determines the overhead of encoding and decoding messages, the type safety of the wire format, and the feasibility of schema evolution.
| Property | Signal (Protobuf) | Matrix (JSON) | quicproquo (Cap'n Proto) |
| Property | Signal (Protobuf) | Matrix (JSON) | quicprochat (Cap'n Proto) |
|---|---|---|---|
| **Format** | Binary, schema-defined | Text, schema-optional (JSON Schema exists but is not enforced by the wire format) | Binary, schema-defined |
| **Deserialization cost** | Requires a decode pass (allocates and copies) | Requires a parse pass (allocates, copies, and handles UTF-8) | **Zero-copy**: the wire bytes are the in-memory representation. Readers traverse pointers in-place. |
@@ -118,7 +118,7 @@ The serialisation format determines the overhead of encoding and decoding messag
**Why Cap'n Proto over Protobuf?**
While Protobuf is a reasonable choice (and Signal uses it successfully), Cap'n Proto provides two features that are particularly valuable for quicproquo:
While Protobuf is a reasonable choice (and Signal uses it successfully), Cap'n Proto provides two features that are particularly valuable for quicprochat:
1. **Zero-copy deserialization** eliminates a class of allocation and performance overhead. In a messaging system that processes many small messages, avoiding deserialization copies adds up.
2. **Built-in RPC** means that Cap'n Proto is both the serialisation format and the RPC framework. There is no need for a separate gRPC or HTTP layer. The same `.capnp` schema file defines both the data structures and the service interface.
@@ -128,7 +128,7 @@ While Protobuf is a reasonable choice (and Signal uses it successfully), Cap'n P
## Summary comparison table
| Dimension | Signal | Matrix | quicproquo |
| Dimension | Signal | Matrix | quicprochat |
|---|---|---|---|
| **1:1 encryption** | Double Ratchet (FS + PCS) | Olm / Double Ratchet (FS + PCS) | MLS (FS + PCS) |
| **Group encryption** | Sender Keys (FS only) | Megolm (FS only) | MLS (FS + PCS) |
@@ -143,13 +143,13 @@ While Protobuf is a reasonable choice (and Signal uses it successfully), Cap'n P
---
## What quicproquo gives up
## What quicprochat gives up
No design is without trade-offs. Compared to Signal and Matrix, quicproquo:
No design is without trade-offs. Compared to Signal and Matrix, quicprochat:
- **Has no federation.** A single server per deployment means no decentralized architecture. This is a deliberate simplification -- federation adds significant complexity and metadata exposure.
- **Is less mature.** Signal and Matrix have years of production hardening, formal security audits, and battle-tested implementations. quicproquo is in early development.
- **Has a smaller ecosystem.** Signal and Matrix have extensive client libraries, bridges, and integrations. quicproquo is a standalone Rust implementation.
- **Is less mature.** Signal and Matrix have years of production hardening, formal security audits, and battle-tested implementations. quicprochat is in early development.
- **Has a smaller ecosystem.** Signal and Matrix have extensive client libraries, bridges, and integrations. quicprochat is a standalone Rust implementation.
- **Requires MLS client complexity.** MLS clients must maintain a ratchet tree, process Commits, and handle epoch transitions. This is more complex than a simple symmetric ratchet (Sender Keys / Megolm), though the complexity buys post-compromise security.
---
@@ -158,6 +158,6 @@ No design is without trade-offs. Compared to Signal and Matrix, quicproquo:
- [Design Decisions Overview](overview.md) -- index of all ADRs
- [ADR-002: Cap'n Proto over MessagePack](adr-002-capnproto.md) -- serialisation format choice
- [Protocol Layers Overview](../protocol-layers/overview.md) -- how quicproquo's layers compose
- [Protocol Layers Overview](../protocol-layers/overview.md) -- how quicprochat's layers compose
- [MLS (RFC 9420)](../protocol-layers/mls.md) -- deep dive into the MLS protocol layer
- [Architecture Overview](../architecture/overview.md) -- system-level architecture