Legion ZK Auth 🛡️

Authentification véritablement zéro-connaissance avec signatures en anneau d'appareils liées au matériel

🎯 Qu'est-ce que Legion ?

Legion est un système d'authentification zéro-connaissance sans mot de passe qui prouve que vous êtes autorisé sans révéler qui vous êtes.

Authentifiez-vous en utilisant uniquement votre empreinte digitale + phrase de récupération de 24 mots (comme MetaMask). Pas de nom d'utilisateur, pas de mot de passe, aucun secret côté serveur.

Fonctionnalités clés

✅ Authentification sans mot de passe : phrase de récupération BIP-39 + empreinte digitale (pas de nom d'utilisateur / mot de passe)
✅ Véritable zéro-connaissance : le serveur n'apprend jamais votre identité (1 sur 1 million d'utilisateurs)
✅ Anonymat de l'appareil : lié au matériel avec signatures en anneau (1 sur 1 000 appareils)
✅ Aucune configuration de confiance : Halo2 PLONK (configuration transparente)
✅ Sécurité matérielle : liaison WebAuthn TPM/Secure Enclave
✅ Protection contre le rejeu : Nullifiers + horodatages
✅ Sécurité de session : les tags de liaison empêchent le vol
✅ Prise en charge multi-appareils : utilisez le même compte sur 2 appareils (ordinateur portable + téléphone)
✅ Limitation de débit : 5 tentatives/heure (des erreurs génériques empêchent l'énumération)
✅ Révocation d'appareil : bloquez instantanément les appareils volés

🔒 Garanties de sécurité (v1.3.0)

🚀 Démarrage rapide (Une seule commande !)

Prérequis

Docker (inclut Docker Compose)

Installer et exécuter```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

**Et voilà !** Ouvrez http://localhost dans votre navigateur.

### Ce qui est installé
- ✅ Redis (stockage de session)
- ✅ Legion Server (vérificateur de preuve ZK)
- ✅ Frontend (client WASM)
- ✅ Nginx (proxy inverse)

**Performance** : Inscription ~5 s, Authentification ~2 min (génération de preuve k=14)

---

### Installation manuelle (sans Docker)

<details>
<summary>Cliquez pour développer l'installation manuelle</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

Pour le déploiement en production, voir DEPLOYMENT.md

📊 Performances

Benchmarks de vérification

Matériel de test : Lenovo IdeaPad 3 - Intel Core i3 11th Gen
Remarque : Les performances peuvent varier selon les spécifications matérielles.

k=12 (Développement/Test)

Détail :

🔥 Démarrage à froid (première vérification) : ~8.4s (inclut paramètres + génération de clés + vérification)
⚡ Vérifications suivantes (avec mise en cache) : ~108ms (paramètres/clés en cache)
💾 Surcharge de preuve : ~326 octets par entrée publique
🔐 Complexité du circuit : Arbre utilisateur (20 niveaux) + Arbre d'appareils (10 niveaux) + liaisons

k=14 (Production - Recommandée)

Détail :

🔥 Démarrage à froid (première vérification) : ~115s (inclut paramètres + génération de clés + vérification)
⚡ Vérifications suivantes (avec mise en cache) : ~967ms (paramètres/clés en cache)
💾 Surcharge de preuve : ~339 octets par entrée publique
🔐 Complexité du circuit : Arbre utilisateur (20 niveaux) + Arbre d'appareils (10 niveaux) + liaisons

Important : La génération des paramètres et la génération de clés sont des coûts uniques qui peuvent être mis en cache. Une fois en cache, la vérification ne prend que ~108-967ms selon la valeur de k. L'implémentation actuelle ne met pas encore les paramètres en cache.

Pourquoi plus lent que les anciens benchmarks ? Le circuit sans mot de passe vérifie désormais DEUX arbres de Merkle (utilisateur + appareil) au lieu d'un seul, offrant un véritable anonymat au niveau de l'appareil (1 appareil sur 1024 par utilisateur).

🏗️ Architecture

📖 Pour un flux d'authentification détaillé, étape par étape, avec les détails cryptographiques, voir ARCHITECTURE_FLOW.md

Composants du système```

┌─────────────────────────────────────────────────────────────────────────┐ │ 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 │ └────────────────────────┘ └───────────────────────────┘

### Flux d'authentification (Simplifié)```
┌─────────────┐                                                ┌──────────────┐
│   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}
       │                                                              │

🔍 Vous voulez plus de détails? Voir ARCHITECTURE_FLOW.md pour:

Opérations cryptographiques étape par étape
Détails des contraintes de circuit
Explications des propriétés de sécurité
Mécanismes de résistance aux attaques

Analyse approfondie de la sécurité des sessions```

┌─────────────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └─────────────────────────────────────────────────────────────────────────┘

## 🔐 Propriétés Zero-Knowledge

### Ce que le serveur sait
- ✅ Quelqu'un dans l'ensemble d'anonymat s'est authentifié
- ✅ La preuve est cryptographiquement valide
- ✅ Même utilisateur+appareil via le tag de liabilité
- ✅ État de la limite de débit (tentatives restantes)
- ✅ État de révocation de l'appareil
- ✅ Nombre total d'utilisateurs enregistrés
- ✅ Racine de l'arbre de Merkle (publique)

### Ce que le serveur NE PEUT PAS savoir
- ❌ Quel utilisateur spécifique (1 sur 1M)
- ❌ Quel appareil spécifique (1 sur 1K par utilisateur)
- ❌ Phrase de récupération (graine BIP-39)
- ❌ account_id (dérivé de la phrase)
- ❌ Clé privée de l'appareil (dans TPM/Secure Enclave)
- ❌ Quelle feuille de l'arbre appartient à quel utilisateur
- ❌ Chemin Merkle de l'utilisateur (calculé côté client)
- ❌ Position tree_index de l'utilisateur

## 📦 Déploiement

Voir [DEPLOYMENT.md](https://github.com/deadends/legion/blob/HEAD/docs/DEPLOYMENT.md) pour le guide détaillé de déploiement en production.

### Déploiement rapide avec 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

Variables d'environnement```env

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

## 🧪 Tests```bash
# Run all tests
cargo test --workspace

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

# Benchmark
cargo bench

📚 Documentation

Flux d'architecture - Flux d'authentification détaillé
Correctifs de sécurité - Améliorations de sécurité v1.1.0
Guide de déploiement - Déploiement en production
Politique de sécurité - Garanties de sécurité et signalement
Contribuer - Directives de contribution

🛠️ Pile technologique

Preuves ZK : Halo2 (PLONK) - Configuration transparente, aucune cérémonie de confiance
Courbes : Pasta (Pallas/Vesta) - Cycle de courbes pour la récursion
Hachage : Blake3 (dérivation d'identifiants), Poseidon (adapté au ZK)
Dérivation de clés : BIP-39 (phrase mnémonique de 24 mots)
Matériel : WebAuthn niveau 2 (TPM 2.0, Secure Enclave)
Backend : Rust, Axum, Redis (sessions), RocksDB (persistance)
Frontend : Rust→WASM (prouveur), JavaScript Vanilla (interface), IndexedDB (stockage)
Déploiement : Docker, Nginx, systemd

🤝 Contribuer

Les contributions sont les bienvenues ! Veuillez d'abord lire CONTRIBUTING.md.

Forkez le dépôt
Créez une branche de fonctionnalité (git checkout -b feature/amazing)
Commitez les modifications (git commit -m 'Add amazing feature')
Poussez vers la branche (git push origin feature/amazing)
Ouvrez une pull request

🔒 Sécurité

Vous avez trouvé un problème de sécurité ? Consultez SECURITY.md pour une divulgation responsable.

N'ouvrez PAS de problèmes publics pour les vulnérabilités.

📄 Licence

Licence MIT - consultez le fichier LICENSE pour plus de détails.

🔄 Journal des modifications

v1.3.0 - Authentification sans mot de passe (2024)

Changements majeurs :

✅ Authentification sans mot de passe - Phrase de récupération BIP-39 + empreinte digitale
✅ Circuit à champ unique - account_id dérivé de la graine BIP-39
✅ Signatures en anneau d'appareils - Anonymat d'appareil 1-sur-1024 par utilisateur
✅ Prise en charge multi-appareils - Utilisez le même compte sur 2 appareils
✅ Clés liées au matériel - Intégration WebAuthn TPM/Secure Enclave
✅ Gestion des éléments de champ Blake3 - Conversion automatique pour les engagements d'appareils

Architecture :

🏗️ Pas de nom d'utilisateur/mot de passe - seulement phrase de récupération + empreinte digitale
🏗️ Dérivation de account_id côté client (Blake3 + BIP-39)
🏗️ Arbres d'appareils stockés côté serveur (isolation par utilisateur)
🏗️ Vérification à double arbre de Merkle (arbre utilisateur + arbre d'appareils)
🏗️ Conversion robuste des éléments de champ (gère les sorties Blake3 >= module du champ)

v1.2.0 - Architecture de preuve côté client (2024)