Files

Chris Nennemann 853ca4fec0 chore: rename project quicnprotochat -> quicproquo (binaries: qpq)

Rename the entire workspace:
- Crate packages: quicnprotochat-{core,proto,server,client,gui,p2p,mobile} -> quicproquo-*
- Binary names: quicnprotochat -> qpq, quicnprotochat-server -> qpq-server,
  quicnprotochat-gui -> qpq-gui
- Default files: *-state.bin -> qpq-state.bin, *-server.toml -> qpq-server.toml,
  *.db -> qpq.db
- Environment variable prefix: QUICNPROTOCHAT_* -> QPQ_*
- App identifier: chat.quicnproto.gui -> chat.quicproquo.gui
- Proto package: quicnprotochat.bench -> quicproquo.bench
- All documentation, Docker, CI, and script references updated

HKDF domain-separation strings and P2P ALPN remain unchanged for
backward compatibility with existing encrypted state and wire protocol.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-01 20:11:51 +01:00

8.8 KiB

Raw Blame History

Architecture Overview

quicproquo is an end-to-end encrypted group messaging system built in Rust. This page describes the high-level architecture: the services that compose the 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:

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.
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 as a unified NodeService interface.

See Service Architecture for per-method details, connection lifecycle, and the long-polling fetchWait mechanism.

Identity Key Model

Each quicproquo client holds a single Ed25519 signing keypair that serves as its long-term identity:

                    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  │
   │                                                  │
   └──────────────────────────────────────────────────┘

Property	Ed25519 (MLS)
Curve	Ed25519 (Twisted Edwards)
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

For details on the cryptographic properties, see Ed25519 Identity Keys.

System Diagram

  ┌─────────────────┐                                      ┌─────────────────┐
  │   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()                                                                 │
  │                                                                            │
  └────────────────────────────────────────────────────────────────────────────┘

Key observations:

The server never sees plaintext message content. MLS ciphertext is opaque to the DS -- it merely routes by recipientKey.
KeyPackages are single-use (RFC 9420 requirement). The AS atomically removes a KeyPackage on fetch to enforce this invariant.
QUIC + TLS 1.3 is the sole transport layer.

Protocol Layering

The system stacks three protocol layers:

Transport -- QUIC + TLS 1.3. Provides confidentiality, integrity, and server authentication. See Protocol Stack.
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.
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).

An optional fourth layer -- the hybrid KEM envelope (X25519 + ML-KEM-768) -- wraps MLS payloads for post-quantum confidentiality at the per-message level. See Hybrid KEM.

Crate Map

The implementation is split across four 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

See Crate Responsibilities for a full breakdown and dependency diagram.

8.8 KiB Raw Blame History