diff --git a/packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md b/packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md index aefc9a3b6..88c11b78e 100644 --- a/packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md +++ b/packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md @@ -1,12 +1,78 @@ # Migration Checklist -- [ ] Scanning: define RN adapters for MRZ/NFC; keep NFC lifecycle in app (screen on). -- [ ] Processing: migrate pure helpers (MRZ parse, NFC response parsing) — first: `extractMRZInfo`, `formatDateToYYMMDD`. -- [ ] Validation: port minimal checks from `validateDocument.ts` (stateless subset). -- [ ] Protocol sync: add paginated tree fetch + TTL cache + root verification. -- [ ] Proof inputs: port `provingInputs.ts` (register/disclose first). -- [ ] TEE session: WS wrapper with `AbortSignal`, timeouts, progress. -- [ ] Attestation: essential verification from `attest.ts`. -- [ ] Crypto: WebCrypto-first via adapter; `@noble/*` fallback; no Node crypto. -- [ ] Artifacts: manifest schema + integrity checks; CDN download + cache (storage adapter). -- [ ] Samples: RN + web minimal flows; iOS scheme `OpenPassport`. +> Detailed task prompts are listed in [MIGRATION_PROMPTS.md](./MIGRATION_PROMPTS.md). + +## 1. Processing helpers (MRZ & NFC) + +- Finalize MRZ utilities and add an NFC response parser. +- Re-export helpers through the SDK entry point. + +## 2. Validation module + +- Port stateless document checks. +- Cover validation logic with unit tests. + +## 3. Proof input generation + +- Port register and disclose TEE input helpers. + +## 4. Crypto adapters + +- Runtime-selectable adapter using WebCrypto with `@noble/*` fallbacks. +- Parity tests across implementations. +- Detect WebCrypto availability on React Native/Hermes environments. +- Ensure CSPRNG-backed random number generation. +- Use timing-safe comparison for secret values. + +## 5. TEE session management + +- WebSocket wrapper supporting abort, timeout, and progress events. + +## 6. Attestation verification + +- PCR0 check and public-key extraction. +- Minimal certificate-chain validation. + +## 7. Protocol synchronization + +- Fetch protocol trees with pagination and a TTL cache. +- Verify computed roots against server data. +- Implement rate limiting with exponential backoff and jitter. +- Set memory bounds for concatenated trees and honor Retry-After headers. + +## 8. Artifact management + +- Manifest schema & integrity verification. +- CDN downloads with caching and storage adapter. +- Verify manifest signature with pinned public key before caching. +- Enforce CDN allowlist and Content-Length checks. +- Stream hashing to avoid buffering large files. + +## 9. Scanning adapters & NFC lifecycle + +- Define cross-platform scanner interfaces. +- Implement React Native MRZ and NFC adapters with screen-on hooks. +- Provide a sample flow chaining MRZ to NFC scanning. + +## 10. Sample applications + +- React Native and web demos showcasing core flows. +- iOS `OpenPassport` URL scheme. + +## 11. Integrate SDK into `/app` + +- Consume `@selfxyz/mobile-sdk-alpha` inside the `app` workspace. +- Replace MRZ/NFC modules with SDK adapters and wire processing helpers. +- Validate builds and unit tests. + +## 12. In-SDK lightweight demo + +- Embedded React Native demo inside the SDK with theming hooks. +- Provide build and run instructions. + +## 13. Partner feedback + +- OAuth-style branding: logo, colors, copy, optional fonts. +- Callback hook so the host app can trigger push notifications after async proof verification. +- Expand ID document coverage for US digital licenses and AADHAR. +- Document bundle size targets and provide a runnable integration example. diff --git a/packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md b/packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md new file mode 100644 index 000000000..ce5e08580 --- /dev/null +++ b/packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md @@ -0,0 +1,290 @@ +# Migration Prompts + +Each chapter from the migration checklist includes granular tasks below. Pick tasks independently to parallelize work. + +> **Note**: This document uses standard Markdown `
` and `` tags for collapsible task sections, ensuring proper rendering on GitHub and other Markdown viewers. + +## 1. Processing helpers (MRZ & NFC) + +
+Test MRZ parsing utilities + +1. In `tests/processing/`, add test cases for `extractMRZInfo` and `formatDateToYYMMDD` covering valid/invalid inputs. +2. Use sample MRZ strings from ICAO specs for fixtures. + +
+ +
+Add NFC response parser + +1. Create `src/processing/nfc.ts` exporting a pure function to parse NFC chip responses into DG1/DG2 structures. +2. Write tests in `tests/processing/nfc.test.ts`. +3. Ensure no React Native dependencies. + +
+ +
+Expose processing utilities + +1. Update `src/index.ts` to re-export MRZ and NFC helpers. +2. Document them in `README.md` under a "Processing utilities" section. + +
+ +## 2. Validation module + +
+Port minimal document validation + +1. Create `src/validation/document.ts`. +2. Port `isPassportDataValid` logic without analytics or store calls. +3. Type the function using `PassportData` from `src/types/public.ts`. + +
+ +
+Test document validation + +1. Add `tests/validation/document.test.ts` with cases for missing metadata and hash mismatches. +2. Run via `yarn workspace @selfxyz/mobile-sdk-alpha test`. + +
+ +## 3. Proof input generation + +
+Port generateTEEInputsRegister + +1. Copy logic from `app/src/utils/proving/provingInputs.ts` lines 106-117 into `src/proving/registerInputs.ts`. +2. Replace `useProtocolStore` calls with parameters for `dscTree` and environment. +3. Ensure types align with `PassportData`. + +
+ +
+Port generateTEEInputsDisclose + +1. Move disclosure-related logic into `src/proving/discloseInputs.ts`. +2. Accept OFAC trees and other dependencies as function parameters instead of store lookups. +3. Write unit tests for both register and disclose generators with mocked trees. + +
+ +## 4. Crypto adapters + +
+Create CryptoAdapter + +1. In `src/crypto/`, add `adapter.ts` defining methods for hashing, random bytes, and asymmetric operations. +2. Document required methods (e.g., `digest`, `getRandomValues`, `subtle` operations). +3. Add a constant-time `timingSafeEqual(a, b)` utility and document RNG requirements (cryptographically secure only). +4. Implement environment detection for WebCrypto (detect globalThis.crypto and feature-check subtle/digest/getRandomValues). +5. Provide fallback to react-native-get-random-values or noble-based adapter when WebCrypto unavailable. +6. Ensure all secret comparisons use constant-time comparison instead of ===. + +
+ +
+Implement crypto adapters + +1. Add `webcrypto.ts` implementing the interface using `globalThis.crypto`. +2. Add `noble.ts` using `@noble/hashes` and `@noble/curves` where WebCrypto is unavailable. +3. Export a factory that chooses the appropriate adapter at runtime. +4. Provide tests ensuring both adapters yield identical results for sample inputs. +5. In noble adapter: select well-known safe curves (secp256r1/ed25519) and recommended hash algorithms. +6. Ensure sensitive buffers are zeroized after use where possible. +7. Add tests for constant-time comparator and RNG fallback behavior. + +
+ +## 5. TEE session management + +
+Implement TEE WebSocket wrapper + +1. Add `src/tee/session.ts` exporting `openSession(url, options)`. +2. Accept an `AbortSignal` and timeout; reject if aborted or timed out. +3. Emit progress events via an `EventEmitter` interface. + +
+ +
+Test and document TEE session + +1. Write tests using a mocked WebSocket server verifying abort/timeout handling. +2. Update `README.md` with example code showing progress listener usage. + +
+ +## 6. Attestation verification + +
+Port basic attestation verification + +1. In `src/attestation/verify.ts`, port `checkPCR0Mapping` and `getPublicKey` without logging. +2. Replace on-chain contract calls with parameters or pluggable providers. +3. Provide TypeScript types for attestation documents. +4. Validate attestation timestamps against device clock with configurable skew tolerance. +5. Define trust anchors and key pinning strategy for PCR0/public key mapping. +6. Add optional OCSP/CRL checks with network fallbacks and clear opt-out rationale. + +
+ +
+Implement certificate chain check + +1. Port simplified `verifyCertChain` from `attest.ts` ensuring no Node-specific APIs. +2. Add unit tests with mock certificates to cover success and failure paths. + +
+ +## 7. Protocol synchronization + +
+Add paginated tree fetch + +1. Under `src/client/`, create `treeFetcher.ts` with `fetchTreePaginated(url, pageSize)` returning concatenated pages. +2. Handle pagination tokens from the backend. +3. Include retries for transient network errors. + +
+ +
+Introduce tree cache with TTL + +1. In `treeFetcher.ts`, wrap results with an in-memory cache keyed by URL and `pageSize`. +2. Allow TTL configuration through SDK options. +3. Expose `clearExpired()` to purge stale entries. + +
+ +
+Implement root verification + +1. After assembling the full tree, compute its root and compare to the server-provided root. +2. Throw descriptive errors on mismatch. +3. Add tests with mock data ensuring verification triggers. + +
+ +## 8. Artifact management + +
+Add artifact manifest schema + +1. In `src/artifacts/`, create `manifest.ts` defining the JSON schema (name, version, urls, hashes). +2. Implement `verifyManifest(manifest, signature, publisherKey)` that validates schema and signature using a pinned publisher key. Only then validate per-file hashes. +3. Verify manifest signature against pinned public key before any caching or storage access. +4. Enforce CDN/domain allowlist and validate response Content-Length header against expected sizes. +5. Compute and verify streaming hash while downloading to avoid buffering full files in memory. + +
+ +
+Download and cache artifacts + +1. Create `downloader.ts` that fetches artifact files from a CDN, verifies integrity, and stores them via a pluggable storage adapter. +2. Support cache lookup before network fetch and provide `clearCache()` helper. +3. Add tests mocking fetch and storage layers. +4. Stream HTTP responses into hash verifier (do not buffer full files). +5. Verify Content-Length matches bytes read to detect truncation. +6. Validate download host against allowed-domains whitelist. +7. Only write to persistent storage after both signature and per-file hash verification succeed. + +
+ +## 9. Scanning adapters & NFC lifecycle + +
+Create scanning adapter interface + +1. In `src/adapters/`, add `scanner.ts` exporting TypeScript interfaces for `MRZScanner` and `NFCScanner`. +2. Reference React Native camera/NFC packages only through these interfaces. +3. Document usage in `README.md`. Include a "Privacy & PII" subsection: forbid logging MRZ/NFC data, enable on-device processing only, and provide redaction utilities for debug. +4. Never log MRZ strings, NFC APDUs, or chip contents anywhere (including telemetry). +5. Ensure camera frames and NFC/APDU processing occur on-device with analytics disabled for those paths by default. +6. Provide a redact/sanitize helper function for debug builds only. + +
+ +
+Implement React Native MRZ adapter + +1. Add `mrz-rn.ts` in `src/adapters/` implementing `MRZScanner` via `react-native-vision-camera`. +2. Expose configuration for permissions, preview, and result handling. +3. Write unit tests under `tests/` mocking camera output. + +
+ +
+Implement React Native NFC adapter + +1. Create `nfc-rn.ts` in `src/adapters/` implementing `NFCScanner` with `react-native-nfc-manager`. +2. Provide lifecycle hooks so the app can call `keepScreenOn(true|false)` during sessions. +3. Document app-level setup in `MIGRATION_CHECKLIST.md`. + +
+ +
+Add scanning sample + +1. Under `samples/`, add a React Native demo showing MRZ then NFC scanning. +2. Include simple error handling and log output. +3. Reference the sample from `README.md`. + +
+ +## 10. Sample applications + +
+Add React Native sample + +1. Under `samples/react-native/`, scaffold a bare-bones app using Expo or React Native CLI. +2. Demonstrate MRZ scanning, NFC reading, and registration flow using SDK APIs. +3. Include instructions in a `README.md`. + +
+ +
+Add web sample + +1. Under `samples/web/`, set up a Vite/React project showing browser-based MRZ input and proof generation. +2. Document setup and build steps. + +
+ +
+Configure OpenPassport scheme + +1. In the React Native sample's iOS project, add URL type `OpenPassport` to `Info.plist`. +2. Document Android intent filters (AndroidManifest.xml). Ensure scheme uniqueness and validate redirect origins to prevent hijacking. +3. Choose a scheme unique to your app (e.g., using reverse-domain or app-identifier prefix). +4. Detect and handle collisions (fallback checks, verify caller package/signature). +5. Verify redirect domains and consider app-claimed links/Android App Links and iOS Universal Links for stronger security. + +
+ +## 11. Integrate SDK into `/app` + +
+Integrate SDK in /app + +1. Add `@selfxyz/mobile-sdk-alpha` to `app/package.json`. +2. Replace existing MRZ/NFC scanning modules with SDK adapters. +3. Wire app screens to SDK processing and validation helpers. +4. Validate builds and unit tests in the `app` workspace. + +
+ +## 12. In-SDK lightweight demo + +
+Create embedded demo app + +1. Scaffold `demo/` under the SDK as a minimal React Native project. +2. Use SDK APIs for MRZ → NFC → registration flow. +3. Expose simple theming configuration. +4. Add `demo/README.md` with build/run instructions. +5. Add publishing guardrails: exclude `demo/` from npm and add a CI step to verify the published tarball contents. + +
diff --git a/packages/mobile-sdk-alpha/PARTNER_FEEDBACK.md b/packages/mobile-sdk-alpha/PARTNER_FEEDBACK.md new file mode 100644 index 000000000..32d7b6527 --- /dev/null +++ b/packages/mobile-sdk-alpha/PARTNER_FEEDBACK.md @@ -0,0 +1,27 @@ +# Partner Feedback + +## Technical integration + +- Expect OAuth-style branding inside the host app. Logo is required; colors, copy, and fonts are optional bonuses. +- Verification flow should run seamlessly on devices that already have the host app installed. +- Ensure branding configuration supports dark/light mode and accessibility requirements. + +## Verification workflow + +- Expand coverage to US driver's licenses, prioritizing states that support digital verification. +- Support both physical licenses and digital wallet credentials when available. +- Add AADHAR identity support. +- Implement proper error handling for unsupported document types with clear user messaging. + +## Implementation + +- Clarify acceptable SDK bundle size with partner (target: <500KB gzipped for core functionality). +- Provide a runnable example React Native app to speed up integration. +- Document minimum iOS/Android version requirements and device compatibility. + +## Infrastructure & notifications + +- Allow the host backend to receive a callback when proofs finish so it can trigger push notifications for users. +- Implement secure callback authentication to prevent unauthorized notifications. +- Add retry logic and timeout handling for callback delivery. +- Provide webhook signature verification for callback security. diff --git a/packages/mobile-sdk-alpha/PARTNER_PROMPTS.md b/packages/mobile-sdk-alpha/PARTNER_PROMPTS.md new file mode 100644 index 000000000..06e208751 --- /dev/null +++ b/packages/mobile-sdk-alpha/PARTNER_PROMPTS.md @@ -0,0 +1,78 @@ +# Partner Feedback Prompts + +Task stubs for requests raised by an external partner. + +> **Note**: This document uses standard Markdown `
` and `` tags for collapsible task sections, ensuring proper rendering on GitHub and other Markdown viewers. + +## Technical integration + +
+Expose branding configuration + +1. Add theming props to SDK screens for logo, colors, and optional fonts. +2. Document OAuth-style branding guidance in `README.md`. +3. Support dark/light mode variants and accessibility requirements. +4. Validate branding assets meet minimum size and format requirements. + +
+ +## Verification workflow + +
+Add US digital license support + +1. Research state APIs or standards for digital driver's license verification. +2. Implement adapters that handle both physical and wallet-based licenses. +3. Provide fixtures and tests for at least one state implementation. +4. Add proper error handling for unsupported states with clear user messaging. +5. Implement secure credential verification with proper signature validation. + +
+ +
+Add AADHAR document support + +1. Investigate required fields and validation rules for AADHAR identities. +2. Implement parsing and validation helpers. +3. Cover logic with unit tests and sample data. +4. Ensure compliance with Indian data protection regulations. +5. Add proper error handling for invalid or expired AADHAR documents. + +
+ +## Implementation + +
+Clarify bundle size budget + +1. Measure current SDK bundle size using `yarn build` outputs. +2. Confirm acceptable bundle size with partner and document target in `PARTNER_FEEDBACK.md`. +3. Implement tree-shaking and code splitting to minimize bundle size. +4. Document minimum iOS/Android version requirements. + +
+ +
+Publish runnable example app + +1. Ensure sample React Native app can be cloned and run without extra setup. +2. Include integration steps mirroring partner's phase 1 flow. +3. Link the example in `PARTNER_FEEDBACK.md` for easy discovery. +4. Add comprehensive error handling and logging examples. +5. Include device compatibility testing instructions. + +
+ +## Infrastructure & notifications + +
+Provide proof callback hook + +1. Expose an API for sending proof completion callbacks to a partner server. +2. Add docs showing how a partner can trigger push notifications when callbacks fire. +3. Include timeout and retry guidance. +4. Implement secure callback authentication with HMAC signatures. +5. Add webhook signature verification for callback security. +6. Provide rate limiting and circuit breaker patterns for callback delivery. + +