[P4] Implement Zero-Knowledge Proof methods (2 endpoints)

[umwelt]

Overview

Implement zero-knowledge proof API methods to match the ZHTP node's ZK proof system.

Parent Issue

Part of #17 - Priority 4 tasks

Node Status

✅ Both ZK proof endpoints implemented on node (Issue #117 - CLOSED)

Missing Methods

ZK Proofs (2 endpoints)

1. ❌ generateZkProof() - MISSING

   • POST /api/v1/zkp/generate

2. ❌ verifyZkProof() - MISSING

   • POST /api/v1/zkp/verify

TypeScript Types Needed

type ProofType = 'age_over_18' | 'age_range' | 'citizenship_verified' | 'jurisdiction_membership';

interface GenerateProofRequest {
  identity_id: string;
  proof_type: ProofType;
  credential_data: {
    age?: number;
    jurisdiction?: string;
    is_verified_citizen?: boolean;
  };
}

interface ProofData {
  proof_data: string; // Base64-encoded ZK proof
  public_inputs: string[]; // Opaque commitments (no plaintext)
  proof_type: ProofType;
  generated_at: number;
  valid_until: number; // Expires after 24 hours
}

interface GenerateProofResponse {
  status: string;
  proof: ProofData;
  valid_until: number;
}

interface VerifyProofRequest {
  proof: ProofData;
}

interface VerifyProofResponse {
  status: string;
  valid: boolean;
  claim: ProofType;
  verified_at: number;
}

Implementation Tasks

1. Implement Methods

• generateZkProof(request: GenerateProofRequest): Promise<ProofData>
• verifyZkProof(proof: ProofData): Promise<VerifyProofResponse>

2. Add Type Definitions

• Add proof types to src/core/types.ts
• Add ProofType enum
• Add credential data types
• Add proof response types

3. Security & Session Handling

• Add Authorization header with session token
• Handle proof expiration (24 hours)
• Validate proof types before sending
• Handle rate limits in error responses

4. Documentation

• JSDoc for all ZK proof methods
• Document supported proof types
• Add usage examples
• Document security limitations (simulated proofs for now)

5. Testing

• Unit tests for all proof methods
• Test all 4 proof types
• Test proof expiration handling
• Test invalid proof rejection
• Integration tests with node

Proof Types Supported

1. age_over_18

Prove age ≥ 18 without revealing exact age

await client.generateZkProof({
  identity_id: "...",
  proof_type: "age_over_18",
  credential_data: { age: 25 }
});

2. age_range

Prove age in range without revealing exact age

• Ranges: 18-25, 26-40, 41-65, 66+

await client.generateZkProof({
  identity_id: "...",
  proof_type: "age_range",
  credential_data: { age: 30 }
});

3. citizenship_verified

Prove verified citizen status

await client.generateZkProof({
  identity_id: "...",
  proof_type: "citizenship_verified",
  credential_data: { is_verified_citizen: true }
});

4. jurisdiction_membership

Prove membership in jurisdiction

await client.generateZkProof({
  identity_id: "...",
  proof_type: "jurisdiction_membership",
  credential_data: { jurisdiction: "US" }
});

Usage Example

// Generate proof
const proof = await client.generateZkProof({
  identity_id: myIdentity.id,
  proof_type: "age_over_18",
  credential_data: { age: 25 }
});

// Verify proof
const verification = await client.verifyZkProof(proof);
console.log(`Proof valid: ${verification.valid}`); // true
console.log(`Claim: ${verification.claim}`); // "age_over_18"

Security Notes from Node

⚠️ IMPORTANT: Current Implementation Limitation

The current ZK proof implementation uses simulated proofs for testing/demonstration. These are NOT cryptographically sound zero-knowledge proofs.

Current Status:

• ✅ API structure and flow production-ready
• ✅ Suitable for development/testing
• ✅ Suitable for alpha with disclaimers
• ❌ NOT suitable for production privacy-critical use

Production Upgrade:
Migration to Bulletproofs/Plonky2 tracked in node issue #131

Rate Limits:

• Proof generation: 10 requests/hour per IP
• Proof verification: 100 requests/15 min

Proof Expiration:

• Proofs valid for 24 hours after generation
• Expired proofs rejected with error

Privacy:

• Public inputs contain opaque commitments only
• No plaintext credential values exposed
• Salted hashing prevents rainbow table attacks

Acceptance Criteria

• Both ZK proof methods implemented
• All 4 proof types supported
• Type definitions complete
• JSDoc documentation complete
• Security limitations documented
• Usage examples in README
• Unit tests pass
• Integration tests pass

Related Issues

• Parent: [IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference #17
• Node: [API] Zero-knowledge proof endpoints (2 endpoints) The-Sovereign-Network#117 (closed)
• Node Production Upgrade: [Security] Migrate ZK proofs from simulation to true zero-knowledge (Bulletproofs/Plonky2) The-Sovereign-Network#131 (open)
• API Client: [FRONTEND]: Zero-knowledge proof endpoints missing in ZHTP node #6

Estimated Effort

Small-Medium - 3-4 hours