From c11c9af143ca1cf675569c3a87b0e9e3f85e3a35 Mon Sep 17 00:00:00 2001 From: Justin Hernandez Date: Tue, 16 Sep 2025 16:33:31 -0700 Subject: [PATCH] chore: update monorepo artifacts (#1079) * remove unneeded artifacts, skip building circuits * update md files --- .cursor/rules/technical-specification.mdc | 161 ------------- .cursorrules | 20 -- README.md | 1 - app/AGENTS.md | 2 - docs/nfc-implementation.md | 273 ---------------------- package.json | 6 +- 6 files changed, 3 insertions(+), 460 deletions(-) delete mode 100644 .cursor/rules/technical-specification.mdc delete mode 100644 docs/nfc-implementation.md diff --git a/.cursor/rules/technical-specification.mdc b/.cursor/rules/technical-specification.mdc deleted file mode 100644 index c48bba6ac..000000000 --- a/.cursor/rules/technical-specification.mdc +++ /dev/null @@ -1,161 +0,0 @@ -# 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. diff --git a/.cursorrules b/.cursorrules index d0cb43a51..7a2e7d399 100644 --- a/.cursorrules +++ b/.cursorrules @@ -48,7 +48,6 @@ ## Core Workflows 1. Document Verification Flow -- NFC chip data extraction and validation - Zero-knowledge proof generation for privacy - Multi-stage attestation verification - Cross-chain verification support @@ -128,25 +127,6 @@ This is a React Native identity verification app with NFC passport reading, zero - Test utilities in `tests/__setup__/databaseMocks.ts` - Mock database instance for testing -## NFC Implementation - -### Cross-Platform Architecture -- iOS: Custom PassportReader Swift module -- Android: Custom RNPassportReaderModule Kotlin implementation -- Unified JavaScript interface with platform detection - -### Authentication Methods -- MRZ Key: Derived from passport number, DOB, and expiry date -- CAN (Card Access Number): 6-digit number for PACE authentication -- PACE: Password Authenticated Connection Establishment -- BAC fallback when PACE fails - -### Error Handling -- Multiple BAC attempts with delays -- Graceful degradation from PACE to BAC -- Real-time status updates and haptic feedback -- Comprehensive error boundaries - ## Code Organization ### File Structure diff --git a/README.md b/README.md index fbd81c41d..ae42dc592 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,6 @@ For detailed development patterns and conventions, see: - **[Development Patterns](docs/development-patterns.md)** - React Native architecture, navigation, state management, and code organization - **[Testing Guide](docs/testing-guide.md)** - Jest configuration, mock patterns, testing strategies, and E2E testing -- **[NFC Implementation](docs/nfc-implementation.md)** - Cross-platform NFC passport reading, authentication methods, and error handling These guides provide comprehensive context for AI-assisted development with ChatGPT Codex, Cursor, and CodeRabbit AI. diff --git a/app/AGENTS.md b/app/AGENTS.md index c62a73e85..e4aa6d220 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -24,7 +24,6 @@ Before creating a PR for the mobile app: - [ ] iOS build succeeds: `yarn ios` (simulator) - [ ] Android build succeeds: `yarn android` (emulator/device) - [ ] Web build succeeds: `yarn web` -- [ ] NFC functionality tested (if applicable) - [ ] No sensitive data in logs (PII, credentials, tokens) ### AI Review Preparation @@ -52,7 +51,6 @@ After PR creation: ### Review Integration - [ ] Address CodeRabbitAI feedback - [ ] Resolve any security warnings -- [ ] Verify NFC/security features still work - [ ] Confirm no sensitive data exposed ## Recommended Workflow diff --git a/docs/nfc-implementation.md b/docs/nfc-implementation.md deleted file mode 100644 index faa5e3f07..000000000 --- a/docs/nfc-implementation.md +++ /dev/null @@ -1,273 +0,0 @@ -# NFC Implementation Guide - -## Architecture Overview - -### Cross-Platform Implementation -The NFC passport reading system uses platform-specific native modules with a unified JavaScript interface: - -- **iOS**: Custom PassportReader Swift module -- **Android**: Custom RNPassportReaderModule Kotlin implementation -- **JavaScript**: Unified interface with platform detection - -### Data Flow -1. User initiates scan with passport details (MRZ data) -2. Platform-specific native module handles NFC communication -3. Raw passport data returned to JavaScript -4. Data parsed and normalized for processing -5. Zero-knowledge proof generation and verification - -## iOS Implementation - -### PassportReader Module -The iOS implementation uses a custom Swift module with NFC capabilities: - -```swift -func readPassport( - password: String, - type: PACEPasswordType, - tags: [NFCISO7816Tag], - skipCA: Bool, - skipPACE: Bool, - useExtendedMode: Bool, - usePacePolling: Bool, - customDisplayMessage: ((NFCViewDisplayMessage) -> String?)? -) async throws -> Passport -``` - -### Authentication Methods -- **MRZ Key**: Derived from passport number, date of birth, and expiry date -- **CAN (Card Access Number)**: 6-digit number for PACE authentication -- **PACE**: Password Authenticated Connection Establishment - -### Error Handling -- Comprehensive try-catch blocks for each authentication step -- Graceful fallback from PACE to BAC when needed -- User-friendly error messages for different failure scenarios - -## Android Implementation - -### RNPassportReaderModule -The Android implementation uses a custom Kotlin module: - -```kotlin -@ReactMethod -fun scan(opts: ReadableMap, promise: Promise) { - // NFC adapter setup and validation - // Intent handling for tag discovery - // Async task execution for passport reading -} -``` - -### Authentication Flow -1. **PACE Authentication**: Primary method using CAN or MRZ key -2. **BAC Fallback**: Basic Access Control when PACE fails -3. **Retry Logic**: Multiple attempts with delays between retries - -### Intent Handling -- `onNewIntent` in MainActivity routes to RNPassportReaderModule -- Foreground dispatch for NFC tag discovery -- Proper lifecycle management (resume/pause) - -### Android-Specific Workarounds -On certain Android devices, NFC scanner fails to activate on app launch. The automatic workaround uses an event-driven approach: -- `scan()` method sets `shouldEnableNfcOnResume=true` -- Programmatically backgrounds the app using `moveTaskToBack(true)` -- Waits 500ms, then foregrounds it -- NFC enablement happens in `onHostResume()` when activity is properly in foreground - -## JavaScript Interface - -### Unified Scan Function -```typescript -export const scan = async (inputs: Inputs) => { - return Platform.OS === 'android' - ? await scanAndroid(inputs) - : await scanIOS(inputs); -}; -``` - -### Input Parameters -```typescript -interface Inputs { - passportNumber: string; - dateOfBirth: string; - dateOfExpiry: string; - canNumber?: string; - useCan?: boolean; - skipPACE?: boolean; - skipCA?: boolean; - extendedMode?: boolean; - usePacePolling?: boolean; -} -``` - -### Response Processing -- Platform-specific response parsing -- Data normalization for consistent format -- Error handling and validation - -## Authentication Methods - -### MRZ Key Generation -The MRZ key is derived from passport data: -```typescript -const mrzKey = getMRZKey( - passportNumber: string, - dateOfBirth: string, - dateOfExpiry: string -); -``` - -### PACE Authentication -- **Primary Method**: Uses CAN or MRZ key for authentication -- **Extended Mode**: Enhanced security features -- **Polling**: Optional polling mechanism for better reliability - -### BAC (Basic Access Control) -- **Fallback Method**: Used when PACE fails -- **Multiple Attempts**: Up to 3 attempts with delays -- **Error Recovery**: Graceful handling of authentication failures - -## Error Handling Patterns - -### Authentication Failures -- **Access Denied**: Invalid credentials or expired passport -- **BAC Denied**: Basic Access Control failure -- **PACE Exception**: Password Authenticated Connection Establishment failure -- **Card Exception**: General NFC communication issues - -### Retry Mechanisms -- Multiple BAC attempts with delays between retries -- Graceful degradation from PACE to BAC -- Timeout handling for slow operations -- User feedback during retry attempts - -### User Feedback -- Real-time status updates during scanning -- Haptic feedback for different states -- Clear error messages for troubleshooting -- Progress indicators for long operations - -## Performance Optimizations - -### Timeout Management -- Configurable timeouts for different operations -- Platform-specific timeout values -- Graceful timeout handling with user feedback - -### Memory Management -- Proper cleanup of NFC connections -- Resource disposal in finally blocks -- Memory leak prevention -- Component lifecycle management - -### Debug Logging -- Conditional debug logging based on environment -- Performance timing for scan operations -- Detailed error logging for troubleshooting -- Analytics integration for performance monitoring - -## Security Considerations - -### Data Protection -- Sensitive data not logged in production -- Secure storage of authentication keys -- Proper cleanup of sensitive data -- Memory protection for cryptographic operations - -### Certificate Validation -- Document Signer Certificate (DSC) validation -- Certificate chain verification -- Trust store management -- Certificate revocation checking - -### Privacy Features -- Zero-knowledge proof generation -- Selective attribute revelation -- Privacy-preserving age verification -- Identity commitment privacy - -## Testing Strategy - -### Mock Implementations -- Comprehensive mocks for testing without hardware -- Platform-specific mock data -- Error scenario testing -- Performance testing with simulated delays - -### Integration Testing -- Real device testing for critical paths -- Platform-specific test scenarios -- Performance benchmarking -- Security testing with realistic, synthetic passport data (NEVER real user data) - -### Test Data -- Mock passport data for unit tests -- Test certificates for validation -- Error scenarios for edge case testing -- Performance benchmarks for optimization - -## Platform-Specific Considerations - -### iOS -- NFC capabilities require iOS 13+ -- Background NFC reading limitations -- Privacy permissions and user consent -- App Store review requirements - -### Android -- NFC hardware requirements -- Permission handling -- Background processing limitations -- Device-specific workarounds - -### Web -- No NFC support (fallback to other methods) -- Alternative authentication flows -- Cross-platform compatibility - -## Common Issues and Solutions - -### NFC Not Detected -- Check device NFC capabilities -- Verify NFC is enabled in settings -- Ensure app has proper permissions -- Try device-specific workarounds - -### Authentication Failures -- Verify passport data accuracy -- Check passport expiration -- Try alternative authentication methods -- Implement retry logic with delays - -### Performance Issues -- Optimize timeout values -- Implement proper cleanup -- Monitor memory usage -- Profile NFC operations - -## Best Practices - -### Error Handling -- Always implement comprehensive error handling -- Provide user-friendly error messages -- Log errors for debugging -- Implement graceful degradation - -### Performance -- Optimize timeout values for your use case -- Implement proper resource cleanup -- Monitor memory usage -- Profile NFC operations - -### Security -- Never log sensitive data -- Implement proper certificate validation -- Use secure storage for keys -- Follow platform security guidelines - -### User Experience -- Provide clear feedback during operations -- Implement haptic feedback -- Show progress indicators -- Handle edge cases gracefully diff --git a/package.json b/package.json index 43312863f..f3b7308f6 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "packages/mobile-sdk-alpha/demo-app" ], "scripts": { - "build": "yarn workspaces foreach --topological-dev --parallel --exclude @selfxyz/contracts -i --all run build", + "build": "yarn workspaces foreach --topological-dev --parallel --exclude @selfxyz/contracts --exclude @selfxyz/circuits -i --all run build", "check:versions": "node scripts/check-package-versions.mjs", "format": "SKIP_BUILD_DEPS=1 yarn format:root && yarn format:github && SKIP_BUILD_DEPS=1 yarn workspaces foreach --parallel -i --all --exclude self-workspace-root run format", "format:github": "yarn prettier --parser yaml --write .github/**/*.yml --single-quote false", @@ -31,11 +31,11 @@ "resolutions": { "@babel/core": "^7.28.4", "@babel/runtime": "^7.28.4", - "@typescript-eslint/eslint-plugin": "^8.43.0", - "@typescript-eslint/parser": "^8.43.0", "@types/node": "^22.18.3", "@types/react": "^18.3.4", "@types/react-dom": "^18.3.0", + "@typescript-eslint/eslint-plugin": "^8.43.0", + "@typescript-eslint/parser": "^8.43.0", "react": "^18.3.1", "react-dom": "^18.3.1", "react-native": "0.76.9"