Legion ZK Auth 🛡️

하드웨어 바인딩 기기 링 서명을 사용하는 진정한 영지식 인증

🎯 Legion이란 무엇인가?

Legion은 당신이 누구인지 공개하지 않으면서 권한이 있음을 증명하는 비밀번호 없는 영지식 인증 시스템입니다.

지문 + 24단어 복구 구문(MetaMask와 유사)만으로 인증하세요. 사용자 이름도, 비밀번호도, 서버 측 비밀도 없습니다.

주요 기능

✅ 비밀번호 없는 인증: BIP-39 복구 구문 + 지문 (사용자 이름/비밀번호 없음)
✅ 진정한 영지식: 서버는 사용자 신원을 알 수 없음 (100만 명 중 1명)
✅ 기기 익명성: 링 서명으로 하드웨어에 바인딩 (1,000개 기기 중 1개)
✅ 신뢰 설정 불필요: Halo2 PLONK (투명한 설정)
✅ 하드웨어 보안: WebAuthn TPM/Secure Enclave 바인딩
✅ 재생 방지: Nullifier + 타임스탬프
✅ 세션 보안: 연결성 태그로 도난 방지
✅ 다중 기기 지원: 노트북 + 휴대폰 등 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 증명 검증기)
- ✅ Frontend (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 - Intel Core i3 11세대
참고: 성능은 하드웨어 사양에 따라 다를 수 있습니다.

k=12 (개발/테스트)

세부 분석:

🔥 콜드 스타트 (첫 번째 검증): ~8.4s (파라미터 + 키 생성 + 검증 포함)
⚡ 이후 검증 (캐싱 사용): ~108ms (파라미터/키 생성 캐시됨)
💾 증명 오버헤드: 공개 입력당 ~326바이트
🔐 회로 복잡도: 사용자 트리 (20레벨) + 기기 트리 (10레벨) + 바인딩

k=14 (프로덕션 - 권장)

세부 분석:

🔥 콜드 스타트 (첫 번째 검증): ~115s (파라미터 + 키 생성 + 검증 포함)
⚡ 이후 검증 (캐싱 사용): ~967ms (파라미터/키 생성 캐시됨)
💾 증명 오버헤드: 공개 입력당 ~339바이트
🔐 회로 복잡도: 사용자 트리 (20레벨) + 기기 트리 (10레벨) + 바인딩

중요: 파라미터 생성과 키 생성은 캐시할 수 있는 일회성 비용입니다. 일단 캐시되면 k 값에 따라 검증은 약 108~967ms만 소요됩니다. 현재 구현은 아직 파라미터를 캐시하지 않습니다.

이전 벤치마크보다 왜 느린가요? 비밀번호 없는 회로는 이제 하나가 아닌 두 개의 Merkle 트리 (사용자 + 기기)를 검증하여 진정한 기기 수준 익명성 (사용자당 1024개 중 1개 기기)을 제공합니다.

🏗️ 아키텍처

📖 암호화 세부 정보가 포함된 단계별 인증 흐름은 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 │ │ │ └─────────────────────────────────────────────────────────────────────────┘

## 🔐 영지식 속성

### 서버가 아는 것
- ✅ 익명 집합 내 누군가가 인증했음
- ✅ 증명이 암호학적으로 유효함
- ✅ 연결 가능성 태그를 통한 동일 사용자+기기
- ✅ 속도 제한 상태(남은 시도 횟수)
- ✅ 기기 해지 상태
- ✅ 등록된 사용자 총 수
- ✅ Merkle 트리 루트(공개)

### 서버가 알 수 없는 것
- ❌ 특정 사용자(100만 명 중 1명)
- ❌ 특정 기기(사용자당 1,000개 중 1개)
- ❌ 복구 구문(BIP-39 시드)
- ❌ account_id(구문에서 파생됨)
- ❌ 기기 개인 키(TPM/Secure Enclave 내)
- ❌ 어떤 트리 리프가 어떤 사용자에게 속하는지
- ❌ 사용자 Merkle 경로(클라이언트 측에서 계산됨)
- ❌ 사용자의 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를 읽어 주세요.

저장소를 포크합니다
기능 브랜치를 생성합니다 (git checkout -b feature/amazing)
변경 사항을 커밋합니다 (git commit -m 'Add amazing feature')
브랜치에 푸시합니다 (git push origin feature/amazing)
풀 리퀘스트를 생성합니다

🔒 보안

보안 문제를 발견하셨나요? 책임 있는 공개를 위해 SECURITY.md를 참조하세요.

취약점에 대해 공개 이슈를 열지 마세요.

📄 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

🔄 변경 로그

v1.3.0 - 비밀번호 없는 인증 (2024)

주요 변경 사항:

✅ 비밀번호 없는 인증 - BIP-39 복구 구문 + 지문
✅ 단일 필드 회로 - BIP-39 시드에서 파생된 account_id
✅ 디바이스 링 서명 - 사용자당 1024개 중 1개의 디바이스 익명성
✅ 다중 디바이스 지원 - 2개 디바이스에서 동일한 계정 사용
✅ 하드웨어 바인딩 키 - WebAuthn TPM/Secure Enclave 통합
✅ Blake3 필드 요소 처리 - 디바이스 커밋먼트 자동 변환

아키텍처:

🏗️ 사용자 이름/비밀번호 없음 - 복구 구문 + 지문만으로
🏗️ 클라이언트 측 account_id 파생 (Blake3 + BIP-39)
🏗️ 서버 측 디바이스 트리 저장 (사용자별 격리)
🏗️ 이중 Merkle 트리 검증 (사용자 트리 + 디바이스 트리)
🏗️ 견고한 필드 요소 변환 (Blake3 출력이 필드 모듈러스 이상(>=)인 경우 처리)

v1.2.0 - 클라이언트 측 증명 아키텍처 (2024)