Legion ZK Auth 🛡️

True Zero-Knowledge Authentication with Hardware-Bound Device Ring Signatures

🎯 What is Legion?

Legion is a passwordless zero-knowledge authentication system that proves you're authorized without revealing who you are.

Authenticate using only your fingerprint + 24-word recovery phrase (like MetaMask). No usernames, no passwords, no server-side secrets.

Key Features

✅ Passwordless Authentication: BIP-39 recovery phrase + fingerprint (no username/password)
✅ True Zero-Knowledge: Server never learns your identity (1 of 1M users)
✅ Device Anonymity: Hardware-bound with ring signatures (1 of 1K devices)
✅ No Trusted Setup: Halo2 PLONK (transparent setup)
✅ Hardware Security: WebAuthn TPM/Secure Enclave binding
✅ Replay Protection: Nullifiers + timestamps
✅ Session Security: Linkability tags prevent theft
✅ Multi-Device Support: Use same account on 2 devices (laptop + phone)
✅ Rate Limiting: 5 attempts/hour (generic errors prevent enumeration)
✅ Device Revocation: Block stolen devices instantly

🔒 Security Guarantees (v1.3.0)

Property	Guarantee
Authentication	Passwordless (BIP-39 + Fingerprint)
User Anonymity	1 of 2^20 (1,048,576)
Device Anonymity	1 of 2^10 (1,024) per user
Soundness Error	2^-128
Proof System	Halo2 PLONK (transparent setup)
Credential Derivation	Blake3 (BIP-39 seed)
Hardware Binding	WebAuthn Level 2 (TPM/Secure Enclave)
Multi-Device	Max 2 devices per account
Rate Limiting	5 attempts/hour
Device Revocation	Instant blacklist

🚀 Quick Start (One Command!)

Prerequisites

Docker (includes Docker Compose)

Install & Run

# 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

That's it! Open http://localhost in your browser.

What Gets Installed

✅ Redis (session storage)
✅ Legion Server (ZK proof verifier)
✅ Frontend (WASM client)
✅ Nginx (reverse proxy)

Performance: Registration ~5s, Authentication ~2min (k=14 proof generation)

Manual Setup (Without Docker)

Click to expand manual installation

# 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

For production deployment, see DEPLOYMENT.md

📊 Performance

Security Level	k	Proof Time	Proof Size	Use Case
Development	12	~30s	3.2 KB	Testing
Production	14	~2min	3.4 KB	Recommended

Verification Benchmarks

Test Hardware: Lenovo IdeaPad 3 - Intel Core i3 11th Gen
Note: Performance may vary based on hardware specifications.

k=12 (Development/Testing)

Metric	Value	Notes
Proof Size	3,264 bytes	3.19 KB compressed
Public Inputs	10	User tree root, device tree root, nullifier, etc.
Params Generation	7.03s	One-time setup per k value
Circuit Creation	2.3µs	Negligible overhead
Verifying Key Gen	1.29s	One-time keygen
Proof Verification	107.7ms	Actual ZK proof check
Total Verification	8.43s	End-to-end (without caching)

Breakdown:

🔥 Cold start (first verification): ~8.4s (includes params + keygen + verification)
⚡ Subsequent verifications (with caching): ~108ms (params/keygen cached)
💾 Proof overhead: ~326 bytes per public input
🔐 Circuit complexity: User tree (20 levels) + Device tree (10 levels) + bindings

k=14 (Production - Recommended)

Metric	Value	Notes
Proof Size	3,392 bytes	3.31 KB compressed
Public Inputs	10	User tree root, device tree root, nullifier, etc.
Params Generation	100.78s	One-time setup per k value
Circuit Creation	5µs	Negligible overhead
Verifying Key Gen	12.89s	One-time keygen
Proof Verification	967.2ms	Actual ZK proof check
Total Verification	114.65s	End-to-end (without caching)

Breakdown:

🔥 Cold start (first verification): ~115s (includes params + keygen + verification)
⚡ Subsequent verifications (with caching): ~967ms (params/keygen cached)
💾 Proof overhead: ~339 bytes per public input
🔐 Circuit complexity: User tree (20 levels) + Device tree (10 levels) + bindings

Important: Params generation and keygen are one-time costs that can be cached. Once cached, verification takes only ~108-967ms depending on k value. Current implementation does not cache params yet.

Why slower than old benchmarks? The passwordless circuit now verifies TWO Merkle trees (user + device) instead of one, providing true device-level anonymity (1-of-1024 devices per user).

🏗️ Architecture

📖 For detailed step-by-step authentication flow with cryptographic details, see ARCHITECTURE_FLOW.md

legion

Most Popular