devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/templates/config-questionnaire.md

@@ -0,0 +1,467 @@
+# Config Questionnaire
+
+Collect all answers before writing any files.
+Apply documented defaults automatically for unanswered non-critical fields.
+Block implementation only when a security-critical value has no safe default (e.g. RSA public key in env mode).
+
+> **Questioning rule**: Ask questions **one at a time**. Present a single question, wait for the answer, then proceed to the next. Never bundle multiple questions into a single prompt.
+
+---
+
+## Pre-Question: React Native Version Check (React Native projects only)
+
+Before asking encryption questions, verify the RN version and existing dependencies:
+
+```bash
+node -p "require('./package.json').dependencies['react-native']"
+npm ls react-native-quick-crypto react-native-nitro-modules react-native-worklets buffer 2>&1
+```
+
+If RN >= 0.76 and quick-crypto >= 1.0: `react-native-nitro-modules` and `react-native-worklets` MUST be installed as peer deps.
+If RN < 0.76 or quick-crypto < 1.0: Nitro Modules is NOT needed.
+
+---
+
+## Question 0 — Platform (Ask First)
+
+Which platform is this project?
+- Default: react-native
+- Options: angular, web, node, android, ios, flutter, react, react-native
+
+Validate against `assets/platform-matrix.json` before proceeding.
+
+---
+
+## Question 0a — React JS Production Mode Detection (React platform only)
+
+Is this a React JS (web browser) project that needs production-grade encryption?
+- If yes and user wants full request/response lifecycle with Web Crypto API → **recommend approach 7**
+- If yes and user wants a quick/simple setup → approaches 1, 2, or 3 remain valid
+- Default: if platform is `react` and no preference stated, ask this question before Question 1
+
+> Approach 7 uses the built-in Web Crypto API (no extra crypto packages). It handles both request encryption and response decryption, supports RSA-OAEP and ECDH-Session modes, and enforces browser-safe storage — suitable for production deployments.
+
+---
+
+## Question 0b — Encryption Model (React Native only — ask before approach)
+
+Which encryption model should be used?
+- Default: **RSA**
+- **RSA** — AES session key wrapped with server's RSA public key (RSA-OAEP). Proven, PEM format. → approaches 4/5
+- **EC (ECDH)** — AES session key derived via ECDH P-256 + HKDF-SHA256. Ephemeral key pair per request; only the 65-byte uncompressed public key is transmitted — the derived AES key is never sent. → approach 6
+
+> If user does not answer, default to **RSA** and proceed.
+
+---
+
+## Question 1 — Approach
+
+Which encryption approach should be used?
+
+| # | Mode | Description |
+|---|------|-------------|
+| 1 | RSA-OAEP + AES-256-GCM | Web Crypto API (angular, web, ios) |
+| 2 | RSA + AES-256-CBC | jsencrypt + crypto-js |
+| 3 | AES-256-CBC shared key | crypto-js only |
+| 4 | **Production JS (React Native)** | AES-256-GCM + RSA-OAEP via react-native-quick-crypto, per-request ephemeral keys, response decryption, keychain |
+| 5 | **Production Native (React Native)** | OS-level crypto: javax.crypto.Cipher (Android) + CryptoKit (iOS) |
+| 6 | **EC / ECDH (React Native)** | ECDH P-256 + HKDF-SHA256 + AES-256-GCM; per-request or session-init; EC+Native reuses NativeCryptoModule |
+| 7 | **React JS Web Production** | AES-256-GCM + RSA-OAEP or ECDH-Session via built-in Web Crypto API; per-request ephemeral keys; response decryption; browser-safe storage; zero extra crypto packages |
+
+Default (React Native): approach 4
+Default (React / other platforms): lowest valid approach for the platform
+
+Validate against `platform.approaches[]` in `platform-matrix.json`.
+
+---
+
+## Question 2 — Encryption Layer (React Native approaches 4, 5, and 6)
+
+Which encryption layer should be used?
+- Default: React Native (JS) → approach 4 (RSA) or 6 (EC)
+- **React Native (JS)** — crypto runs in JavaScript using `react-native-quick-crypto`. Simpler setup.
+- **Native** — AES runs in the OS-level engine. For RSA: `javax.crypto.Cipher` (Android) + CryptoKit (iOS) → approach 5. For EC: ECDH+HKDF run in JS; only AES runs natively (reuses existing `NativeCryptoModule`).
+
+If user omits this answer, apply default (React Native JS) and continue.
+
+---
+
+## Question 3 — RSA Padding (Approaches 1, 2, 4, 5)
+
+Which RSA padding should be used?
+- Default: RSA-OAEP
+- **RSA-OAEP** (mandatory — use this unless there is a documented legacy constraint)
+- RSA PKCS1 v1.5 (legacy only — requires explicit written approval; not acceptable for new deployments in 2026)
+
+---
+
+## Question 4 — RSA Public Key Source (Approaches 1, 2, 4, 5)
+
+Where should the RSA public key come from?
+- Default: API
+- **API** (recommended — fetched at runtime, cached in memory, refreshable)
+- Environment variable (embedded as PEM/Base64 in `.env`)
+
+---
+
+## Question 5 — If API Source Selected
+
+a. Public key endpoint URL
+   - Default: `<API_BASE_URL>/api/security/public-key`
+
+b. Response format
+   - Default: `{ public_key: string, key_id: string, expires_at?: string }`
+
+c. Cache key in memory?
+   - Default: Yes
+
+d. Retry count on fetch failure
+   - Default: 3
+
+---
+
+## Question 6 — If Environment Source Selected
+
+a. RSA public key value (PEM starting with `-----BEGIN PUBLIC KEY-----`)
+   - Default: none — must be provided
+   - Validate PEM headers before accepting
+
+---
+
+## Question 7 — Shared Key (Approach 3 only)
+
+Enter the shared secret key.
+- Minimum: 32 characters
+- Default: none — must be provided
+- Validate length before accepting
+
+---
+
+## Question 8 — API Client Type (Approaches 4 and 5)
+
+Which API client is used?
+- Default: Axios
+- Axios
+- Fetch
+- Custom service layer
+
+---
+
+## Question 9 — API Layer Path (Approaches 4 and 5)
+
+Where is the API layer file located?
+- Default: `src/services/api.ts`
+- Validate the path exists in the project before accepting
+
+---
+
+## Question 10 — Secure Storage (Approaches 4 and 5)
+
+Confirm secure storage with react-native-keychain for:
+- Tokens: Default Yes
+- Sensitive persisted data: Default Yes
+
+---
+
+## Question 11 — Encryption Toggle Policy
+
+Should encryption be:
+- Default: Controlled by env flag (`ENCRYPTION_ENABLED`)
+- **Controlled by env flag** (recommended — allows disabling in dev)
+- Always enabled
+
+---
+
+## Question 12 — Platform Scope (React Native)
+
+Which platforms should encryption be applied to?
+- Default: Both Android and iOS
+- Both Android and iOS
+- Android only
+- iOS only
+
+---
+
+## Question 13 — Minimum iOS Version (Approach 5 only)
+
+What is the minimum iOS deployment target?
+- Default: 13 (required for CryptoKit)
+- If below 13: plan CommonCrypto fallback (`CCCryptorGCM` for AES-GCM + `SecKeyCreateEncryptedData` for RSA-OAEP)
+
+---
+
+## Question 14 — Android Package (Approach 5 only)
+
+Android Kotlin package name for NativeCryptoModule.
+- Default: `com.example.security`
+
+Also verify `minSdkVersion >= 23` in `android/app/build.gradle` before proceeding.
+
+---
+
+## Question 15 — HMAC Request Signing
+
+Enable HMAC-SHA256 request signing?
+- Default: No
+- If Yes: set `ENCRYPTION_HMAC_SECRET` as an env var at runtime — never hardcode or commit
+
+---
+
+## Question 16 — URL Exclusions
+
+Are there any URL prefixes that should bypass encryption?
+- Default: none
+- Example: `/api/auth/login, /api/health, /api/public`
+
+---
+
+## Questions for Approach 7 (React JS Web Production Mode)
+
+Ask these questions only when `platform = react` and `approach = 7`. Ask one at a time.
+
+### Q7-1 — Web Encryption Mode
+
+Which encryption mode should be used?
+- Default: **RSA-OAEP**
+- **RSA-OAEP** — per-request ephemeral AES-256-GCM key wrapped with server RSA public key; simpler setup
+- **ECDH-Session** — ECDH P-256 + HKDF-SHA256 + AES-256-GCM; session key derived once at init; cleaner for long-lived sessions
+
+### Q7-2 — Framework / Bundler
+
+Which framework or bundler is used?
+- Default: none — must be detected or confirmed
+- **Vite** → env prefix `VITE_`
+- **Create React App (CRA)** → env prefix `REACT_APP_`
+- **Next.js** → env prefix `NEXT_PUBLIC_`
+
+> This determines the correct env variable prefix for all feature flags.
+
+### Q7-3 — Token Storage
+
+How should auth tokens be stored?
+- Default: **sessionStorage**
+- **sessionStorage** — clears on tab close; suitable for most SPAs
+- **HTTP-only cookie** — server sets cookie; browser never exposes it to JS; recommended for high-security apps
+- **localStorage** — FORBIDDEN for tokens or session material; never use for approach 7
+
+### Q7-4 — RSA Public Key Source (RSA-OAEP mode only)
+
+Where should the RSA public key come from?
+- Default: API
+- **API** — fetched at runtime, cached in memory, refreshable
+- **Environment variable** — embedded as PEM/Base64 in `.env.*`
+
+### Q7-5 — RSA Public Key Endpoint (RSA-OAEP API source only)
+
+What is the public key endpoint URL?
+- Default: `<API_BASE_URL>/api/security/public-key`
+- Response format default: `{ public_key: string, key_id: string, expires_at?: string }`
+
+### Q7-6 — ECDH-Session Blocking Questions (ECDH-Session mode only)
+
+ALL fields are backend-specific and have no safe defaults. Ask each one individually and do not proceed until all are provided:
+
+- Q7-6a: Session init endpoint URL
+- Q7-6b: HKDF `info` string (do NOT assume `'enc'`)
+- Q7-6c: AAD required? If yes, provide the canonical JSON shape (alphabetically sorted key order)
+- Q7-6d: Response encoding (standard base64 or base64url)
+- Q7-6e: Device ID source (how `device_id` is generated or retrieved)
+- Q7-6f: Session restore strategy (reload from `sessionStorage` JWK or re-initiate session)
+
+---
+
+## Confirmed Configuration Snapshot
+
+Record before implementation:
+
+| Field | Value |
+|-------|-------|
+| Platform | |
+| Approach | |
+| Encryption layer (RN only) | |
+| RSA padding | RSA-OAEP |
+| RSA key source | API |
+| RSA key endpoint | `<API_BASE_URL>/api/security/public-key` |
+| RSA key retries | 3 |
+| API client | Axios |
+| API layer path | src/services/api.ts |
+| Encryption toggle | env-flag |
+| HMAC signing | No |
+| URL exclusions | (none) |
+| Min iOS version (approach 5) | 13 |
+| Android package (approach 5) | com.example.security |
+| Encryption model (approach 6) | ec |
+| EC contract type (approach 6) | per-request |
+| EC key endpoint (approach 6) | `<API_BASE_URL>/api/security/ec-public-key` |
+| EC HKDF info string (session-init only) | **no default — must be confirmed** |
+| EC nonce format/length (session-init only) | **no default — must be confirmed** |
+| EC AAD required + shape (session-init only) | **no default — must be confirmed** |
+| EC response IV source (session-init only) | **no default — must be confirmed** |
+| Web encryption mode (approach 7) | RSA-OAEP |
+| Framework/bundler (approach 7) | **must be detected or confirmed** |
+| Token storage (approach 7) | sessionStorage |
+| RSA key endpoint (approach 7) | `<API_BASE_URL>/api/security/public-key` |
+| ECDH session init URL (approach 7, ECDH-Session) | **no default — must be confirmed** |
+| ECDH HKDF info string (approach 7, ECDH-Session) | **no default — must be confirmed** |
+| ECDH AAD shape (approach 7, ECDH-Session) | **no default — must be confirmed** |
+
+---
+
+## Required Answers — EC + React Native JS mode (Approach 6 / encryptionModel = ec)
+
+1. EC curve selection
+   - Default: P-256 (secp256r1)
+   - Options: P-256 / P-384 / P-521
+
+1a. EC contract type
+   - Default: per-request
+   - **Per-request EC** — fresh ephemeral key pair per API call; HKDF salt = per-request nonce
+   - **Session-init EC** — shared session AES key derived once at login; reused across requests
+
+1b. If session-init EC selected (ALL fields are blocking — ask each one individually, no defaults):
+
+   - Q-SI-1: Session init endpoint URL
+   - Q-SI-2: Token/session endpoint URL
+   - Q-SI-3: Required API call order (default: initEncryptionSession → createSession → encrypted business APIs)
+   - Q-SI-4: Is `encrypted_shared_aes_key` from the init response used or ignored by the reference client?
+   - Q-SI-5: Exact HKDF `info` string (backend-specific — do NOT assume `'enc'`)
+   - Q-SI-6: Exact AAD JSON shape (if AAD is required by AES-GCM)
+   - Q-SI-7: Response IV source (nonce-as-IV, separate `iv` field, or other)
+   - Q-SI-8: Response payload encoding (standard base64 or base64url)
+   - Q-SI-9: Response payload structure (ciphertext \|\| tag, or IV \|\| ciphertext \|\| tag)
+   - Q-SI-10: Nonce format
+   - Q-SI-11: Nonce length
+   - Q-SI-12: Nonce character set restrictions
+   - Q-SI-13: Is there a reference client (Flutter, web, etc.) to verify against?
+   - Q-SI-14: Which `Buffer` package is installed: (verify `npm ls buffer`)
+   - Q-SI-15: `DEVICE_ID_SOURCE` — how is the stable `device_id` generated or retrieved
+
+2. EC public key source
+   - Default: API
+   - API or Environment variable
+
+3. If API source selected:
+   - Endpoint URL: default `<API_BASE_URL>/api/security/ec-public-key`
+   - Response format: default `{ public_key: string, key_id: string, expires_at?: string }` where `public_key` is base64(65-byte uncompressed P-256 point)
+   - Cache in memory: default Yes
+   - Retry count: default 3
+
+4. If Environment source selected:
+   - EC public key value (base64, 65 bytes, first decoded byte must be `0x04`):
+   - Format validated: default Yes
+
+5. API client type: default Axios
+6. API layer path: default `src/services/api.ts`
+7. Secure storage (react-native-keychain): default Yes
+8. Encryption toggle: default env-controlled (`ENCRYPTION_MODEL=ec`)
+9. Platform scope: default Android + iOS
+10. HMAC signing: default No
+
+## Validation Status — EC + JS mode
+
+- [ ] Encryption model: EC
+- [ ] EC contract type confirmed: per-request / session-init
+- [ ] EC public key format valid (65 bytes, first byte 0x04)
+- [ ] EC public key endpoint is HTTPS (if API source)
+- [ ] Session-init: HKDF `info` string confirmed
+- [ ] Session-init: AAD shape confirmed or confirmed not required
+- [ ] Session-init: nonce length/format confirmed
+- [ ] Session-init: response IV source confirmed
+- [ ] API layer path exists in project
+- [ ] All required answers received
+- [ ] Approved to proceed: Yes
+
+---
+
+## Required Answers — EC + Native mode (Approach 6 + encryptionLayer = native)
+
+1. EC curve selection
+   - Default: P-256 (secp256r1)
+
+1a. EC contract type
+   - **REQUIRED — ask developer, no default**
+   - Per-request EC or session-init EC
+
+1b. If session-init EC selected (ALL fields are blocking — ask each one individually, no defaults):
+
+   - Q-SI-1: Session init endpoint URL (`SESSION_INIT_ENDPOINT`): must be provided
+   - Q-SI-2: Token/session endpoint URL (`CREATE_SESSION_ENDPOINT`): must be provided
+   - Q-SI-3: Required API call order (default: initEncryptionSession → createSession → encrypted business APIs)
+   - Q-SI-4: Exact HKDF `info` string (`HKDF_INFO`): must be provided — do NOT assume `'enc'`
+   - Q-SI-5: Exact AAD JSON shape (`AAD_SHAPE`): must be provided if AAD is required
+   - Q-SI-6: Response IV source (nonce-as-IV, separate `iv` field, or other): must be provided
+   - Q-SI-7: Response payload encoding (`RESPONSE_ENCODING` — standard base64 or base64url): must be confirmed
+   - Q-SI-8: Response payload structure (ciphertext \|\| tag, or IV \|\| ciphertext \|\| tag): must be provided
+   - Q-SI-9: Nonce format (`NONCE_FORMAT`): must be provided explicitly
+   - Q-SI-10: Nonce length: must be provided explicitly
+   - Q-SI-11: Nonce character set restrictions: must be provided explicitly
+   - Q-SI-12: `DEVICE_ID_SOURCE` — how is the stable `device_id` generated or retrieved: must be provided
+   - Q-SI-13: `encrypted_shared_aes_key` handling (used / ignored): must be confirmed
+   - Q-SI-14: Which `Buffer` package is installed: (verify `npm ls buffer`)
+   - Q-SI-15: Is there a reference client (Flutter, web, etc.) to verify against: ask backend team
+
+2. EC public key source: default API
+3. If API source selected: endpoint URL, response format `{ public_key, key_id, expires_at? }`, cache (yes), retries (3)
+4. If Environment source selected: base64 65-byte uncompressed P-256 point, first byte must be `0x04`
+5. Minimum iOS version: default 13 (CryptoKit)
+6. API client type: default Axios
+7. API layer path: default `src/services/api.ts`
+8. Secure storage: default Yes (react-native-keychain)
+9. Encryption toggle: default env-controlled (`ENCRYPTION_MODEL=ec`, `ENCRYPTION_LAYER=native`)
+10. Platform scope: default Android + iOS
+11. HMAC signing: default No
+
+> Note: EC + Native does NOT require new Kotlin/Swift files. ECDH + HKDF run in JS; only AES runs in the existing NativeCryptoModule.
+
+## Validation Status — EC + Native mode
+
+- [ ] Android minSdkVersion >= 23
+- [ ] iOS deployment target >= 13.0 confirmed
+- [ ] Existing NativeCryptoModule confirmed accessible from JS
+- [ ] EC public key format valid (65 bytes, first byte 0x04)
+- [ ] EC public key source URL is HTTPS (if API)
+- [ ] EC contract type confirmed (per-request / session-init)
+- [ ] Session-init endpoints confirmed (if session-init): SESSION_INIT_ENDPOINT / CREATE_SESSION_ENDPOINT
+- [ ] HKDF `info` string confirmed (if session-init)
+- [ ] AAD contract confirmed (if session-init)
+- [ ] Nonce length/format confirmed (if session-init)
+- [ ] Response encoding confirmed (if session-init)
+- [ ] DEVICE_ID_SOURCE confirmed (if session-init)
+- [ ] All required answers received
+- [ ] Approved to proceed: Yes
+
+---
+
+## Validation Status (All other platforms / approaches 1–5)
+
+- [ ] Platform confirmed and exists in `platform-matrix.json`
+- [ ] Approach valid for this platform
+- [ ] All RSA key source inputs validated (HTTPS URLs, PEM headers if env mode)
+- [ ] Shared key >= 32 characters (approach 3)
+- [ ] API layer path exists in project
+- [ ] Android `minSdkVersion >= 23` confirmed (approach 5)
+- [ ] iOS deployment target confirmed / fallback planned (approach 5)
+- [ ] `privateKeyPem` refused for angular/web platforms
+- [ ] Approved to proceed with implementation: Yes
+
+---
+
+## Validation Status — React JS Web Production Mode (Approach 7)
+
+- [ ] Platform confirmed: `react`
+- [ ] Approach 7 valid for react platform (check `platform-matrix.json`)
+- [ ] App is served over HTTPS or localhost (`crypto.subtle` unavailable on plain HTTP)
+- [ ] Framework/bundler detected: Vite / CRA / Next.js (env prefix confirmed)
+- [ ] `tsconfig.json` includes `"DOM"` in `lib`
+- [ ] Web encryption mode confirmed: RSA-OAEP / ECDH-Session
+- [ ] RSA-OAEP: public key endpoint is HTTPS (if API source)
+- [ ] RSA-OAEP: PEM headers valid (if env source)
+- [ ] No `crypto-js`, `node-forge`, or Buffer polyfill in dependencies
+- [ ] Token storage confirmed: sessionStorage / HTTP-only cookie (localStorage rejected)
+- [ ] ECDH-Session: session init URL confirmed (if ECDH-Session mode)
+- [ ] ECDH-Session: HKDF `info` string confirmed (if ECDH-Session mode)
+- [ ] ECDH-Session: AAD shape confirmed or confirmed not required (if ECDH-Session mode)
+- [ ] ECDH-Session: device ID source confirmed (if ECDH-Session mode)
+- [ ] HMAC secret in env var only — never hardcoded
+- [ ] All required answers received
+- [ ] Approved to proceed: Yes

package/.github/skills/encryption-decryption-utility/templates/delivery-checklist.md

@@ -0,0 +1,206 @@
+# Delivery Checklist
+
+Mark each item complete before marking the implementation finished.
+
+---
+
+## Setup
+
+- [ ] `detect.js` ran and result noted (FOUND / NOT_FOUND).
+- [ ] Detection mode selected: replace / reuse / refactor.
+- [ ] Platform confirmed and validated against `platform-matrix.json`.
+- [ ] Approach confirmed and validated against allowed approaches for the platform.
+- [ ] All required inputs collected and validated (PEM format, key length, HTTPS URLs).
+- [ ] Encryption model confirmed (RSA / EC).
+- [ ] Encryption layer confirmed (React Native JS / Native).
+
+---
+
+## Dependencies (React Native JS Mode — all approaches)
+
+- [ ] react-native-quick-crypto installed and verified.
+- [ ] react-native-nitro-modules installed explicitly (required peer dep of quick-crypto >= 1.0 / RN >= 0.76).
+- [ ] react-native-worklets installed explicitly (required peer dep of quick-crypto >= 1.0 / RN >= 0.76).
+- [ ] react-native-quick-base64 present (auto-installed by quick-crypto — verify with `npm ls react-native-quick-base64`).
+- [ ] buffer package installed (>= 6.0.0) — required for EC mode and session-init helpers.
+- [ ] `npm ls react-native-nitro-modules` does NOT show `UNMET PEER DEP`.
+- [ ] Android `.cxx` cache cleared after native module changes.
+- [ ] Android clean build completed successfully.
+- [ ] iOS pod install completed successfully.
+
+---
+
+## Implementation — All Platforms
+
+- [ ] Config file written (`encryption.config.ts` / `EncryptionConfig.kt` / `EncryptionConfig.swift` / `EncryptionConfig.dart`).
+- [ ] Service file written (`EncryptionService` with `encrypt` method, and `decrypt` where applicable).
+- [ ] Interceptor / middleware written and wired into the HTTP layer.
+- [ ] Module wiring patched (AppModule / axiosInstance / OkHttpClient / Podfile / Dio).
+- [ ] `ENCRYPTION_INTERCEPTOR_PLACEHOLDER` marker present (for future patching).
+
+## Implementation — React Native Approaches 4 and 5
+
+- [ ] `src/services/security/types.ts` written (`EncryptedEnvelope`, `EncryptedResponse`).
+- [ ] `src/services/security/encryption.service.ts` written (AES-256-GCM per-request encrypt).
+- [ ] `src/services/security/decryption.service.ts` written (AES-256-GCM decrypt + auth tag split).
+- [ ] `src/services/security/rsa-key.service.ts` written (fetch / cache / retry).
+- [ ] `src/services/security/keychain.service.ts` written (`react-native-keychain` wrapper).
+- [ ] `src/services/security/hmac.service.ts` written (even if HMAC disabled — ready for activation).
+- [ ] `src/services/security/encryption-config.ts` written (feature flags + env references).
+- [ ] Request interceptor written (encrypt POST/PUT/PATCH, store in request map, set `X-Request-Id`).
+- [ ] Response interceptor written (decrypt using request map key, clean up map on success and failure).
+- [ ] `index.js` patched with `react-native-get-random-values` polyfill as first import.
+- [ ] `axiosInstance.ts` wired with `applyProductionEncryptionInterceptor`.
+
+## Implementation — Native Mode (Approach 5) Additional
+
+- [ ] `NativeCryptoModule.kt` created (`encryptAES`, `decryptAES`, `encryptRSA`).
+- [ ] `NativeCryptoPackage.kt` created and `NativeCryptoPackage` registered in `MainApplication`.
+- [ ] `NativeCryptoModule.swift` created using `do/try/catch` — no `try!` allowed.
+- [ ] `NativeCryptoModule.m` Objective-C bridge file created.
+- [ ] `src/services/security/native-crypto.module.ts` JS bridge interface created.
+- [ ] Interceptors updated to call `nativeEncryptAES` / `nativeDecryptAES` / `nativeEncryptRSA`.
+- [ ] `ENCRYPTION_LAYER=native` added to `.env`.
+- [ ] Pod install completed (iOS).
+- [ ] Gradle sync completed (Android).
+- [ ] `NativeModules.NativeCryptoModule` confirmed accessible from JS.
+
+## Implementation — EC + React Native JS Mode (Approach 6, per-request)
+
+- [ ] `EcPublicKeyResponse`, `EcEncryptedEnvelope`, and `RequestCryptoMaterial` types added to `types.ts`.
+- [ ] `ec-key.service.ts` created (EC public key fetch / validate / cache / retry with 65-byte point check).
+- [ ] `ec-crypto.util.ts` created (`ecEncryptPayload`, `ecDeriveKey`, HKDF-SHA256).
+- [ ] `toBase64()`, `toBuffer()`, `byteCopy()` helpers included — NOT using `Buffer.toString('base64')` on Hermes.
+- [ ] Dual Buffer imports: `Buffer from 'buffer'` + `Buffer as QCBuffer from 'react-native-quick-crypto'`.
+- [ ] `ENCRYPTION_MODEL` routing added to `api.ts` (rsa vs ec branches).
+- [ ] `KEY_ID_NOT_FOUND` (401) handler routes to `EcKeyService.refreshPublicKey` when EC model.
+- [ ] Ephemeral EC key pair discarded immediately after `computeSecret()`.
+- [ ] Derived AES key is NEVER transmitted — only `ephemeral_public_key` sent in envelope.
+- [ ] Feature flags wired: `ENCRYPTION_MODEL=ec`, `EC_PUBLIC_KEY_ENDPOINT`, `EC_KEY_RETRY`.
+- [ ] `[If HMAC_ENABLED=true]` `hmac.service.ts` injected into request interceptor after envelope is built.
+
+## Implementation — EC + React Native JS Mode (Approach 6, session-init)
+
+- [ ] All items from per-request EC section above.
+- [ ] Stateful auth service class created, holding `sessionAesKey`, `encryptionKeyId`, `sessionDeviceId`.
+- [ ] `deriveSessionKey()` uses backend-confirmed HKDF info string (NOT hardcoded `'enc'`).
+- [ ] `buildSessionAad()` uses canonical JSON with alphabetically sorted keys.
+- [ ] `sessionEncrypt()` uses nonce-as-IV and AAD (confirmed from backend contract).
+- [ ] `sessionDecrypt()` uses correct IV source (confirmed from backend contract or reference client).
+- [ ] `urlSafeBase64ToStd()` applied to all base64url fields received from server.
+- [ ] `initEncryptionSession` sends real freshly-generated `client_ecdh_pub` from the same ECDH instance used for derivation.
+- [ ] `createSession` runs only after `initEncryptionSession` succeeds and uses the returned `key_id`.
+- [ ] Nonce generator uses CSPRNG (`randomBytes`) — NOT `Math.random()` — nonce IS the AES-GCM IV.
+- [ ] Nonce format/length matches backend contract exactly.
+- [ ] `encrypted_shared_aes_key` handling confirmed (used vs ignored).
+- [ ] `device_id` is stable and consistent across init, HKDF context, AAD, and encrypted requests.
+- [ ] Token persistence is separate from session key lifetime (app restart requires re-init if key not stored).
+- [ ] Dead debug code removed (unwrapSessionKey, tryAesGcmDecrypt, hkdfExpandOnly, hkdfSwapped) if present.
+
+## Implementation — EC + Native Mode (Approach 6 + encryptionLayer = native)
+
+- [ ] All EC + JS items above.
+- [ ] `ecDeriveKey()` helper returns `{ derivedAesKeyBase64, ephemeralPublicKeyBase64 }` without AES.
+- [ ] Interceptor calls `ecDeriveKey` in JS, then passes `derivedAesKeyBase64` to existing `nativeEncryptAES`.
+- [ ] Response decryption calls `nativeDecryptAES` with same `derivedAesKeyBase64` from request map.
+- [ ] No new Kotlin/Swift files added — existing `NativeCryptoModule` is reused.
+- [ ] `ENCRYPTION_MODEL=ec` and `ENCRYPTION_LAYER=native` env flags wired.
+
+## Implementation — React JS Web Production Mode, RSA-OAEP (Approach 7)
+
+- [ ] App confirmed served over HTTPS or localhost (crypto.subtle unavailable on plain HTTP).
+- [ ] `tsconfig.json` `"lib"` includes `"DOM"` — patched if missing.
+- [ ] `axios` present in package.json — installed if missing.
+- [ ] No `crypto-js`, `node-forge`, Buffer polyfill, or `react-native-*` packages added.
+- [ ] `crypto-utils.ts` written (Base64 helpers, nonce generator using `crypto.getRandomValues`).
+- [ ] `aes.service.ts` written (`generateAESKey`, `encryptAESGCM`, `decryptAESGCM` via `crypto.subtle`, tagLength 128).
+- [ ] `rsa.service.ts` written (`importRSAPublicKey` using `importKey('spki', ...)` after stripping PEM headers, `encryptRSAOAEP`).
+- [ ] `rsa-key.service.ts` written (fetch / cache / retry; `KEY_ID_NOT_FOUND` refreshes key + retries exactly once).
+- [ ] `hmac.service.ts` written using `crypto.subtle` HMAC-SHA256.
+- [ ] `storage.service.ts` written (`sessionStorage` wrapper; HTTP-only cookie guidance; `localStorage` explicitly blocked).
+- [ ] `encryption.interceptor.ts` written:
+  - [ ] Request: generates AES key, stores in `Map<requestId, {cryptoKey, iv}>`, attaches envelope.
+  - [ ] Response: decrypts using map entry, deletes entry immediately on success and error.
+  - [ ] `DOMException` on decrypt → `ERR_CRYPTO_REJECTED`, no plaintext fallback.
+- [ ] `encryption-config.ts` written with correct framework env prefix (VITE_ / REACT_APP_ / NEXT_PUBLIC_).
+- [ ] `types.ts` written (`EncryptedEnvelope`, `EncryptedResponse`).
+- [ ] `axiosInstance.ts` patched with `applyProductionEncryptionInterceptor` + `bootstrapEncryption()` bootstrap call.
+- [ ] `.env.example` includes all required env variables with correct prefix.
+- [ ] RSA public key endpoint is HTTPS (if API source).
+- [ ] RSA-OAEP padding confirmed — PKCS1 v1.5 not used.
+
+## Implementation — React JS ECDH-Session Sub-Mode (Approach 7)
+
+- [ ] All RSA-OAEP items above (except `rsa.service.ts`, `rsa-key.service.ts` replaced by ECDH services).
+- [ ] `base64url.ts` written (Base64URL encode/decode, no Buffer).
+- [ ] `aad.ts` written (AAD builder with alphabetical key order, template literal not `JSON.stringify`).
+- [ ] `ecdhSession.ts` written:
+  - [ ] ECDH P-256 key pair via `crypto.subtle.generateKey`.
+  - [ ] `deriveSessionKey` uses `crypto.subtle.deriveKey` with HKDF-SHA256 — no manual HMAC chain.
+  - [ ] Derived AES key is `extractable: false` — never stored.
+  - [ ] ECDH private key exported as JWK for `sessionStorage` restore.
+- [ ] `aesGcm.ts` written (AES-256-GCM encrypt/decrypt with AAD).
+- [ ] `ecdhSessionService.ts` written (init, restore from `sessionStorage`, `clearSession`).
+- [ ] `clearSession()` called on 401 → surfaces `ERR_SESSION_EXPIRED`.
+- [ ] `clearSession()` called on 400 DECRYPTION_FAILED / INVALID_PAYLOAD → surfaces `ERR_CRYPTO_REJECTED`.
+- [ ] 500 responses pass through without session invalidation.
+- [ ] ECDH-Session interceptor adds `X-Request-ID`, `X-Nonce` (12-byte Base64URL), `X-Timestamp` (ISO 8601 UTC) to every request.
+- [ ] HKDF `info` string matches backend contract (NOT assumed to be `'enc'`).
+- [ ] AAD canonical JSON shape confirmed with backend team.
+- [ ] Session init URL is HTTPS.
+- [ ] Device ID source confirmed and consistent across all encrypted requests.
+
+---
+
+## Security
+
+- [ ] No sensitive logging (no AES keys, IVs, auth tags, plaintext payloads, or key material).
+- [ ] No persistent AES key/IV storage.
+- [ ] HTTPS enforced for key endpoint and all API traffic.
+- [ ] Auth tag verification enforced (AES-GCM modes).
+- [ ] FormData excluded from encryption.
+- [ ] `ENCRYPTION_ENABLED=false` is the safe default.
+- [ ] [Native mode] AES key never written to Android Keystore or iOS Secure Enclave.
+- [ ] [Native mode] `try!` not present anywhere in Swift bridge code.
+- [ ] [Approach 3] Shared key is at least 32 characters.
+- [ ] [Angular/Web] `privateKeyPem` not accepted — private keys stay on the server.
+- [ ] [EC] EC public key validated on every fetch: 65 bytes, first byte `0x04`.
+- [ ] [EC] Ephemeral EC key pair discarded immediately after `computeSecret()`.
+- [ ] [EC] Derived AES key never transmitted — only `ephemeral_public_key` in envelope.
+- [ ] [EC session-init] Nonce generator uses CSPRNG (`randomBytes`) — NOT `Math.random()`.
+- [ ] [Approach 7] `crypto.subtle` availability check at bootstrap — surfaces error before any API call.
+- [ ] [Approach 7] No `Math.random()` for any cryptographic purpose — all nonce/key generation uses Web Crypto API.
+- [ ] [Approach 7] No `localStorage` for tokens or session material.
+- [ ] [Approach 7 ECDH-Session] Derived AES key is `extractable: false` — never stored or exported.
+- [ ] [Approach 7 ECDH-Session] ECDH private key stored only as JWK in `sessionStorage`; cleared on `clearSession()`.
+- [ ] [Approach 7] HMAC secret in env var only — never hardcoded, never committed to source.
+
+---
+
+## Operational
+
+- [ ] Concurrent request safety verified (request map keyed by unique `requestId`).
+- [ ] Missing RSA key / refetch flow handled (bounded retry, fail-safe on exhaustion).
+- [ ] Invalid auth tag triggers session reset (not silent fallback).
+- [ ] Build passes after all files are written.
+- [ ] Temp config file (`.encryption-resolved-config.tmp.json`) deleted after install.
+
+---
+
+## Final Output
+
+- [ ] List of all files written/patched included in report.
+- [ ] List of all packages installed included in report.
+- [ ] Encryption approach, model, and layer recorded.
+- [ ] HMAC status recorded.
+- [ ] URL exclusions recorded.
+- [ ] Envelope shape documented:
+  - RSA: `{ data, key, iv, nonce, key_id }`
+  - EC per-request: `{ data, ephemeral_public_key, iv, nonce, key_id }`
+  - EC session-init: backend-specific (confirm shape with backend team)
+  - Approach 7 RSA-OAEP: `{ data, key, iv, nonce, key_id }` (wire-compatible with React Native)
+  - Approach 7 ECDH-Session: backend-specific (confirm with backend team; see `references/react-web-crypto.md`)
+- [ ] Backend alignment spec printed/referenced (approaches 4/5: Part A RSA; approach 6: Part B EC).
+- [ ] [Approach 7] CORS headers confirmed: `Access-Control-Allow-Headers` includes `X-Request-ID`, `X-Nonce`, `X-Request-Signature`, `X-Device-ID`, `X-Timestamp`.
+- [ ] Any residual risks or manual steps noted.
+- [ ] Suggested next validation steps included.