github/self
1
1
Fork 0
mirror of https://github.com/selfxyz/self.git synced 2026-01-06 21:34:13 -05:00
Code Issues Packages Projects Releases Wiki Activity

chore: update monorepo artifacts (#1079)

Browse Source 
* remove unneeded artifacts, skip building circuits

* update md files
This commit is contained in:
Justin Hernandez
2025-09-16 16:33:31 -07:00
committed by GitHub
parent 8e385cb857
commit c11c9af143
6 changed files with 3 additions and 460 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
.cursor/rules/technical-specification.mdc
View File

@@ -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.

20
.cursorrules
View File

@@ -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

1
README.md
View File

@@ -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.

2
app/AGENTS.md
View File

@@ -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

273
docs/nfc-implementation.md
View File

@@ -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

6
package.json
View File

@@ -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"