Skip to content

Expand migration checklist and prompts #880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 12, 2025
Merged

Expand migration checklist and prompts #880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
206d829
Expand migration checklist and prompts
transphorm Aug 11, 2025
ac10508
recommendos
transphorm Aug 11, 2025
ec00f9a
update order
transphorm Aug 11, 2025
7dfac90
add partner feedback
transphorm Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 76 additions & 10 deletions packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Comment on lines +57 to +61
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

iOS URL scheme uniqueness and collision avoidance.

Verify OpenPassport scheme is unique and documented for integrators to avoid conflicts.

🏁 Script executed:

#!/bin/bash
# Search for existing URL scheme docs/usages to avoid duplication across packages
rg -n 'OpenPassport|CFBundleURLSchemes|URL scheme' -A 2 -B 2

Length of output: 37523

Clarify and document the iOS URL scheme in the migration checklist

The checklist currently calls out an “iOS OpenPassport URL scheme,” but your Info.plist (and existing tests) actually register the scheme as proofofpassport. Let’s keep everything in sync and remind integrators to pick a collision-safe name:

• packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md (around line 60):

- - iOS `OpenPassport` URL scheme.
+ - iOS `proofofpassport` URL scheme – ensure you choose a unique name (e.g. reverse-domain prefix).  
+   See packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md Step 1 for details on configuring and avoiding collisions.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 10. Sample applications
- React Native and web demos showcasing core flows.
- iOS `OpenPassport` URL scheme.
## 10. Sample applications
- React Native and web demos showcasing core flows.
- iOS `proofofpassport` URL scheme – ensure you choose a unique name (e.g. reverse-domain prefix).
See packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md Step 1 for details on configuring and avoiding collisions.
🤖 Prompt for AI Agents 
In packages/mobile-sdk-alpha/MIGRATION_CHECKLIST.md around lines 57 to 61, the
checklist refers to an iOS "OpenPassport" URL scheme but the project registers
the scheme as "proofofpassport"; update the checklist text to reference
"proofofpassport" (or explicitly instruct integrators to choose a collision-safe
custom scheme and keep it consistent), and add a short note to remind
maintainers to synchronize the chosen scheme across Info.plist, tests, and
sample apps to avoid mismatches.

## 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.
290 changes: 290 additions & 0 deletions packages/mobile-sdk-alpha/MIGRATION_PROMPTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<details>` and `<summary>` tags for collapsible task sections, ensuring proper rendering on GitHub and other Markdown viewers.

## 1. Processing helpers (MRZ & NFC)

<details>
<summary><strong>Test MRZ parsing utilities</strong></summary>

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.

</details>

<details>
<summary><strong>Add NFC response parser</strong></summary>

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.

</details>

<details>
<summary><strong>Expose processing utilities</strong></summary>

1. Update `src/index.ts` to re-export MRZ and NFC helpers.
2. Document them in `README.md` under a "Processing utilities" section.

</details>

## 2. Validation module

<details>
<summary><strong>Port minimal document validation</strong></summary>

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

</details>

<details>
<summary><strong>Test document validation</strong></summary>

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

</details>

## 3. Proof input generation

<details>
<summary><strong>Port generateTEEInputsRegister</strong></summary>

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

</details>

<details>
<summary><strong>Port generateTEEInputsDisclose</strong></summary>

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.

</details>

## 4. Crypto adapters

<details>
<summary><strong>Create CryptoAdapter</strong></summary>

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

</details>

<details>
<summary><strong>Implement crypto adapters</strong></summary>

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.

</details>

## 5. TEE session management

<details>
<summary><strong>Implement TEE WebSocket wrapper</strong></summary>

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.

</details>

<details>
<summary><strong>Test and document TEE session</strong></summary>

1. Write tests using a mocked WebSocket server verifying abort/timeout handling.
2. Update `README.md` with example code showing progress listener usage.

</details>

## 6. Attestation verification

<details>
<summary><strong>Port basic attestation verification</strong></summary>

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.

</details>

<details>
<summary><strong>Implement certificate chain check</strong></summary>

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.

</details>

## 7. Protocol synchronization

<details>
<summary><strong>Add paginated tree fetch</strong></summary>

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.

</details>

<details>
<summary><strong>Introduce tree cache with TTL</strong></summary>

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.

</details>

<details>
<summary><strong>Implement root verification</strong></summary>

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.

</details>

## 8. Artifact management

<details>
<summary><strong>Add artifact manifest schema</strong></summary>

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.

</details>

<details>
<summary><strong>Download and cache artifacts</strong></summary>

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.

</details>

## 9. Scanning adapters & NFC lifecycle

<details>
<summary><strong>Create scanning adapter interface</strong></summary>

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.

</details>

<details>
<summary><strong>Implement React Native MRZ adapter</strong></summary>

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.

</details>

<details>
<summary><strong>Implement React Native NFC adapter</strong></summary>

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

</details>

<details>
<summary><strong>Add scanning sample</strong></summary>

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

</details>

## 10. Sample applications

<details>
<summary><strong>Add React Native sample</strong></summary>

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

</details>

<details>
<summary><strong>Add web sample</strong></summary>

1. Under `samples/web/`, set up a Vite/React project showing browser-based MRZ input and proof generation.
2. Document setup and build steps.

</details>

<details>
<summary><strong>Configure OpenPassport scheme</strong></summary>

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.

</details>

## 11. Integrate SDK into `/app`

<details>
<summary><strong>Integrate SDK in /app</strong></summary>

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.

</details>

## 12. In-SDK lightweight demo

<details>
<summary><strong>Create embedded demo app</strong></summary>

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.

</details>
Loading
Loading