self/.cursor/rules/technical-specification.mdc

# Technical Specification: Identity Verification System

## 1. Zero-Knowledge Proof Circuits

### Register Circuit Implementation
- **Circuit Location**: `circuits/circuits/register/register.circom`
- **Purpose**: Generate identity commitments and nullifiers for passport/ID verification
- **Input Validation**:
  - Passport number: normalized (whitespace/punctuation removed)
  - Date of birth: ISO 8601 format (YYYY-MM-DD)
  - Expiry date: ISO 8601 format (YYYY-MM-DD)
  - Country code: ISO 3166-1 alpha-3 format
- **Output**: Poseidon hash commitment with domain separation `"register-v1"`

### DSC Proof Circuit
- **Circuit Location**: `circuits/circuits/dsc/dsc.circom`
- **Purpose**: Validate Document Signer Certificate authenticity
- **Validation Steps**:
  - Certificate chain verification (CSCA → DSC)
  - Signature algorithm support (RSA-2048, ECDSA-P256)
  - Revocation list checking via Merkle inclusion
- **Memory Constraints**: <300MB peak memory usage

### Disclosure Proof Circuit
- **Circuit Location**: `circuits/circuits/disclose/vc_and_disclose.circom`
- **Purpose**: Selective attribute revelation with privacy preservation
- **Supported Disclosures**:
  - Age verification: "olderThan" with day granularity
  - Country verification: forbidden country checks
  - Document type: passport vs EU ID card
- **Privacy**: No raw PII leaves device, only commitments

## 2. Data Models & Structures

### Identity Commitment Format
```typescript
interface IdentityCommitment {
  commitment: string; // Poseidon hash
  nullifier: string; // Domain-separated nullifier
  timestamp: number; // UTC timestamp
  version: string; // Circuit version
  documentType: 'passport' | 'eu_id_card';
}
```

### DSC Key Commitment
```typescript
interface DSCKeyCommitment {
  publicKeyHash: string; // Poseidon hash of public key
  certificateChain: string[]; // Certificate chain hashes
  revocationStatus: boolean; // Revocation list inclusion
  issuer: string; // Issuing country code
}
```

### Verification Configuration
```typescript
interface VerificationConfig {
  circuitVersion: string; // Semantic versioning
  complianceRules: ComplianceRule[];
  timeWindow: number; // 24-hour window in seconds
  clockDrift: number; // ±5 minutes tolerance
  trustAnchors: string[]; // Trusted certificate authority roots
  revocationRoots: string[]; // Certificate revocation list roots
  timeSource: string; // NTP server for time validation
  nullifierScope: string; // Domain separation for nullifiers
}
```

## 3. Identity Verification Workflows

### Passport Verification Path
1. **NFC Data Extraction**: Read passport chip via NFC
2. **MRZ Validation**: Parse and validate Machine Readable Zone
3. **DSC Verification**: Validate Document Signer Certificate
4. **Register Proof**: Generate identity commitment
5. **Compliance Check**: OFAC screening via zero-knowledge proofs
6. **Attestation**: Create privacy-preserving attestation

### EU ID Card Verification Path
1. **Similar to passport** with EU-specific compliance checks
2. **Additional validation**: EU document format requirements
3. **Regional compliance**: EU-specific forbidden country lists

### Cross-Chain Verification
- **Commitment linking**: Link commitments across different chains
- **Nullifier tracking**: Prevent duplicate registrations across chains
- **Attestation portability**: Share attestations across ecosystems

## 4. Implementation Requirements

### Cryptographic Standards
- **Hash Function**: Poseidon (optimized for ZK circuits)
- **Field Size**: BN254 scalar field (254 bits)
- **Key Sizes**: RSA-2048 minimum, ECDSA-P256 preferred
- **Randomness**: CSPRNG with entropy validation
- **Signature Scheme**: EdDSA over BabyJubJub (zk-friendly)
- **MRZ Validation**: Check digits validation for data integrity
- **Authentication**: Passive/active authentication modes
- **NFC Security**: Secure channel establishment with PACE/BAC

### Performance Constraints
- **Proof Generation**: <60s on mid-tier mobile devices
- **Memory Usage**: <300MB peak memory
- **Bundle Size**: <2MB SDK bundle size
- **Startup Time**: <1s SDK initialization

### Security Requirements
- **PII Protection**: No raw PII in logs or network traffic
- **Key Management**: Secure key storage with rotation
- **Audit Trails**: Privacy-preserving audit logs
- **Input Validation**: Comprehensive input sanitization
- **OFAC Anchoring**: Signed list snapshots with freshness guarantees
- **Cross-Chain Privacy**: Domain-separated nullifiers prevent linkability
- **Hardware Security**: Hardware keystore requirements for mobile
- **TLS Pinning**: Certificate pinning for secure communications
- **Telemetry Minimization**: Minimal data collection and transmission

## 5. Error Handling & Recovery

### Circuit Errors
- **Invalid Input**: Clear error codes for malformed data
- **Proof Failure**: Graceful degradation with retry logic
- **Memory Limits**: Client-side only - no server-side proving fallback
- **Timeout Handling**: Configurable timeouts with progress events

### Network Errors
- **Retry Logic**: Exponential backoff with jitter
- **Offline Support**: Cached verification data
- **Graceful Degradation**: Fallback verification methods
- **Error Reporting**: Non-identifying error metadata

## 6. Testing Requirements

### Circuit Testing
- **Unit Tests**: Individual circuit component testing
- **Integration Tests**: End-to-end proof generation
- **Performance Tests**: Memory and timing validation
- **Security Tests**: Cryptographic validation

### SDK Testing
- **Cross-Platform**: iOS, Android, Web compatibility
- **Memory Profiling**: Memory leak detection
- **Bundle Analysis**: Tree-shaking validation
- **Integration Testing**: App integration validation

## 7. Deployment & Versioning

### Circuit Versioning
- **Semantic Versioning**: MAJOR.MINOR.PATCH
- **Backward Compatibility**: MINOR versions maintain compatibility
- **Migration Strategy**: Graceful migration with deprecation windows
- **Rollback Plan**: Emergency rollback procedures

### SDK Distribution
- **Package Management**: npm/yarn distribution
- **Version Compatibility**: Circuit version compatibility matrix
- **Documentation**: Comprehensive API documentation
- **Examples**: Integration examples and demos

This specification provides concrete implementation guidance for the identity verification system with specific technical requirements, performance constraints, and development patterns.