Legion ZK Auth 🛡️

真正的零知识认证，带有硬件绑定的设备环签名

🎯 Legion 是什么？

Legion 是一个 免密码的零知识认证系统，可以在不暴露你是谁的情况下证明你拥有授权。

只需使用你的 指纹 + 24 词恢复助记词（类似 MetaMask）即可完成认证。无需用户名、无需密码、无需服务器端秘密。

主要特性

✅ 免密码认证：BIP-39 恢复助记词 + 指纹（无用户名/密码）
✅ 真正的零知识：服务器永远不会知道你的身份（100 万用户中的 1 个）
✅ 设备匿名：通过环签名绑定硬件（1000 台设备中的 1 台）
✅ 无需可信设置：Halo2 PLONK（透明设置）
✅ 硬件安全：WebAuthn TPM/Secure Enclave 绑定
✅ 重放保护：空值器 + 时间戳
✅ 会话安全：链路标签防止被盗
✅ 多设备支持：同一账户可在 2 台设备上使用（笔记本 + 手机）
✅ 速率限制：每小时 5 次尝试（通用错误防止枚举）
✅ 设备撤销：立即阻止被盗设备

🔒 安全保证（v1.3.0）

🚀 快速开始（一条命令！）

前提条件

Docker（包含 Docker Compose）

安装并运行```bash

Clone and run

git clone https://github.com/deadends/legion.git cd legion

Linux/macOS

chmod +x scripts/install.sh && ./scripts/install.sh

Windows

scripts\install.bat

**大功告成！** 在浏览器中打开 http://localhost。

### 安装内容
- ✅ Redis（会话存储）
- ✅ Legion Server（ZK 证明验证器）
- ✅ 前端（WASM 客户端）
- ✅ Nginx（反向代理）

**性能**：注册约 5 秒，认证约 2 分钟（k=14 证明生成）

---

### 手动设置（不使用 Docker）

<details>
<summary>点击展开手动安装步骤</summary>```bash
# 1. Install Redis
# macOS: brew install redis && redis-server
# Ubuntu: sudo apt install redis && redis-server
# Windows: https://redis.io/docs/install/install-redis/install-redis-on-windows/

# 2. Run server (terminal 1)
cd legion-server
cargo run --release --features redis

# 3. Build frontend (terminal 2)
cd wasm-client
wasm-pack build --target web --release
python3 -m http.server 8000

# 4. Open http://localhost:8000

对于生产部署，请参见 DEPLOYMENT.md

📊 性能

验证基准

测试硬件： Lenovo IdeaPad 3 - 第11代Intel Core i3
注意： 性能可能因硬件规格而异。

k=12（开发/测试）

细目：

🔥 冷启动（首次验证）：~8.4秒（包括参数生成+密钥生成+验证）
⚡ 后续验证（启用缓存）：~108毫秒（参数/密钥缓存）
💾 证明开销：每个公开输入约326字节
🔐 电路复杂度：用户树（20层）+ 设备树（10层）+ 绑定

k=14（生产环境 - 推荐）

细目：

🔥 冷启动（首次验证）：~115秒（包括参数生成+密钥生成+验证）
⚡ 后续验证（启用缓存）：~967毫秒（参数/密钥缓存）
💾 证明开销：每个公开输入约339字节
🔐 电路复杂度：用户树（20层）+ 设备树（10层）+ 绑定

重要说明： 参数生成和密钥生成均属于一次性开销，可进行缓存。一旦缓存，根据k值不同，验证仅需约108-967毫秒。当前实现尚未包含参数缓存。

为何比旧基准慢？ 无密码电路现在需要验证两个Merkle树（用户树+设备树），而非仅一个，从而实现了真正的设备级匿名性（每个用户可拥有1/1024台设备）。

🏗️ 架构

📖 有关包含密码学细节的逐步认证流程，请参见 ARCHITECTURE_FLOW.md

系统组件```

┌─────────────────────────────────────────────────────────────────────────┐ │ CLIENT (Browser + WASM) │ ├─────────────────────────────────────────────────────────────────────────┤ │ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────────────┐ │ │ │ UI Layer │ │ WASM Prover │ │ Local Storage │ │ │ │ (Vanilla JS) │ │ (Rust→WASM) │ │ (IndexedDB) │ │ │ ├────────────────┤ ├─────────────────┤ ├──────────────────────────┤ │ │ │ • Registration │ │ • Blake3 Hash │ │ • Full Merkle Tree │ │ │ │ • Login Form │ │ • BIP-39 Derive │ │ • Device Trees │ │ │ │ • Session UI │ │ • Halo2 Prover │ │ • WebAuthn Credentials │ │ │ │ • Tree Sync │ │ • Merkle Proof │ │ • Tree Version Cache │ │ │ └────────────────┘ │ • Ring Sigs │ └──────────────────────────┘ │ │ └─────────────────┘ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ Hardware Security (WebAuthn Level 2) │ │ │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ • TPM 2.0 / Secure Enclave • FIDO2 Authenticator │ │ │ │ • Device Private Key (ECDSA) • Biometric/Touch Required │ │ │ └──────────────────────────────────────────────────────────────────┘ │ └────────────────────────────────┬────────────────────────────────────────┘ │ HTTPS/TLS 1.3 │ (Encrypted Channel) ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ LEGION SERVER (Rust/Axum) │ ├──────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ API Layer (Axum) │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ POST /api/register-blind │ Blind registration │ │ │ │ GET /api/download-tree │ Download full Merkle tree │ │ │ │ POST /api/verify-anonymous-proof │ Verify ZK proof │ │ │ │ POST /api/verify-session │ Session validation │ │ │ │ POST /api/webauthn/* │ WebAuthn endpoints │ │ │ │ GET /health │ Health check │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Business Logic Layer │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ • Blind Registration │ • Tree Synchronization │ │ │ │ • ZK Proof Verifier │ • Nullifier Tracker (replay) │ │ │ │ • Session Manager │ • Linkability Tag Validator │ │ │ │ • WebAuthn Service │ • Timestamp Validator (±10min) │ │ │ │ • Device Revocation │ • Rate Limiter (5/hour) │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Cryptographic Layer │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ • Halo2 Verifier (PLONK) │ • Poseidon Hash (ZK-friendly) │ │ │ │ • Blake3 (credential) │ • BIP-39 (recovery phrase) │ │ │ │ • Merkle Tree (2^20) │ • Device Trees (2^10 per user) │ │ │ │ • Ring Signature Verify │ • WebAuthn Signature Verify │ │ │ └─────────────────────────────────────────────────────────────────┘ │ └────────────────────────┬──────────────────────┬──────────────────────────┘ │ │ ▼ ▼ ┌────────────────────────┐ ┌───────────────────────────┐ │ Redis (In-Memory) │ │ RocksDB (Persistent) │ ├────────────────────────┤ ├───────────────────────────┤ │ • Session Tokens │ │ • Merkle Tree Leaves │ │ • Linkability Tags │ │ • Device Trees │ │ • Spent Nullifiers │ │ • Nullifier History │ │ • Rate Limit Counters │ │ • WebAuthn Credentials │ │ TTL: 1 hour │ │ • Revoked Devices │ └────────────────────────┘ └───────────────────────────┘

### 认证流程（简化）```
┌─────────────┐                                                ┌──────────────┐
│   Client    │                                                │    Server    │
│  (Browser)  │                                                │  (Verifier)  │
└──────┬──────┘                                                └──────┬───────┘
       │                                                              │
       │ 1. Generate 24-word recovery phrase (BIP-39)                 │
       │    → 256-bit entropy (like MetaMask)                         │
       │    → User writes down on paper                               │
       │                                                              │
       │ 2. Derive account_id from phrase (Blake3)                    │
       │    account_id = Blake3("LEGION_ACCOUNT_V2" || bip39_seed)    │
       │    → Deterministic, no server interaction                    │
       │                                                              │
       │ 3. Hash account_id for tree leaf (Poseidon)                  │
       │    credential_hash = Poseidon(account_id)                    │
       │                                                              │
       │ 4. Blind registration (TRUE zero-knowledge)             ────►│
       │    → Sends ONLY credential_hash (no phrase/identity)         │
       │    → Server adds to tree, returns tree_index                 │
       │                                                         ◄────│ {tree_index: 114}
       │                                                              │
       │ 5. Download full Merkle tree (one-time sync)            ────►│
       │    → Client stores entire tree in IndexedDB                  │
       │    → Enables TRUE zero-knowledge (no server queries)         │
       │                                                         ◄────│ {tree_data: [all leaves],
       │                                                              │  merkle_root, version}
       │                                                              │
       │ 6. Generate WebAuthn key (TPM/Secure Enclave)                │
       │    → Fingerprint prompt creates hardware-bound key           │
       │    → device_pubkey (ECDSA P-256, non-exportable)             │
       │    → Stored in TPM 2.0 / Secure Enclave                      │
       │                                                              │
       │ 7. Register device in device tree                       ────►│
       │    → device_commitment = Blake3(credential_id)               │
       │    → Server converts to valid field element if needed        │
       │    → Server adds to user's device tree (1 of 1024 slots)     │
       │                                                         ◄────│ {device_position: 0,
       │                                                              │  device_tree_root}
       │                                                              │
       │ 8. LOGIN: Touch fingerprint to authenticate                  │
       │    → WebAuthn verifies hardware-bound key                    │
       │    → Decrypts recovery phrase from local storage             │
       │    → Re-derives account_id from phrase                       │
       │                                                              │
       │ 9. Fetch device Merkle proof                            ────►│
       │    → Sends account_id (derived from phrase)                  │
       │    → Server returns device tree path                         │
       │                                                         ◄────│ {device_path: [siblings],
       │                                                              │  device_root}
       │                                                              │
       │ 10. Compute user Merkle proof CLIENT-SIDE                    │
       │    → Uses local tree from IndexedDB                          │
       │    → Computes path for tree_index                            │
       │    → Server NEVER learns which user!                         │
       │                                                              │
       │ 11. Compute nullifier (replay protection)                    │
       │    nullifier = Poseidon(account_id || challenge)             │
       │    → ONE-TIME USE: Different every login                     │
       │    → Prevents proof replay attacks                           │
       │                                                              │
       │ 12. Compute linkability tag (session binding)                │
       │    linkability_tag = Blake3(device_pubkey || nullifier)      │
       │    ⚠️  Binds session to specific device+user                 │        
       │                                                              │
       │ 13. Generate ZK proof (Halo2 PLONK, ~2min for k=14)          │
       │    Proves in zero-knowledge:                                 │
       │    ✓ User exists in Merkle tree (1 of 2^20)                  │
       │    ✓ Device exists in device tree (1 of 2^10)                │
       │    ✓ account_id hashes to credential_hash                    │
       │    ✓ Nullifier computed correctly                            │
       │    ✓ Timestamp is fresh                                      │
       │    WITHOUT revealing which user or device                    │
       │                                                              │
       │ 14. Submit proof                                        ────►│
       │    {proof, public_inputs, linkability_tag, k=14}             │
       │                                                              │ • Check device not revoked
       │                                                              │ • Verify timestamp (±10min)
       │                                                              │ • Rate limit check (5/hour)
       │                                                              │ • Check nullifier (replay?)
       │                                                              │ • Verify ZK proof (~115s)
       │                                                              │ • Mark nullifier as used
       │                                                              │
       │                                                         ◄────│ {session_token, expires_at}
       │                                                              │
       │ 15. Verify session (every request)                      ────►│
       │    {session_token, linkability_tag}                          │
       │                                                              │ • Lookup in Redis
       │                                                              │ • Verify linkability_tag
       │                                                              │   (prevents session theft)
       │                                                              │ • Check not spent
       │                                                         ◄────│ {valid: true}
       │                                                              │

🔍 想要更多细节？ 请参阅 ARCHITECTURE_FLOW.md 了解：

逐步的密码学操作
电路约束细节
安全属性解释
攻击抵抗机制

会话安全深度解析```

┌─────────────────────────────────────────────────────────────────────────┐ │ SESSION SECURITY MECHANISMS │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 1. LINKABILITY TAG (Zero-Knowledge Device Binding) │ │ ═══════════════════════════════════════════════════════ │ │ │ │ linkability_tag = Blake3(device_pubkey || nullifier) │ │ │ │ • Computed client-side using hardware-bound device key │ │ • Sent with every session validation request │ │ • Server verifies: stored_tag == provided_tag │ │ │ │ ✅ PREVENTS: Session token theft/replay on different device │ │ ✅ ENSURES: Same user + same device for entire session │ │ ✅ MAINTAINS: Zero-knowledge (server doesn't learn identity) │ │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ 2. SESSION TOKEN (Cryptographic Binding) │ │ ═══════════════════════════════════════════════════════ │ │ │ │ session_token = Poseidon(nullifier || timestamp || linkability_tag) │ │ │ │ • Generated server-side after proof verification │ │ • Stored in Redis with linkability_tag as value │ │ • Cannot be forged without knowing nullifier │ │ │ │ ✅ PREVENTS: Token forgery │ │ ✅ ENSURES: Cryptographic binding to proof │ │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ 3. NULLIFIER (Replay Protection) │ │ ═══════════════════════════════════════════════════════ │ │ │ │ nullifier = Poseidon(credential_hash || challenge) │ │ │ │ • Unique per authentication attempt │ │ • Tracked in RocksDB (permanent) and Redis (cache) │ │ • Server rejects if nullifier seen before │ │ │ │ ✅ PREVENTS: Proof replay attacks │ │ ✅ ENSURES: One-time use per challenge │ │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ 4. TIMESTAMP VALIDATION (Time-Bound Security) │ │ ═══════════════════════════════════════════════════════ │ │ │ │ • Proof includes timestamp (Unix epoch) │ │ • Server validates: |proof_time - server_time| < 5 minutes │ │ • Session TTL: 1 hour (sliding window) │ │ │ │ ✅ PREVENTS: Old proof replay │ │ ✅ ENSURES: Fresh authentication │ │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ 5. CHALLENGE-RESPONSE (Freshness Guarantee) │ │ ═══════════════════════════════════════════════════════ │ │ │ │ • Server generates random 32-byte challenge │ │ • Stored in Redis with 5-minute TTL │ │ • Client must include in proof │ │ • Server verifies challenge matches and deletes │ │ │ │ ✅ PREVENTS: Pre-computed proof attacks │ │ ✅ ENSURES: Proof generated for this specific session │ │ │ └─────────────────────────────────────────────────────────────────────────┘

## 🔐 零知识属性

### 服务器知道的
- ✅ 匿名集中的某人的身份验证通过
- ✅ 密码学上有效的证明
- ✅ 通过可链接标签识别的同一用户+设备
- ✅ 速率限制状态（剩余尝试次数）
- ✅ 设备吊销状态
- ✅ 注册用户总数
- ✅ 默克尔树根（公开）

### 服务器无法知道的
- ❌ 具体是哪个用户（100万中之一）
- ❌ 具体是哪个设备（每用户1000个中之一）
- ❌ 恢复短语（BIP-39种子）
- ❌ account_id（从短语派生）
- ❌ 设备私钥（在TPM/安全区域中）
- ❌ 哪个树叶属于哪个用户
- ❌ 用户默克尔路径（客户端计算）
- ❌ 用户的tree_index位置

## 📦 部署

请参阅 [DEPLOYMENT.md](https://github.com/deadends/legion/blob/HEAD/docs/DEPLOYMENT.md) 获取详细的生产部署指南。

### 使用 Docker 快速部署```bash
# Production build
docker-compose -f deployment/docker-compose.yml up -d

# Check logs
docker-compose -f deployment/docker-compose.yml logs -f legion-server

# Check health
curl http://localhost/health

环境变量```env

RUST_LOG=info LEGION_DATA_PATH=/var/lib/legion/data REDIS_URL=redis://127.0.0.1:6379

## 🧪 测试```bash
# Run all tests
cargo test --workspace

# Run with Redis features
cargo test --workspace --features redis

# Benchmark
cargo bench

📚 文档

架构流程 - 详细的认证流程
安全修复 - v1.1.0 安全改进
部署指南 - 生产环境部署
安全策略 - 安全保证与报告
贡献指南 - 贡献规范

🛠️ 技术栈

ZK 证明: Halo2 (PLONK) - 透明设置，无需可信设置
曲线: Pasta (Pallas/Vesta) - 递归曲线循环
哈希: Blake3 (凭证派生), Poseidon (ZK 友好)
密钥派生: BIP-39 (24 词助记词)
硬件: WebAuthn Level 2 (TPM 2.0, Secure Enclave)
后端: Rust, Axum, Redis (会话), RocksDB (持久化)
前端: Rust→WASM (证明器), Vanilla JS (UI), IndexedDB (存储)
部署: Docker, Nginx, systemd

🤝 贡献指南

欢迎贡献！请先阅读 CONTRIBUTING.md。

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing)
提交更改 (git commit -m '添加惊艳特性')
推送到分支 (git push origin feature/amazing)
提交 Pull Request

🔒 安全

发现安全问题？请参阅 SECURITY.md 了解负责任披露流程。

不要针对漏洞公开提交 issue。

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

🔄 更新日志

v1.3.0 - 无密码认证 (2024)

主要变更：

✅ 无密码认证 - BIP-39 恢复短语 + 指纹
✅ 单字段电路 - account_id 从 BIP-39 种子派生
✅ 设备环签名 - 每用户 1-of-1024 设备匿名性
✅ 多设备支持 - 同一账户可在 2 台设备上使用
✅ 硬件绑定密钥 - WebAuthn TPM/Secure Enclave 集成
✅ Blake3 域元素处理 - 设备承诺的自动转换

架构：

🏗️ 无用户名/密码 - 仅恢复短语 + 指纹
🏗️ 客户端 account_id 派生 (Blake3 + BIP-39)
🏗️ 设备树存储在服务端（每用户隔离）
🏗️ 双重 Merkle 树验证（用户树 + 设备树）
🏗️ 健壮的域元素转换（处理大于域模数的 Blake3 输出）

v1.2.0 - 客户端证明架构 (2024)