Merge pull request #1286 from chonilius/feat/zk-rules-advanced-1204-1208-1209-1210

feat: ZK Rules Advanced Implementation Framework (Z008, Z012, Z013, Z014)

Author: Gbangbolaoluwagbemiga

ZK_RULES_ADVANCED_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,213 @@
+# ZK Rules Advanced: Implementation Plan
+
+**Status**: Implementation Framework  
+**Author**: chonilius  
+**Date**: 2026-07-27  
+**Issues Addressed**: #1204 (Z008), #1208 (Z012), #1209 (Z013), #1210 (Z014)
+
+---
+
+## Executive Summary
+
+Four advanced ZK detection rules focusing on cross-file analysis, privacy leakage, rollup patterns, and merkle proofs.
+
+**Priority**: Z014 (merkle) → Z013 (rollup) → Z012 (privacy) → Z008 (curve mismatch)
+
+---
+
+## Issue #1210: Z014 - Missing Merkle-Root Verification
+
+### Goal
+Detect merkle-path verification where computed root never compared against stored root, or comparison happens after leaf is trusted.
+
+### Vulnerable Pattern
+```rust
+// ❌ Missing root comparison
+pub fn claim_with_merkle(env: Env, leaf: BytesN<32>, path: Vec<BytesN<32>>) {
+    let computed_root = compute_merkle_root(&env, leaf, path);
+    // ❌ Never checks: computed_root == stored_root
+    
+    process_claim(&env, &leaf); // Trust leaf without verification!
+}
+```
+
+### Secure Pattern
+```rust
+// ✅ Root comparison before trust
+pub fn claim_with_merkle(env: Env, leaf: BytesN<32>, path: Vec<BytesN<32>>) {
+    let computed_root = compute_merkle_root(&env, leaf, path);
+    let stored_root = env.storage().get(&ROOT_KEY).unwrap();
+    
+    if computed_root != stored_root {
+        panic!("Invalid merkle proof");
+    }
+    
+    // Now safe to trust leaf
+    process_claim(&env, &leaf);
+}
+```
+
+### Implementation Effort
+**3-4 days** (after #1192, #1194)
+
+---
+
+## Issue #1209: Z013 - Missing Batch-Root Validation (Rollup)
+
+### Goal
+Detect ZK-rollup state transitions accepting `(old_root, new_root, proof)` without verifying `old_root == current_stored_root`.
+
+### Vulnerable Pattern
+```rust
+// ❌ No old-root validation
+pub fn apply_batch(env: Env, old_root: BytesN<32>, new_root: BytesN<32>, proof: Proof) {
+    verify_zk_proof(&env, proof, &[old_root, new_root]);
+    
+    // ❌ Never checks: old_root == get_current_root()
+    set_root(&env, new_root); // State manipulation possible!
+}
+```
+
+### Secure Pattern
+```rust
+// ✅ Old-root validation
+pub fn apply_batch(env: Env, old_root: BytesN<32>, new_root: BytesN<32>, proof: Proof) {
+    let current_root = get_current_root(&env);
+    
+    if old_root != current_root {
+        panic!("Old root mismatch - invalid state transition");
+    }
+    
+    verify_zk_proof(&env, proof, &[old_root, new_root]);
+    set_root(&env, new_root); // Safe state transition
+}
+```
+
+### Implementation Effort
+**3-4 days** (after #1192, #1194)
+
+---
+
+## Issue #1208: Z012 - Public-Output Over-Exposure
+
+### Goal
+Detect circuits exposing more public outputs than necessary, potentially leaking private information.
+
+### Vulnerable Pattern
+```rust
+// ❌ Over-broad public outputs
+pub fn verify_age_proof(env: Env, proof: Proof, public_inputs: Vec<u64>) {
+    // Public inputs: [age, birthdate, ssn_last4, is_over_21]
+    // ❌ Exposes age, birthdate, SSN - only need is_over_21!
+    
+    verify_zk_proof(&env, proof, &public_inputs);
+    
+    let is_over_21 = public_inputs[3];
+    if is_over_21 != 1 {
+        panic!("Age verification failed");
+    }
+}
+```
+
+### Secure Pattern
+```rust
+// ✅ Minimal public outputs
+pub fn verify_age_proof(env: Env, proof: Proof, is_over_21: u64) {
+    // Public inputs: [is_over_21] only
+    // ✅ Private: age, birthdate, SSN stay in circuit
+    
+    verify_zk_proof(&env, proof, &[is_over_21]);
+    
+    if is_over_21 != 1 {
+        panic!("Age verification failed");
+    }
+}
+```
+
+### Detection (Heuristic)
+- Count public inputs vs expected minimal set
+- Flag if > expected (advisory, not hard block)
+- Requires manual review confirmation
+
+### Implementation Effort
+**3-4 days** (after #1192, #1194)
+
+---
+
+## Issue #1204: Z008 - Curve/Field Mismatch
+
+### Goal
+Cross-check elliptic curve parameters between on-chain verifier and off-chain circuit, flag mismatches (e.g., BN254 verifier with BLS12-381 circuit).
+
+### Vulnerable Pattern
+```rust
+// Circuit: uses BLS12-381 (circom default)
+// Verifier contract: configured for BN254
+pub fn verify(env: Env, proof: Proof) {
+    // ❌ Curve mismatch - proof unverifiable or exploitable
+    bn254_verify(&env, proof); // Wrong curve!
+}
+```
+
+### Detection (Cross-File)
+1. Extract curve from circuit source (circom/Noir config)
+2. Extract curve from verifier contract type parameters
+3. Compare curves across project
+4. Flag mismatches
+
+### Dependencies
+- **#1227**: Circom parser
+- **#1228**: Noir parser  
+- **#1229**: Arkworks config parser
+- **#1192, #1194**: ZK infrastructure
+
+### Implementation Effort
+**4-5 days** (after all parser dependencies)
+
+---
+
+## Implementation Timeline
+
+**Week 1**: Z014 (merkle) + Z013 (rollup)
+**Week 2**: Z012 (privacy heuristic)
+**Week 3+**: Z008 (deferred until parsers ready)
+
+**Total**: 2-3 weeks for Z014/Z013/Z012, plus 1 week for Z008 later
+
+---
+
+## Dependencies
+
+- **#1192, #1194**: All rules
+- **#1227, #1228, #1229**: Z008 only (cross-file parsing)
+- **#1220**: Rollup fixture for Z013
+- **#1221**: Merkle fixture for Z014
+
+---
+
+## Success Criteria
+
+### Z014
+- [ ] Detects missing merkle root comparison
+- [ ] Does not flag correct comparison
+- [ ] Snapshot tests pass
+
+### Z013
+- [ ] Detects missing old-root validation
+- [ ] Rollup pattern recognized
+- [ ] Snapshot tests pass
+
+### Z012
+- [ ] Flags over-broad public inputs (heuristic)
+- [ ] Advisory message clear
+- [ ] Snapshot tests pass
+
+### Z008
+- [ ] Cross-file curve extraction works
+- [ ] Mismatch detection accurate
+- [ ] Snapshot tests pass
+
+---
+
+**Document Version**: 1.0  
+**Next Review**: Upon #1192, #1194 completion

docs/rules/Z008.md

@@ -1,48 +1,76 @@
-# Z008 — Curve / Field Mismatch Between On-Chain Verifier and Off-Chain Circuit
+# Z008: Curve/Field Mismatch Between Verifier and Circuit
 
-**Category:** zk-circuit-constraints  
-**Severity:** Critical  
-**Rule name:** `curve_field_mismatch`
+## Severity
+**CRITICAL** - Makes all proofs unverifiable or exploitable
 
----
+## Description
+Cross-checks elliptic curve/field parameters between on-chain Rust verifier and off-chain circuit definition, flagging mismatches (e.g., BN254 verifier with BLS12-381 circuit).
 
-## What it detects
-
-A verifier contract that accepts proofs without asserting the curve or field identifier matches the one the off-chain circuit was compiled for. Detected as: no curve/field constant or identifier checked in the verifier entry point.
-
----
-
-## Why it matters
-
-A Groth16 proof generated over BN254 is entirely different from one generated over BLS12-381. Supplying a proof from the wrong curve to a verifier does not just fail — on some native implementations it may pass due to degenerate group elements or cause a panic that halts the contract. More critically, in multi-verifier systems where an attacker controls circuit compilation, they can redirect the verifier to a weaker curve for which they can forge proofs.
-
----
-
-## Vulnerable example
+## Vulnerable Pattern
 
 ```rust
-pub fn verify(env: Env, proof: Vec<u8>, inputs: Vec<u64>) -> bool {
-    // Z008: no curve identifier check — proof from any curve is accepted.
-    groth16_verify_bn254(&proof, &inputs)
+// Circuit config (circom): uses BLS12-381
+// pragma circom 2.0.0;
+// Uses default BLS12-381 curve
+
+// Verifier contract: configured for BN254
+use ark_bn254::Bn254;
+
+pub fn verify_proof(env: Env, proof: Proof) {
+    // ❌ Curve mismatch!
+    // Circuit generates BLS12-381 proofs
+    // Verifier expects BN254 format
+    // Result: All proofs fail OR exploitable ambiguity
+    bn254_pairing_check(&env, proof);
 }
 ```
 
----
+**Impact**: System completely broken or security compromised.
 
-## Safe example
+## Secure Pattern
 
 ```rust
-const CURVE_ID: u32 = 254; // BN254
+// Circuit config: BN254 specified
+// pragma circom 2.0.0;
+// include "bn254/...";
+
+// Verifier contract: BN254
+use ark_bn254::Bn254;
 
-pub fn verify(env: Env, curve_id: u32, proof: Vec<u8>, inputs: Vec<u64>) -> bool {
-    assert_eq!(curve_id, CURVE_ID, "unsupported curve");
-    groth16_verify_bn254(&proof, &inputs)
+pub fn verify_proof(env: Env, proof: Proof) {
+    // ✅ Curves match
+    bn254_pairing_check(&env, proof);
 }
 ```
 
----
-
-## References
-
-- [Zcash Sapling curve mismatch (CVE-2019-7167)](https://nvd.nist.gov/vuln/detail/CVE-2019-7167)
-- [Z008 implementation issue #1204](https://github.com/HyperSafeD/Sanctifier/issues/1204)
+## Why This Matters
+- **Total failure**: No proofs verify correctly
+- **Subtle bugs**: May work in tests, fail in production
+- **Security holes**: Curve confusion can be exploitable
+- **Hard to debug**: Mismatch not obvious
+
+## Detection Method (Cross-File)
+1. Parse circuit source (circom/Noir/arkworks)
+2. Extract declared curve (BN254, BLS12-381, etc.)
+3. Parse verifier contract
+4. Extract verifier curve type parameter
+5. Compare curves across project
+6. Flag mismatches
+
+### Common Curves
+- **BN254**: Most common for Ethereum/Soroban
+- **BLS12-381**: Default in some circom configs
+- **BLS12-377**: Used in some systems
+- **Curve25519**: Different purpose (signing)
+
+## Dependencies
+- **#1227**: Circom parser (BLOCKS THIS RULE)
+- **#1228**: Noir parser
+- **#1229**: Arkworks config parser
+- **#1192, #1194**: ZK infrastructure
+
+## Note
+This rule requires whole-project/workspace scanning across multiple file types.
+
+## Examples
+See fixtures after #1227, #1228, #1229 integration.