AlexMelanFromRingo/uber-mesh

## 目录 - [为什么](#why) · [核心亮点](#highlights) · [架构](#architecture) · [Workspace](#workspace-crates) - [快速开始](#quickstart) · [抗审查](#censorship-resistance) · [验证与基准测试](#validation--benchmarks) - [安全模型](#security-model) · [项目结构](#project-layout) · [规范驱动开发](#spec-driven-development) - [路线图](#roadmap) · [贡献指南](#contributing) · [许可证](#license) ## 为什么 在 2025-26 年，应对审查的韧性来自于**敏捷性，而非单一牢不可破的协议**。审查者 结合了被动全加密分类（熵/无头部启发式）、主动探测、TLS 状态机 和 SNI 检查，以及基于流量的限速。uber-mesh 在一个**去中心化的 libp2p overlay** 网络上，将一个**可插拔、由环境自动选择的 混淆传输层**置于**混合后量子安全通道**之下—— 因此，节点可以混入普通的 TLS 流量中，拒绝向探测者暴露自身，绕过 封锁，并在没有任何中央机构的情况下端到端验证每条消息。 ## 核心亮点 | 功能 | 具体作用 | |---|---| | 🔐 **混合后量子** | 每条链路均通过 X-Wing 风格的 BLAKE3 组合器，使用 **X25519 + ML-KEM-768** 生成密钥。经典部分保持权威性；所有 mesh 数据均通过 PQ 密钥隧道传输（杜绝“先收集后解密”）。 | | 🥷 **模拟 TLS-1.3 ClientHello** | 混淆握手是一个*结构合法的* TLS 1.3 ClientHello → ServerHello，并带有一个 PQ 混合的 `X25519MLKEM768` key_share。有效对抗基于熵/无头部**以及** TLS 状态机的 DPI；可与真实的 PQ-TLS 流量完美融合。 | | 🪞 **类 REALITY 的探测防御** | 未持有共享 PSK 的对等节点将无法通过网关，只能得到**静默回应**，或者**被反向代理到真实的掩护站点**——主动探测者无法区分节点与真正的 TLS 服务器。 | | 🕸️ **去中心化 Overlay** | libp2p **Gossipsub**（严格签名 + 评分）、**私有 Kademlia**、identify/ping，以及 NAT 组合套件（**AutoNAT v2 / Circuit Relay v2 / DCUtR**）——全部*运行于*混淆载体之上。 | | ✍️ **签名 gossip + 防重放** | 经过 Ed25519 签名、内容寻址的消息，配合单调递增的 seqno、时间戳窗口和 LRU 去重保护。伪造和重放消息将被拒绝。 | | 📦 **内容交换与同步** | 内容寻址存储 + 请求/响应 blob (`BLAKE3(bytes) == Cid`) 以及 **negentropy 风格的集合协调**。 | | 📈 **可观测且轻量** | 每个节点均提供 Prometheus `/metrics` 及预配置的 Grafana；每个叶节点仅占 **~4 MB RSS**，支持自定义 Tokio worker 池（`UMESH_WORKERS`）。 | | 🦀 **纯 Rust 实现，无 `unsafe`** | 整个 workspace 启用 `unsafe_code = "deny"`；加密核心中使用 `#![forbid(unsafe_code)]`。默认构建不包含 C/FFI。 | ## 架构 uber-mesh 将混淆层堆叠在 libp2p 的 Noise 通道**之下**，因此整个 gossip mesh 天然具备了 该传输层的 DPI 抗性，且数据通道实现了端到端的混合 PQ 安全。 ``` flowchart TB subgraph app["uber-mesh CLI · umesh-node"] A["init · run · mesh · status · keys
config · keystore · runtime · Prometheus /metrics"] end subgraph overlay["umesh-p2p — libp2p overlay"] B["Gossipsub (signed + scored) · private Kademlia
AutoNAT v2 / Relay v2 / DCUtR · blobs · set reconciliation"] end subgraph noise["libp2p Noise + Yamux"] C["authenticated, multiplexed secure channel"] end subgraph obfs["umesh-obfs — obfuscation carrier"] D["TLS-1.3 ClientHello/ServerHello handshake (PQ key_share + session_id MAC gate)
AEAD record stream · length-hiding padding · IAT shaping · profiles · rotation"] end subgraph crypto["umesh-crypto (#![forbid(unsafe_code)])"] E["hybrid X25519 + ML-KEM-768 KEM · Ed25519 identity
BLAKE3 hash/KDF/MAC/CID · XChaCha20-Poly1305 · Merkle · PoW"] end A --> B --> C --> D --> F["TCP / :443-survivable (QUIC — staged)"] E -. keys & primitives .-> C E -. keys & primitives .-> D ``` 混淆握手本身在网络数据包中看起来就像是一个普通的后量子 TLS 1.3 开场： ``` sequenceDiagram participant C as Client participant S as Server (PSK holder) Note over C: ephemeral X25519 + ML-KEM-768 keygen C->>S: TLS ClientHello (0x16)
key_share = ml-kem ek(1184) ‖ x25519(32)
session_id = epoch ‖ MAC(key_share, epoch) Note over S: verify session_id MAC under PSK (gate)
fail ⇒ silence OR reverse-proxy to cover site S->>C: TLS ServerHello (0x16)
key_share = ml-kem ct(1088) ‖ x25519(32) Note over C,S: derive directional AEAD keys from the hybrid shared secret C->>S: Application-Data records (0x17) — Noise → Gossipsub … S->>C: Application-Data records (0x17) ``` ### Workspace crates | Crate | 作用 | |-------|------| | [`umesh-crypto`](crates/umesh-crypto) | 纯 Rust 加密核心 (`#![forbid(unsafe_code)]`)：混合 X25519+ML-KEM-768 KEM（X-Wing 风格 BLAKE3 组合器）、Ed25519 身份标识 (`PeerId = BLAKE3(pubkey)`)、BLAKE3 哈希/KDF/带密钥 MAC/带域分离的 CID、XChaCha20-Poly1305、Merkle 树、PoW。包含 KATs 和属性测试。 | | [`umesh-obfs`](crates/umesh-obfs) | 可插拔的混淆载体：带 `session_id` MAC 网关的 TLS-1.3 ClientHello/ServerHello 模拟握手、AEAD 记录流、隐藏长度的填充 + 流量整形、环境配置文件、`ObfsTcp` + 连接时轮换、类 REALITY 的回退机制。包含 DPI 模拟测试。 | | [`umesh-p2p`](crates/umesh-p2p) | libp2p mesh：签名 gossip + 防重放、`MeshBehaviour`（包含 Gossipsub Strict、私有 Kademlia、identify、ping）+ NAT 组合套件（AutoNAT v2 / Relay v2 / DCUtR）+ blob 请求/响应（bincode 编解码器）+ negentropy 风格的集合协调、内容寻址的 `ContentStore`、`MeshNode` 驱动程序、Prometheus 指标。 | | [`umesh-node`](crates/umesh-node) | 节点调度：配置、身份密钥库 (`0600`)、运行时、无泄露密钥的状态。 | | [`uber-mesh`](crates/uber-mesh) | CLI 二进制程序。 | ## 快速开始 ``` git clone https://github.com/AlexMelanFromRingo/uber-mesh cd uber-mesh cargo build --workspace cargo test --workspace # 99 tests: KATs, property tests, DPI sim, gossip/NAT/reconcile integration cargo clippy --workspace --all-targets -- -D warnings ``` ### 双节点 gossip mesh（已混淆、混合 PQ、抗探测） Mesh 网络运行在混淆载体之上，因此对等节点之间会共享一个混淆 **PSK**（由 `init` 打印的网桥密钥， 需通过带外方式分发）。 ``` # 初始化两个节点——每个节点会打印一个 PSK。记下节点 A 的 PSK。 cargo run -p uber-mesh -- --data-dir /tmp/a init # ← copy A's PSK cargo run -p uber-mesh -- --data-dir /tmp/b init # 节点 A（bootstrap）——打印 "libp2p peer: " 并在 :9100/metrics 上提供 metrics cargo run -p uber-mesh -- --data-dir /tmp/a mesh --listen /ip4/127.0.0.1/tcp/41999 --psk # 节点 B——使用 A 的 PSK 通过混淆 transport 拨号 A cargo run -p uber-mesh -- --data-dir /tmp/b mesh --listen /ip4/127.0.0.1/tcp/0 \ --bootstrap /ip4/127.0.0.1/tcp/41999/p2p/ --psk ``` 每个节点都会打印 `[uber-mesh/global] b3:: heartbeat …`（发送者已通过 Ed25519 验证）。如果 使用**错误的 `--psk` 启动，对等节点将被混淆网关拒绝且永远无法连接**。检查节点状态，且 绝不会暴露任何密钥： ``` cargo run -p uber-mesh -- --data-dir /tmp/a status --json curl -s localhost:9100/metrics | grep umesh_ # peers, gossip, handshake histogram, resources ```

环境变量

| 变量 | 默认值 | 含义 | |---|---|---| | `UMESH_WORKERS` | `2` | Tokio worker 线程数（`1` = current-thread 运行时；越小足迹越轻）。 | | `METRICS_PORT` | `9100` | `mesh` 命令使用的 Prometheus `/metrics` 端口（设为 `off` 以禁用）。 | | `UMESH_SNI` | `www.cloudflare.com` | 混淆 ClientHello 中呈现的掩护域名 SNI。 | | `RUST_LOG` | `info` | Tracing 过滤器（绝不记录密钥）。 |

对网络数据包解析器进行 Fuzz 测试（nightly 版本）：`cd fuzz && cargo +nightly fuzz run obfs_record`（或 `message_parse`）。 在 `tc-netem` 下运行包含 Prometheus + Grafana 的 100 节点 Docker 集群：`NODES=100 bash docker/run-cluster.sh`。 ## 抗审查 uber-mesh 借鉴了各种主流翻墙设计的核心承载理念，并将它们组合在一个 可插拔的传输层接缝背后。本表关注的是*理念与姿态*，而非基准测试大比拼。 | | uber-mesh | REALITY / XTLS | Hysteria2 | AmneziaWG | obfs4 | |---|---|---|---|---|---| | **载体** | TCP（能在 `:443` 存活） | TCP / TLS | QUIC / UDP | WireGuard / UDP | TCP | | **抗 DPI** | 模拟 TLS-1.3 ClientHello + 抵抗熵/探测/状态机检测 + 掩护站点回退 | 窃取真实的 TLS 握手（字节级精确） | Salamander 混淆 + 拥塞控制 | 垃圾数据包 + 魔术标头 | 均匀随机 + ntor + IAT | | **后量子** | ✅ X25519 + ML-KEM-768 | ❌ 经典密码学 | ❌ | ❌ | ❌ | | **去中心化** | ✅ libp2p mesh | ❌ 客户端/服务器代理 | ❌ 代理 | ❌ VPN | ❌ 可插拔传输层 | | **uber-mesh 的借鉴点** | — | 掩护站点回退 + `session_id` 中的短 ID 网关 | QUIC+Salamander *(已设计，暂缓)* | AmneziaWG 混淆 *(已设计，暂缓)* | 静默回应 / 主动探测防御 | ## 验证与基准测试 这些测试工具在单元测试之外对**真实代码**进行了压力测试（单主机环境，2026 年中；完整的方法与注意事项详见 [`docs/benchmarks.md`](docs/benchmarks.md)): | 场景 | 结果 | |---|---| | 进程内 gossip，**100 个节点** | **100% 投递率**，传播 p95 ≈ **3 ms** | | Docker **100 个节点** + 在 `tc-netem` 下运行 Prometheus (丢包率 2%, 50 ms±10) | 混淆握手 p95 = **147 ms**（< 150 ms 目标值），25 540 条 gossip 消息，**0 伪造** | | 路径中的 **DPI 中间盒** ([`tests/dpi_middlebox.rs`](crates/umesh-obfs/tests/dpi_middlebox.rs)) | 混淆传输**通过**了基于熵/无头部 **+** 主动探测 **+** TLS 状态机的审查；原始 / 永久应答 / 应用层数据优先的流量被**阻断** | | 吞吐量（环回测试，AEAD 记录） | **267 MB/s**（激进的 IAT 整形*根据设计*将大流量限制在 1.4 MB/s） | | 单节点资源占用 | RSS 占用 **~4 MB**（叶节点） / ~33 MB（bootstrap 节点），CPU 接近空闲，~4 个线程（默认池） | | 稳定性测试（3 分钟） · 极度混乱（杀掉 12/50 个节点） | RSS 稳定，无内存泄漏 · 38 个幸存节点继续进行 gossip，0 伪造 | ## 安全模型 - **混合 PQ，以经典密码学为权威。** 会话密钥结合了 X25519 和 ML-KEM-768；仅仅攻破 （未经审计的）PQ 部分无法危及整个会话的安全。无任何手动实现的密码学原语。 - **抗探测。** PSK 网关是 TLS `session_id` 中的一个带密钥的 BLAKE3 MAC（常数时间检查， ±1 分钟的时代窗口）。非 PSK 对等节点只能获得静默回应（obfs4 模型）或透明的掩护站点代理（REALITY 模型）。 - **自主主权身份。** `PeerId = BLAKE3(Ed25519 pubkey)`；签名使用 `verify_strict`。无 CA，无注册表。 - **无密钥泄露。** PSK、身份种子和会话密钥在 drop 时会被清零，且绝不会出现在日志、 状态、错误或指标中（仅显示指纹）。磁盘上的密文件权限为 `0600`。 - **内存安全。** 整个 workspace 启用 `unsafe_code = "deny"`；在 `umesh-crypto` 中为 `#![forbid(unsafe_code)]`。 完整的政策、威胁模型和报告见：[`SECURITY.md`](SECURITY.md)。暂缓工作的处置说明： [`docs/security-and-deferred.md`](docs/security-and-deferred.md)。PQ crates 尚未经过审计——在生产环境使用前请固定版本并 重新审计。 ## 项目结构 ``` crates/ umesh-crypto pure-Rust crypto core (#![forbid(unsafe_code)]) umesh-obfs obfuscation carrier (TLS-mimicry handshake, AEAD record stream, shaping, profiles) umesh-p2p libp2p mesh overlay (gossip, Kademlia, NAT, blobs, reconciliation) over the obfs carrier umesh-node config, keystore, node orchestration, status uber-mesh the CLI (init / run / mesh / status / keys show) fuzz/ standalone nightly libFuzzer harnesses (excluded from the workspace) docker/ scalable Docker cluster + Prometheus + Grafana + tc-netem runner docs/ benchmarks, security-and-deferred, research dossier specs/ Spec Kit design artifacts for 001-uber-mesh-core .specify/ the constitution (iron rules) + Spec Kit templates ``` ## 规范驱动开发 uber-mesh 使用 [**GitHub Spec Kit**](https://github.com/github/spec-kit) 构建：设计先于代码，且 产出物均已提交入库。该项目的**铁律**是七项宪法原则 ([`.specify/memory/constitution.md`](.specify/memory/constitution.md), v1.0.0): 完整的设计文档位于 [`specs/001-uber-mesh-core/`](specs/001-uber-mesh-core/) 目录下（包含 `spec.md`、`plan.md`、 `tasks.md`、`data-model.md`、`research.md`、`contracts/`）；经过验证的技术原理解析详见 [`docs/research/dossier.md`](docs/research/dossier.md)。 ## 路线图 **已实现并测试** —— 加密核心 · 带有 TLS-1.3 ClientHello 模拟、抗探测 & 类 REALITY 回退机制的混淆载体 · 配置文件 / 整形 / 轮换 · libp2p Noise **之下**的混淆（mesh 继承了 DPI 抗性）· Gossipsub + 私有 Kademlia + AutoNAT/Relay/DCUtR · 签名 gossip + 防重放 · 内容交换 + 集合协调 · Prometheus 指标 + Grafana · 节点 + CLI · Docker 验证。 **按设计暂缓实现**（作为增量功能保留在 `ObfsTransport` 接缝背后；理由详见 [`docs/security-and-deferred.md`](docs/security-and-deferred.md))：字节级精确的 uTLS JA3/JA4 + 全握手记录的 原生 REALITY（需要能控制 ClientHello 的 TLS 协议栈）、QUIC + Salamander（需要 `quinn` UDP 访问权限）、 AmneziaWG（需要 WireGuard 核心），以及基于本地射频的 blackout 模式（需要无线电硬件）。进度追踪见 [`specs/001-uber-mesh-core/tasks.md`](specs/001-uber-mesh-core/tasks.md)；发布历史见 [`CHANGELOG.md`](CHANGELOG.md)。 ## 许可证 基于 **Mozilla Public License 2.0** ([`LICENSE`](LICENSE)) 授权。参与贡献即表示您同意将您的 贡献内容基于 MPL-2.0 授权。 ## 致谢 本项目构建于 [rust-libp2p](https://github.com/libp2p/rust-libp2p)、 [dalek](https://github.com/dalek-cryptography) 和 [RustCrypto](https://github.com/RustCrypto) 生态系统 （`ml-kem`、`chacha20poly1305`）、[BLAKE3](https://github.com/BLAKE3-team/BLAKE3) 的工作之上，并借鉴了 REALITY/XTLS、Hysteria、AmneziaWG 和 obfs4 背后的技术。使用 [GitHub Spec Kit](https://github.com/github/spec-kit) 开发。

标签：libp2p, P2P网络, Rust, 可视化界面, 后量子密码学, 抗审查, 流量伪装, 网络流量审计, 网络通信, 自定义请求头, 请求拦截, 通知系统