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

Remove Noise protocol references from wiki docs and tests

Browse Source 
Delete 8 Noise-specific documentation pages (noise-xx.md,
transport-keys.md, adr-001/003/006, framing-codec.md) and update
~30 remaining wiki pages to reflect QUIC+TLS as the sole transport.
Remove obsolete Noise-based integration tests (auth_service.rs,
mls_group.rs). Code-side Noise removal was done in f334ed3.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Christian Nennemann
2026-02-22 08:25:23 +01:00
parent f334ed3d43
commit 9fdb37876a
36 changed files with 125 additions and 2201 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/src/wire-format/overview.md
View File

@@ -6,22 +6,22 @@ This section documents the serialisation pipeline that transforms application-le
## Serialisation pipeline
Data flows through four stages on the send path. The receive path reverses the order.
Data flows through three stages on the send path. The receive path reverses the order.
```text
Stage 1 Stage 2 Stage 3 Stage 4
-------- -------- -------- --------
Application Cap'n Proto Length-prefixed Transport
data serialisation framing encryption
Stage 1 Stage 2 Stage 3
-------- -------- --------
Application Cap'n Proto Transport
data serialisation encryption
ParsedEnvelope capnp::serialize [u32 LE len][payload] Noise ChaCha20-Poly1305
or RPC call (zero-copy bytes) or QUIC/TLS 1.3
RPC call capnp::serialize QUIC/TLS 1.3
(zero-copy bytes)
| | | |
v v v v
Rust structs Canonical byte Framed byte stream Encrypted
& method representation ready for transport ciphertext
invocations (no deserialization on the wire
| | |
v v v
Rust structs Canonical byte Encrypted
& method representation ciphertext
invocations (no deserialization on the wire
needed on receive)
```
@@ -45,42 +45,15 @@ The wire representation consists of:
Cap'n Proto's canonical form is deterministic for a given message, which makes it suitable for signing: two implementations that build the same logical message will produce identical bytes.
### Stage 3: Length-prefixed framing
### Stage 3: Transport encryption
Before the serialised bytes enter the transport, they are wrapped in a length-prefixed frame:
The serialised bytes are encrypted by the QUIC/TLS 1.3 transport layer. The QUIC transport uses native QUIC stream framing, which provides its own length delimitation. Cap'n Proto RPC over QUIC relies on the `capnp-rpc` crate's built-in stream adapter.
```text
+----------------------------+--------------------------------------+
| length (4 bytes, LE u32) | payload (length bytes) |
+----------------------------+--------------------------------------+
```
| Transport | Encryption | Authentication |
|---|---|---|
| **QUIC + TLS 1.3** | AES-128-GCM or ChaCha20-Poly1305 (negotiated by TLS) | Server cert (rustls/quinn) |
The length prefix is encoded as a **little-endian** 32-bit unsigned integer. Little-endian was chosen for consistency with Cap'n Proto's own segment table encoding, which also uses little-endian integers. This avoids byte-order confusion when the same buffer contains both framing headers and Cap'n Proto data.
The maximum payload size is **65,535 bytes**, matching the Noise protocol's maximum message size. Frames exceeding this limit are rejected as protocol violations. See [Framing Codec](framing-codec.md) for the full `LengthPrefixedCodec` implementation.
> **Note:** This framing stage applies only to the Noise transport path. The QUIC transport uses native QUIC stream framing, which provides its own length delimitation. Cap'n Proto RPC over QUIC relies on the `capnp-rpc` crate's built-in stream adapter rather than `LengthPrefixedCodec`.
### Stage 4: Transport encryption
The framed byte stream is encrypted by the transport layer:
| Transport | Encryption | Authentication | When Used |
|---|---|---|---|
| **Noise\_XX over TCP** | ChaCha20-Poly1305 (per-session key from XX handshake) | Mutual, via static X25519 keys | M1 stack, peer-to-peer, integration tests |
| **QUIC + TLS 1.3** | AES-128-GCM or ChaCha20-Poly1305 (negotiated by TLS) | Server cert (rustls/quinn) | M3+ primary transport |
In both cases, the transport layer treats the payload as opaque bytes. It does not inspect or interpret the Cap'n Proto content. This clean separation means the serialisation format can evolve independently of the transport.
---
## Little-endian framing rationale
Cap'n Proto uses little-endian encoding for its segment table (the header that precedes each serialised message). The `LengthPrefixedCodec` uses the same byte order for its 4-byte length field. This consistency means:
1. A developer inspecting a raw byte dump sees uniform endianness throughout.
2. On little-endian architectures (x86-64, AArch64 in LE mode), both the framing header and the Cap'n Proto header can be read without byte-swapping.
3. There is no risk of accidentally mixing big-endian and little-endian headers in the same stream.
The transport layer treats the payload as opaque bytes. It does not inspect or interpret the Cap'n Proto content. This clean separation means the serialisation format can evolve independently of the transport.
---
@@ -95,8 +68,6 @@ The Cap'n Proto schemas that define the wire-level messages are documented on de
| `schemas/delivery.capnp` | [Delivery Schema](delivery-schema.md) | Delivery Service RPC interface |
| `schemas/node.capnp` | [NodeService Schema](node-service-schema.md) | Unified node RPC (current) |
The length-prefixed framing codec that wraps serialised messages is documented at [Framing Codec](framing-codec.md).
---
## Further reading
@@ -104,4 +75,3 @@ The length-prefixed framing codec that wraps serialised messages is documented a
- [Architecture Overview](../architecture/overview.md) -- system-level view of how services compose
- [Protocol Layers Overview](../protocol-layers/overview.md) -- how transport, framing, and E2E encryption stack
- [ADR-002: Cap'n Proto over MessagePack](../design-rationale/adr-002-capnproto.md) -- why Cap'n Proto was chosen
- [ADR-003: RPC Inside the Noise Tunnel](../design-rationale/adr-003-rpc-inside-noise.md) -- why RPC runs inside the encrypted channel