feat: add post-quantum hybrid KEM + SQLCipher persistence
Feature 1 — Post-Quantum Hybrid KEM (X25519 + ML-KEM-768): - Create hybrid_kem.rs with keygen, encrypt, decrypt + 11 unit tests - Wire format: version(1) | x25519_eph_pk(32) | mlkem_ct(1088) | nonce(12) | ct - Add uploadHybridKey/fetchHybridKey RPCs to node.capnp schema - Server: hybrid key storage in FileBackedStore + RPC handlers - Client: hybrid keypair in StoredState, auto-wrap/unwrap in send/recv/invite/join - demo-group runs full hybrid PQ envelope round-trip Feature 2 — SQLCipher Persistence: - Extract Store trait from FileBackedStore API - Create SqlStore (rusqlite + bundled-sqlcipher) with encrypted-at-rest SQLite - Schema: key_packages, deliveries, hybrid_keys tables with indexes - Server CLI: --store-backend=sql, --db-path, --db-key flags - 5 unit tests for SqlStore (FIFO, round-trip, upsert, channel isolation) Also includes: client lib.rs refactor, auth config, TOML config file support, mdBook documentation, and various cleanups by user. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
139
docs/src/getting-started/building.md
Normal file
139
docs/src/getting-started/building.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Building from Source
|
||||
|
||||
This page covers compiling the workspace, running the test suite, and understanding the build-time Cap'n Proto code generation step.
|
||||
|
||||
---
|
||||
|
||||
## Building the workspace
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
cargo build --workspace
|
||||
```
|
||||
|
||||
This compiles all four crates:
|
||||
|
||||
| Crate | Type | Purpose |
|
||||
|---|---|---|
|
||||
| `quicnprotochat-core` | library | Crypto primitives, Noise transport, MLS `GroupMember` state machine, frame codec |
|
||||
| `quicnprotochat-proto` | library | Cap'n Proto schemas, generated types, envelope serialisation helpers |
|
||||
| `quicnprotochat-server` | binary | Unified Authentication + Delivery Service (`NodeService`) |
|
||||
| `quicnprotochat-client` | binary | CLI client with subcommands (`ping`, `register`, `send`, `recv`, etc.) |
|
||||
|
||||
For a release build with LTO, symbol stripping, and single codegen unit:
|
||||
|
||||
```bash
|
||||
cargo build --workspace --release
|
||||
```
|
||||
|
||||
The release profile is configured in the workspace `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
opt-level = 3
|
||||
lto = "thin"
|
||||
codegen-units = 1
|
||||
strip = "symbols"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running the test suite
|
||||
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
The test suite includes:
|
||||
|
||||
- **`quicnprotochat-proto`**: Round-trip serialisation tests for Cap'n Proto `Envelope` messages (Ping, Pong, corrupted-input error handling).
|
||||
- **`quicnprotochat-core`**: Two-party MLS round-trip (`create_group` / `add_member` / `send_message` / `receive_message`), group ID lifecycle assertions.
|
||||
- **`quicnprotochat-client`**: Integration tests for MLS group operations and auth service interactions (require a running server or use in-process mocks).
|
||||
|
||||
To run tests for a single crate:
|
||||
|
||||
```bash
|
||||
cargo test -p quicnprotochat-core
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cap'n Proto code generation
|
||||
|
||||
The `quicnprotochat-proto` crate does not contain hand-written Rust types for wire messages. Instead, its `build.rs` script invokes the `capnp` compiler at build time to generate Rust source from the `.capnp` schema files.
|
||||
|
||||
### How it works
|
||||
|
||||
1. `build.rs` locates the workspace-root `schemas/` directory (two levels above `crates/quicnprotochat-proto/`).
|
||||
2. It invokes `capnpc::CompilerCommand` on all four schema files:
|
||||
- `schemas/envelope.capnp` -- top-level wire envelope with `MsgType` discriminant
|
||||
- `schemas/auth.capnp` -- `AuthenticationService` RPC interface
|
||||
- `schemas/delivery.capnp` -- `DeliveryService` RPC interface
|
||||
- `schemas/node.capnp` -- `NodeService` RPC interface (unified AS + DS)
|
||||
3. The generated Rust source is written to `$OUT_DIR` (Cargo's build output directory).
|
||||
4. `src/lib.rs` includes the generated code via `include!(concat!(env!("OUT_DIR"), "/envelope_capnp.rs"))` and similar macros for each schema.
|
||||
|
||||
### Rebuild triggers
|
||||
|
||||
The `build.rs` script emits `cargo:rerun-if-changed` directives for each schema file. If you modify a `.capnp` file, the next `cargo build` will automatically re-run code generation.
|
||||
|
||||
### Schema include path
|
||||
|
||||
The `src_prefix` is set to the `schemas/` directory so that inter-schema imports (e.g., `using Auth = import "auth.capnp".Auth;` inside `node.capnp`) resolve correctly.
|
||||
|
||||
### Design constraints of quicnprotochat-proto
|
||||
|
||||
The proto crate is intentionally restricted:
|
||||
|
||||
- **No crypto** -- key material never enters this crate.
|
||||
- **No I/O** -- callers own the transport; this crate only converts bytes to types and back.
|
||||
- **No async** -- pure synchronous data-layer code.
|
||||
|
||||
For details on the wire format, see the [Wire Format Reference](../wire-format/overview.md).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `capnp` binary not found
|
||||
|
||||
**Symptom:**
|
||||
|
||||
```
|
||||
Cap'n Proto schema compilation failed.
|
||||
Is `capnp` installed? (apt-get install capnproto / brew install capnp)
|
||||
```
|
||||
|
||||
**Fix:** Install the Cap'n Proto compiler for your platform. See [Prerequisites](prerequisites.md) for platform-specific instructions.
|
||||
|
||||
Verify it is on your `PATH`:
|
||||
|
||||
```bash
|
||||
which capnp
|
||||
capnp --version
|
||||
```
|
||||
|
||||
### Version mismatch between `capnp` CLI and `capnpc` Rust crate
|
||||
|
||||
The workspace uses `capnpc = "0.19"` (the Rust bindings for the Cap'n Proto compiler). If your system `capnp` binary is significantly older or newer, generated code may be incompatible. The recommended approach is to use a `capnp` binary whose major version matches the `capnpc` crate version. On most systems, the package manager version is compatible.
|
||||
|
||||
### linker errors on macOS with Apple Silicon
|
||||
|
||||
If you see linker errors related to `ring` or `aws-lc-sys` (used transitively by `rustls`), ensure you have Xcode Command Line Tools installed:
|
||||
|
||||
```bash
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
### Slow first build
|
||||
|
||||
The first build downloads and compiles all dependencies (including `openmls`, `quinn`, `rustls`, `capnp-rpc`, etc.). This can take several minutes depending on your hardware. Subsequent builds are incremental and much faster.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Running the Server](running-the-server.md) -- start the NodeService endpoint
|
||||
- [Running the Client](running-the-client.md) -- CLI subcommands and usage examples
|
||||
- [Docker Deployment](docker.md) -- build and run in containers
|
||||
Reference in New Issue
Block a user