snaart/phantom_protocol
GitHub: snaart/phantom_protocol
一个后量子安全传输 SDK，为应用提供经过身份验证的加密字节流管道，适用于构建 VPN、消息传递等安全网络产品的基础设施。
Stars: 1 | Forks: 0
# Phantom Protocol
[](https://crates.io/crates/phantom-protocol)
[](https://docs.rs/phantom-protocol)
[](https://github.com/snaart/phantom_protocol/actions/workflows/ci.yml)
[](LICENSE)
Rust 中的后量子安全 L4/L6 通用传输框架。
Phantom Protocol 是一个 **SDK** —— 一个用于构建安全网络产品（VPN、消息传递等）的基础组件，而不是一个终端用户应用程序。它为应用程序提供了一个经过身份验证的、机密的、后量子安全的字节管道，将混合的经典加 PQ 握手（X25519 + ML-KEM-768 KEM，Ed25519 + ML-DSA-65 签名 —— FIPS 203 / FIPS 204，纯 Rust 实现）与传输层（TCP / WebSocket 会话和原生可靠 UDP 传输 (PhantomUDP)）配对，此外还有 WASI / 嵌入式字节流成帧。通过 UniFFI 提供跨语言绑定（Python、Swift、Kotlin、C）；原生 WASM 目标；用于 no_std 的裸机 `EmbeddedLeg`。（计划提供一种 DPI 模仿传输模式，但目前尚未构建。）
## 安装
已在 crates.io 上发布为 [`phantom-protocol`](https://crates.io/crates/phantom-protocol)
（导入路径为 `phantom_protocol`）：
```
[dependencies]
phantom-protocol = "0.1"
```
或者 `cargo add phantom-protocol`。API 文档：。
## 核心亮点
- **混合后量子握手** —— X25519 + ML-KEM-768 KEM，Ed25519 + ML-DSA-65 签名。两部分都必须验证。纯 Rust RustCrypto 原语 —— 加密路径中没有 C 绑定，因此整个握手可以在原生、移动设备和 `wasm32` 上编译。（裸机 `thumbv7em` 将 `std` 限制为仅成帧传输 —— 参见[状态与限制](#status--limitations)。）
- **0-RTT 恢复** —— AEAD 封装的早期数据（≤ 16 KiB）被折叠到单个 `ClientHello` 中，通过消耗 `SessionCache` 票据进行一次性防重放，并在票据未知/过期或 blob 无法打开时尽最大努力回退到 1-RTT 握手。
- **会话中重新加密 (rekey)** —— HKDF 棘轮，`REKEY` 标志 + 每个数据包的 `epoch`。
- **传输** —— `PhantomSession` 如今可通过 **TCP** 和 **WebSocket** 运行经过身份验证的会话（此外还有 WASI 和 Embedded 作为成帧链路）。原生可靠 UDP 传输 (**PhantomUDP**) 正在开发中，以增加多路径、拥塞控制和连接迁移，且无需额外的加密层（参见[状态与限制](#status--limitations)）。先前实验性的 KCP / FakeTLS 链路以及未使用的 `TransportLeg` 多路径 trait 已被移除，等待该工作完成；FakeTLS 风格的 HTTP 流量模仿将作为一个专用模式重新引入。
- **多流** —— 严格优先级调度器，每个流的 `WINDOW_UPDATE` 流控制，受 BBRv2 启发的步调（启动 / 排空 / ProbeBW / ProbeRTT / FastRecovery）。
- **抗 DoS 握手** —— 无状态 HMAC-SHA-256 cookie（每小时轮换主密钥）+ 自适应 blake3 工作量证明（负载分级难度 0–16）。
- **每流防重放保护** —— RFC 4303 §3.4.3 滑动窗口位图，默认 1024 位，在 AEAD 验证 _之后_ 检查。
- **可观测性** —— OpenTelemetry 指标 + 跟踪（可选的 `telemetry-otel` 功能）。无锁热路径原子操作（≤ 2.5 ns / 次调用），OTLP/gRPC 推送到任何后端（Datadog、Honeycomb、Grafana Cloud、通过 OTel Collector 自托管）。`docs/observability/` 中提供了预构建的 Grafana 仪表板 + Prometheus 告警规则。
- **SLSA-3 构建出处** —— 每个发布工件上都有 OIDC 证明。
- **跨平台** —— 每个 CI 目标都是硬性关卡（Linux x4、macOS x2、iOS x2、Windows x2、wasm32-unknown-unknown、wasm32-wasip2、thumbv7em-none-eabihf）；**没有 `allow_failure` 项**。
## 快速开始
### 构建 / 测试 / lint
```
cargo build --manifest-path core/Cargo.toml
cargo test --manifest-path core/Cargo.toml --lib
cargo clippy --manifest-path core/Cargo.toml --lib -- -D warnings
cargo fmt --manifest-path core/Cargo.toml --check
```
Loopback 集成测试受 `#[ignore]` 控制：
```
cargo test --manifest-path core/Cargo.toml --test tcp_integration -- --ignored
```
更多命令（基准测试、模糊测试、miri、跨目标、嵌入式）在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
### 最小化客户端 / 服务端
必须固定服务端身份 —— `connect_with_transport` 需要一个 `HybridVerifyingKey`；没有跳过路径（安全不变量 1）。
```
use phantom_protocol::api::{PhantomListener, PhantomSession, TcpSessionTransport};
use phantom_protocol::crypto::hybrid_sign::HybridVerifyingKey;
use tokio::net::TcpStream;
// ── Server ────────────────────────────────────────────────────────────────
let listener = PhantomListener::bind("127.0.0.1:0".to_string()).await?;
let server_addr = listener.local_addr();
let pinned_key = listener.verifying_key_bytes(); // share out-of-band
tokio::spawn(async move {
let outcome = listener.accept().await?;
let session = outcome.session();
let req = session.recv().await?;
session.send(b"hello, post-quantum world".to_vec()).await?;
Ok::<_, phantom_protocol::CoreError>(())
});
// ── Client (one-shot helper used by mobile / FFI consumers) ───────────────
let session = phantom_protocol::api::session::connect_pinned(
"127.0.0.1".into(), 4242, pinned_key,
).await?;
session.send(b"ping".to_vec()).await?;
let reply = session.recv().await?;
// ── Or, explicit transport (TCP / WebSocket today; WASI / Embedded framing) ─
let stream = TcpStream::connect(&server_addr).await?;
let transport = TcpSessionTransport::new(stream);
let key = HybridVerifyingKey::from_bytes(&pinned_key)?;
let session = PhantomSession::connect_with_transport(&server_addr, transport, key);
```
可运行的形式：[`core/examples/loopback_demo.rs`](core/examples/loopback_demo.rs)、
[`core/examples/embedded_demo.rs`](core/examples/embedded_demo.rs)、
[`core/examples/crypto_bench.rs`](core/examples/crypto_bench.rs)。
## 密码学
| 角色 | 原语 | 标准 / 来源 |
| --- | --- | --- |
| KEM | X25519 + ML-KEM-768 | RFC 7748 + FIPS 203 (RustCrypto `ml-kem`) |
| 签名 | Ed25519 + ML-DSA-65 | FIPS 186-5 + FIPS 204 (RustCrypto `ml-dsa`) |
| AEAD（主要） | AES-256-GCM | `ring`，硬件加速 (AES-NI / ARMv8 PMULL) |
| AEAD（备用） | ChaCha20-Poly1305 | RFC 8439，在没有 AES 内在函数 (intrinsics) 时自动选择 |
| KDF | HKDF-SHA-256 | RFC 5869 |
| Hash / MAC | SHA-256, HMAC-SHA-256, blake3 (keyed) | FIPS 180-4 / FIPS 198-1 + non-FIPS |
阶段 5.1 将 PQ 原语从绑定 C 的 `pqcrypto-*` crate 迁移到了 RustCrypto 的 FIPS-203 / FIPS-204 实现。该 crate 可以在没有 C 绑定的情况下在 `wasm32-unknown-unknown` 和 `thumbv7em-none-eabihf` 上编译。
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ Public API (core/src/api/) │
│ PhantomSession · PhantomListener · TcpSessionTransport │
├─────────────────────────────────────────────────────────────────┤
│ Transport (core/src/transport/) │
│ Handshake{Client,Server} · Session · scheduler · pacer · paths │
│ api/{tcp,udp}_transport · legs/{websocket, wasi, embedded} │
├─────────────────────────────────────────────────────────────────┤
│ Crypto (core/src/crypto/) │
│ hybrid_kem · hybrid_sign · adaptive_crypto · kdf · pow · rng │
├─────────────────────────────────────────────────────────────────┤
│ Security (core/src/security/) │
│ ReplayWindow · ReplayProtection │
├─────────────────────────────────────────────────────────────────┤
│ Runtime (core/src/runtime/) │
│ TokioRuntime (native) · WasmRuntime · (EmbeddedRuntime TODO) │
└─────────────────────────────────────────────────────────────────┘
```
正式的架构规范是
[`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)；
统一的网络协议（包括 0-RTT）是
[`docs/protocol/PROTOCOL.md`](docs/protocol/PROTOCOL.md)。各子系统的
安全不变量记录在
[`docs/security/threat-model.md`](docs/security/threat-model.md) 中。
## 传输特性
- **单一统一的网络协议。** 一个 `PacketHeader`（45 字节，带有固定的 `version` 字节 = `WIRE_VERSION`）封装在原始的 `PhantomPacket`（`header` + `payload` + TLV 预留空间 `extensions`）中 —— 没有 `VersionedPacket` 枚举，没有按会话进行的网络协议版本协商。`epoch`、`REKEY`、`PATH_VALIDATION`、`COALESCED`、`WINDOW_UPDATE` 标志都存在于同一个 header 中；接收路径直接反序列化 `PhantomPacket` 并丢弃任何 `header.version` 不一致的数据帧。握手消息是原始的 borsh 结构体（没有封装）：一个 `ClientHello`（其中折叠了可选的 0-RTT `early_data` blob），一个 `ServerHello`，一个 `HelloRetryRequest`，一个以 `protocol_variant` 开头并带有签名的 `HandshakeTranscript`。固定的 `PROTOCOL_VERSION` / `WIRE_VERSION` 字节是防篡改校验锚点，也是未来刻意进行版本升级的钩子。
- **路径验证原语（内部）。** `PathRegistry` + 常数时间挑战/响应；路径 0 已预先验证，辅助路径的状态转换为 `Unvalidated → Validating → Validated`。这是未来连接迁移的基础构建块；它尚未接入实际的多路径数据平面。
## 性能
在 **Apple M1 Pro (8P + 2E, 16 GiB), macOS 26.0, rustc 1.93.0，带 ARMv8 AES-PMULL 的 `ring`**（快照日期 2026-05-17，criterion `--quick`，默认 `target-cpu`）上的参考数据：
| 路径 | 数值 | 备注 |
| --- | --- | --- |
| 混合 PQ 握手 (固定) | **1.06 ms** / ~945 conn/s/core | 完整的生产路径；在 8 个 P 核心上聚合约为 7,500 次/秒的冷握手 |
| AEAD 加密, 64 KiB | **4.67 GiB/s/core** (13.1 µs) | 带有 header-AAD + 重放窗口的 `encrypt_packet` |
| AEAD 解密, 16 KiB | **4.68 GiB/s/core** | 相同路径 |
| 1 MiB 往返 | **391.5 µs** → **5.0 GiB/s** | 加密 + 解密 |
| 裸 AES-256-GCM (`ring`) | 在 64 KiB 时 **5,514 MiB/s** | 裸加密，无成帧 |
| ChaCha20-Poly1305 (软件) | 在 1 MiB 时 1,555 MiB/s | 在此部分上比 AES 慢约 3.5 倍 |
| ClientHello 解析 + cookie + 声誉 | **4.60 µs** / ~217K/s/core | DoS 网关热路径 |
| `kem_encapsulate` | 80.7 µs | 混合 X25519 + ML-KEM-768 |
| `hybrid_sign` / `hybrid_verify` | 310.0 µs / 131.6 µs | Ed25519 + ML-DSA-65 |
`RUSTFLAGS="-C target-cpu=native"` 通常会增加 +5–10%；通过 `cargo-pgo` 进行 PGO 在稳定的工作负载上还能增加 +5–10%。发布配置（`opt-level=3`、`lto="fat"`、`codegen-units=1`、`panic="abort"`）在工作空间根目录中设置。带有 AES-NI 的 Linux x86_64 也处于类似的水平。完整的方法论和生产环境调优（`bbr`、`fq`、`LimitNOFILE`、分配器交换、CPU 绑定）在
[`BENCHMARKS.md`](BENCHMARKS.md) 和 [`docs/operations/perf-tuning.md`](docs/operations/perf-tuning.md) 中。
## 部署
### `phantom-server`（参考二进制文件）
生产级嵌入器。自动加载或创建持久化的 `HybridSigningKey`，将 OTLP 遥测数据推送到 OTel Collector / SaaS 后端，通过 10s 排空处理 SIGTERM / SIGINT。
| 标志 | 环境变量 | 默认值 |
| --- | --- | --- |
| `--bind` | `PHANTOM_BIND` | `0.0.0.0:4242` |
| `--otlp-endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` |
| `--otel-service-name` | `OTEL_SERVICE_NAME` | `phantom-server` |
| `--otel-trace-sample-ratio` | `OTEL_TRACES_SAMPLER_ARG` | `0.01` |
| `--signing-key-file` | `PHANTOM_SIGNING_KEY_FILE` | `/etc/phantom-server/signing.key` (0600，自动创建) |
| `--log-json` | `PHANTOM_LOG_JSON` | `false` |
| `--log-filter` | `RUST_LOG` | `info,phantom_protocol=debug` |
```
cargo run --manifest-path server/Cargo.toml -- \
--bind 0.0.0.0:4242 \
--otlp-endpoint http://otel-collector:4317
```
### Docker / docker-compose
多阶段 `Dockerfile`（`rust:1-slim-bookworm` → `debian:bookworm-slim`），非 root 用户 `phantom` UID 65532，EXPOSE 4242 + 9090，签名密钥卷位于 `/etc/phantom-server`。`docker-compose.yml` 已准备好运行，带有命名卷和 TCP 健康检查。
--msg hello
cargo run --manifest-path cli/Cargo.toml -- version
```
## 平台与语言绑定
### 交叉编译矩阵 (`.github/workflows/cross.yml`)
| 目标 | 状态 |
| --- | --- |
| `x86_64-unknown-linux-gnu` / `aarch64-unknown-linux-gnu` / `aarch64-unknown-linux-musl` | 硬性关卡 |
| `x86_64-apple-darwin` / `aarch64-apple-darwin` | 硬性关卡 |
| `aarch64-apple-ios` (设备) / `aarch64-apple-ios-sim` | 硬性关卡 |
| `x86_64-pc-windows-msvc` / `aarch64-pc-windows-msvc` | 硬性关卡 |
| `wasm32-unknown-unknown` | 硬性关卡 (阶段 3.3 / 3.5) |
| `thumbv7em-none-eabihf` | 硬性关卡 (阶段 3.6；`--no-default-features --features embedded,no-std`) |
| `wasm32-wasip2` | 硬性关卡 (编译 + 主机往返；WASI 仅限客户端成帧 —— 参见 [`docs/operations/wasi.md`](docs/operations/wasi.md)) |
### 语言绑定 (`tests/bindings/`)
| 绑定 | 成熟度 | 备注 |
| --- | --- | --- |
| **Swift** | 生产形态 | 通过 UniFFI 0.29 自动生成；iOS XCFramework 配方在 [`docs/operations/mobile.md`](docs/operations/mobile.md) 中 |
| **Kotlin** | 生产形态 | 自动生成；Android NDK + Gradle `jniLibs` 配方在 `mobile.md` 中 |
| **Python** | UniFFI 接口自动生成 | 演示测试工具 `tests/run_test.py` 已过期，且引用了以前的 API |
| **C** | 实验性 | **手工整理的**头文件 —— UniFFI 0.29 没有 C 生成器。涵盖了 `connect_pinned`，但未涵盖 `HybridSigningKey` 或 `PhantomConfig`。README 建议改用 Swift / Kotlin / Python |
| **WASM (浏览器)** | 附带演示 | [`examples/wasm-demo/`](examples/wasm-demo/) 与 [`docs/operations/wasm.md`](docs/operations/wasm.md) 配对；使用 `WebSocketLeg` + `WasmRuntime` |
重新生成：`tests/bindings/{generate_swift,generate_kotlin,generate_c}.sh`。
### 嵌入式（`embedded` 功能，默认关闭）
在裸机 `thumbv7em-none-eabihf` 上，Phantom Protocol **仅**提供成帧传输 —— `EmbeddedLeg` 及其长度前缀编解码器。PQ 握手、`PhantomSession`、加密原语和 `TokioRuntime` 是 `std` 受限的，因此在那里**不会**被构建；裸机嵌入器需要自带加密/握手驱动程序，并通过该链路运行它。PQ-on-bare-metal 已被排除在 1.0 范围之外（参见[状态与限制](#status--limitations)）。
`EmbeddedLeg` 包装了任何 `embedded-io-async = 0.6` 字节流（UART、USB-CDC 等），带有 4 字节的大端序 (BE) 长度前缀成帧 —— 网络数据格式与 `TcpSessionTransport` 相同。纯 Rust，no_std + alloc，与目标架构无关（在主机 x86_64 上构建单元测试，_也_可以在裸机 `thumbv7em-none-eabihf` 上构建）。通过 `impl_embedded_session_transport!` 宏为每个 `(R, W)` 实现 `SessionTransport`。当 `getrandom` 不可用时，`RngProvider` trait 可用于注入硬件 RNG。[`core/examples/embedded_demo.rs`](core/examples/embedded_demo.rs) **在主机上** (std) 通过模拟字节流运行完整会话，演示了该链路 —— 而不是裸机握手。
## 安全性
完整的威胁模型、缓解措施和披露策略位于
[`SECURITY.md`](SECURITY.md) 和
[`docs/security/threat-model.md`](docs/security/threat-model.md) 中。要点：
- **强制固定服务端身份** —— `connect_with_transport` 需要一个 `HybridVerifyingKey`；没有跳过路径。
- **前向保密** —— 每次握手的临时混合 KEM + 基于 HKDF 的会话中期密钥更新（epoch 在 `u8::MAX` 处饱和，永不溢出）。
- **防重放拒绝发生在 AEAD 验证 _之后_** —— RFC 4303 §3.4.3 滑动窗口位图，按流划分。
- **抗降级** —— 固定的协议版本和 `protocol_variant` 都在握手记录中进行了签名；剥离了 `ENCRYPTED` 的握手后数据包将被丢弃。
- **0-RTT 防重放** —— `SessionCache::try_resume` 在首次查找时即消耗恢复票据；超大 / 过期 / AEAD 验证失败的早期数据会尽最大努力处理，绝不会对握手造成致命影响。
- **AEAD nonce 耗尽保护** —— 当达到 `AEAD_MAX_INVOCATIONS = 2^48` 时抛出 `CryptoError::NonceExhausted`。
- **在所有包含密钥的结构上使用 `ZeroizeOnDrop`**；在整个 crate 范围内 `#![deny(unsafe_code)]`，只有一个经过审计的可选启用项（用于 libc GSO / `recvmmsg` 的 `transport/udp_transport.rs`）。
- 取消安全审计：在所有 `tokio::select!` 站点未发现 bug。
- 6 个已记录的带有 `PANIC-SAFETY:` 不变量的生产 panic 站点 —— 参见
[`docs/security/panic-sites.md`](docs/security/panic-sites.md)。
### FIPS 140-3 / 通用标准 —— 仅作为探索，未经验证
- **FIPS 140-3:** 密码学使用了多种 FIPS 批准的原语（ML-KEM-768、ML-DSA-65、Ed25519、SHA-256、HMAC/HKDF-SHA-256），可选的 `fips` Cargo 功能会将剩余的非批准原语替换为 `aws-lc-rs` 基质。这 *不是* 经过验证的加密模块（无 CMVP）。差距分析：[`docs/compliance/fips-readiness.md`](docs/compliance/fips-readiness.md)；
CAVP 风格的已知答案向量在 [`core/tests/cavp.rs`](core/tests/cavp.rs) 中。
- **通用标准:** 针对 NIAP PP-Module VPN Client 的内部 SFR 差距映射工作仅作为设计参考存在
（[`docs/compliance/cc-pp-mapping.md`](docs/compliance/cc-pp-mapping.md)）。目前没有计划进行实验室评估。
### 披露
私下报告，**不要**通过公开 issues。禁运 SLA 为 90 天；在 5 个工作日内确认，在 14 天内进行分类。联系方式在 [`SECURITY.md`](SECURITY.md) 中（那里的电子邮件是等待 crate 发布前的占位符）。
### 供应链
`cargo deny`（宽松的许可证白名单，`yanked = "deny"`，
`unknown-registry = "deny"`）和 `cargo audit` 在 CI 中运行。发布工件通过 `actions/attest-build-provenance@v2` 携带 **SLSA-3 OIDC 构建出处证明**。使用 `gh attestation verify --owner ` 或 `cosign verify-blob-attestation` 进行验证。
## 状态与限制
- **1.0 之前版本 (`0.1.1`)。** 线上格式可能会在次要版本之间发生破坏性改变；SemVer 在 1.0 发布后适用。当前的线上协议是一个单一的固定版本 —— 以前的 V1/V2/V3 轴线在 1.0 之前被合并了（没有用户，没有协商，没有回退），因此没有跨版本迁移指南。
- **原生 UDP 传输 (PhantomUDP): 握手 + demux 工作；丢包恢复是悬而未决的部分。** `PhantomSession` 现在可以通过 TCP、WebSocket 以及原始 UDP（连接 ID demux、服务端接受、分片握手）运行经过身份验证的会话 —— 已在无损 loopback 上进行了端到端验证。**尚未**完成的是：UDP 数据平面的丢包恢复此前仅在可靠管道上运行过，尚未在真实的丢包环境中进行验证；确定性丢包/重排测试传输（验证它所需的工具）正在优先构建中。早期实验性的 KCP / FakeTLS 链路以及未使用的 `TransportLeg` 多路径 trait 已被移除（从未接入数据平面）。路线图：验证单路径 UDP 丢包恢复 → 无缝连接迁移（一次仅维持一个活跃路径，用于在没有重新握手的情况下进行 Wi-Fi↔蜂窝切换） → DPI 模仿传输模式。跨传输的带宽 *聚合* **并未**在计划中 —— 分析表明它会对这种工作负载产生倒退，并损害不可观测性。
- **移动连接迁移（Wi-Fi ↔ LTE）尚不支持。** 路径验证原语仅限内部使用；在网络发生变化时，请重新连接（通过 `connect_pinned_with_resumption` 使用 0-RTT 恢复以最小化成本）。
- **丢包恢复基于超时（无 SACK）且未在丢包环境中得到验证。** 代码包含 RFC-6298 RTO + 重传 + BBR 风格的拥塞窗口 + 会话中期密钥更新，但这套机制是为可靠的字节管道构建的，并且 **从未针对真实的丢包/重排进行过演练** —— 验证它（以及使之成为可能的丢包测试装备）是目前的优先事项。SACK / dup-ACK 快速重传 / PTO 是接下来的工作项，需要对数据包编号 / ACK 范围字段进行敏感的安全处理，即一次刻意的 `WIRE_VERSION` 提升。
- **负安全测试套件：** `core/tests/security_invariants.rs` 中有 33 个常驻测试，锁定了所有已记录的不变量。此外还有 proptest、fuzz、wire-vector、runtime-integration 和 CAVP 套件、282 个库单元测试，以及受 `#[ignore]` 限制的 loopback 集成套件（TCP、UDP、WASI）。0 个工作空间警告，0 个 clippy 警告。**注意：** 广泛的测试覆盖 *并不* 等同于经过验证的传输 —— 在面临真实的丢包时，这些测试都还没有针对数据平面进行演练（参见上面的丢包恢复项）。
- **计划阶段的功能覆盖面很广，但尚未达到生产就绪状态。** 握手/身份/可观测性/跨目标工作已基本就绪；数据平面（UDP 丢包恢复）是未完成、未经验证的部分，并且尚未进行外部安全审计或 CMVP/CC 验证。形式化验证（ProVerif / Tamarin）和外部审计已提上日程，但尚未完成。
- **`PhantomListener::bind()` 会每个进程生成一个新的签名密钥** —— 身份在重启后无法保留。固定稳定的生产部署必须使用 `bind_with_signing_key()` 并从磁盘加载密钥（`phantom-cli keygen` 会写入 0600 权限的种子文件）。
- **该库不包含 HTTP 服务器。** 该库暴露 OTel 指标；嵌入器配置导出器。`server/src/telemetry.rs` 是参考的 OTLP/gRPC 接线方式。
- **MSRV: Rust 1.75.** `cli/` 使用 edition 2024，可以在稳定版上构建，但不能在 1.75 限制上构建。
- **7 个 fuzz harness**，在 CI 中运行（`.github/workflows/fuzz.yml`：每个目标在每个 PR 运行 60 秒，每晚运行 600 秒）。模糊测试需要 nightly；只有 `fuzz_embedded_framing` 的主体也可以在稳定版上编译。
- **嵌入式在裸机上仅支持成帧。** `thumbv7em-none-eabihf` 构建（`--no-default-features --features embedded,no-std`）仅提供 `EmbeddedLeg` 及其长度前缀成帧；PQ 加密、握手和 `PhantomSession` 受 `std` 限制被排除在外。**PQ-on-bare-metal 不在 1.0 计划之内** —— RustCrypto 原语需要 `alloc` 以及嵌入器提供的熵/堆，而真正的裸机握手（no-std 加密、Embassy/RTIC 运行时、QEMU 托管的握手测试）是一个单独的子项目。裸机嵌入器通过该链路运行它们自己的加密。严格的 `thumbv7em` CI 关卡是 `cargo check --lib` —— 它证明成帧可以编译，但并不证明会话可以运行。
## 文档
- **架构:** [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)；
贡献者工作流在 [CONTRIBUTING.md](CONTRIBUTING.md) 中
- **线上协议:** [`docs/protocol/PROTOCOL.md`](docs/protocol/PROTOCOL.md)
（单一统一协议，包括 0-RTT）
- **安全性:** [`SECURITY.md`](SECURITY.md)、
[`docs/security/threat-model.md`](docs/security/threat-model.md)、
[`docs/security/incident-response.md`](docs/security/incident-response.md)、
[`docs/security/cancel-safety-audit.md`](docs/security/cancel-safety-audit.md)、
[`docs/security/panic-sites.md`](docs/security/panic-sites.md)
- **合规性:** [`docs/compliance/`](docs/compliance/) —
`fips-readiness.md`、`cc-pp-mapping.md`、`constant-time-audit.md`、
`rng-audit.md`、`key-management.md`、`self-tests.md`、
`fips-security-policy.md`
- **运维:** [`docs/operations/`](docs/operations/) —
`perf-tuning.md`、`deployment.md`、`docker.md`、`systemd.md`、
`kubernetes.md` (+ `helm/`)、`mobile.md`、`wasm.md`、`wasi.md`
- **政策:** [`docs/policy/versioning.md`](docs/policy/versioning.md)
- **性能:** [`BENCHMARKS.md`](BENCHMARKS.md)
- **更新日志:** [`CHANGELOG.md`](CHANGELOG.md)
## 致谢
使用 Anthropic 的 **Claude Opus 4.6** 通过 [Claude Code](https://claude.com/claude-code) 提供的 AI 协助进行开发。所有架构决策、安全不变量、威胁模型以及 FIPS / CC 合规工件均由人类作者编写、审查、测试和维护。
## 许可证
Apache License 2.0。参见 [`LICENSE`](LICENSE)。
标签：Rust, 内核驱动, 可视化界面, 后量子密码学, 用户代理, 网络传输, 网络协议, 网络流量审计, 跨平台SDK, 通知系统