devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/templates/implementation-plan.md

@@ -0,0 +1,304 @@
+# Implementation Plan
+
+Fill out before writing any files. Use after questionnaire completion and validation.
+
+---
+
+## Encryption Model + Layer Selected
+
+### React Native (approaches 4/5/6)
+- [ ] RSA + React Native JS (approach 4)
+- [ ] RSA + Native (approach 5)
+- [ ] EC + React Native JS, per-request (approach 6)
+- [ ] EC + React Native JS, session-init (approach 6)
+- [ ] EC + Native (approach 6 + native layer)
+
+### React JS Web (approach 7)
+- [ ] RSA-OAEP mode (approach 7, default)
+- [ ] ECDH-Session mode (approach 7, sub-mode)
+
+---
+
+## Confirmed Configuration
+
+- Platform:
+- Approach:
+- Detection mode (replace / reuse / refactor):
+- Encryption model (rsa / ec):
+- EC contract type (per-request / session-init):
+- RSA key source (api / env):
+- RSA key endpoint:
+- EC key endpoint:
+- EC HKDF info string (session-init only — backend-confirmed, NO default):
+- EC nonce format/length (session-init only — backend-confirmed, NO default):
+- EC AAD shape (session-init only — backend-confirmed, NO default):
+- EC response IV source (session-init only — backend-confirmed, NO default):
+- Shared key length (approach 3 only):
+- API client type (axios / fetch / custom):
+- API layer path:
+- Encryption toggle (env-flag / always-on):
+- HMAC signing enabled (yes / no):
+- URL exclusions:
+- [React Native approach 5] Minimum iOS version:
+- [React Native approach 5] Android Kotlin package:
+- [Approach 7] Web encryption mode (rsa-oaep / ecdh-session):
+- [Approach 7] Framework/bundler (vite / cra / nextjs):
+- [Approach 7] Env prefix (VITE_ / REACT_APP_ / NEXT_PUBLIC_):
+- [Approach 7] Token storage (session-storage / http-only-cookie):
+- [Approach 7] RSA key endpoint (RSA-OAEP mode):
+- [Approach 7] ECDH session init URL (ECDH-Session mode — no default):
+- [Approach 7] ECDH HKDF info string (ECDH-Session mode — no default):
+- [Approach 7] ECDH AAD shape (ECDH-Session mode — no default if required):
+- [Approach 7] Deployment origin confirmed HTTPS or localhost:
+
+---
+
+## Project Discovery
+
+- React Native version (if RN):
+- Existing API client file:
+- Existing interceptor location (if any):
+- Existing config/env module:
+- Existing token storage service:
+- App startup / init file:
+- [Native mode] Android native modules folder (`android/app/src/main/java/...`):
+- [Native mode] iOS native modules folder (`ios/`):
+- [Angular] NgModule or standalone (check for `app.module.ts`):
+- [Approach 7] `tsconfig.json` lib includes `"DOM"`: yes / no / patch needed:
+- [Approach 7] `axios` present in package.json: yes / no:
+- [Approach 7] Existing `axiosInstance.ts` location (extend, do not replace):
+
+---
+
+## Dependency Plan
+
+### React Native JS Mode (Approaches 2, 3, 4)
+
+- react-native-quick-crypto version:
+- buffer package version (>= 6.0.0):
+- react-native-quick-base64 present (auto-installed — verify with `npm ls react-native-quick-base64`):
+- react-native-keychain version:
+- react-native-get-random-values version:
+- jsencrypt version (approach 2 only):
+- crypto-js version (approaches 2, 3):
+- Already installed (skip):
+- Needs install:
+
+### React Native Native Mode (Approach 5)
+
+- All of JS mode packages plus:
+- react-native-aes-crypto version (if not using NativeCryptoModule):
+- react-native-rsa-native version (if not using NativeCryptoModule):
+- Android `minSdkVersion >= 23` verified: yes / no
+- iOS deployment target `>= 13.0` verified: yes / no / CommonCrypto fallback planned
+
+### React Native EC Mode (Approach 6)
+
+- react-native-quick-crypto version:
+- react-native-nitro-modules version (REQUIRED peer dep — quick-crypto >= 1.0 / RN >= 0.76):
+- react-native-worklets version (REQUIRED peer dep — quick-crypto >= 1.0 / RN >= 0.76):
+- buffer package version (>= 6.0.0, used for Hermes-safe helpers):
+- react-native-keychain version:
+- react-native-get-random-values version:
+- `npm ls react-native-nitro-modules` — UNMET PEER DEP present: yes / no
+- Android .cxx cache cleared: yes / no
+- iOS pod install completed: yes / no
+
+### React JS Web Production Mode (Approach 7)
+
+- No crypto packages required (Web Crypto API is built-in)
+- `axios` present: yes / no (install if missing)
+- Do NOT install: `crypto-js`, `node-forge`, Buffer polyfill, any `react-native-*` package
+- Package manager: npm
+
+### Other Platforms
+
+- Package manager (npm / yarn / pnpm / gradle / pub):
+- Packages to install:
+- Packages already present:
+
+---
+
+## Files to Write
+
+### All Platforms
+
+| File | Path | Status (new / skip / scaffold) |
+|------|------|-------------------------------|
+| Config | | |
+| Service | | |
+| Interceptor / Middleware | | |
+| Module wiring | | |
+
+### React Native Approaches 4 and 5 (additional)
+
+| File | Path | Status |
+|------|------|--------|
+| types.ts | src/services/security/types.ts | |
+| encryption.service.ts | src/services/security/encryption.service.ts | |
+| decryption.service.ts | src/services/security/decryption.service.ts | |
+| rsa-key.service.ts | src/services/security/rsa-key.service.ts | |
+| keychain.service.ts | src/services/security/keychain.service.ts | |
+| hmac.service.ts | src/services/security/hmac.service.ts | |
+| encryption-config.ts | src/services/security/encryption-config.ts | |
+| encryption.interceptor.ts | src/services/security/encryption.interceptor.ts | |
+| axiosInstance.ts | src/api/axiosInstance.ts | |
+| index.js polyfill | index.js (prepend) | |
+
+### Native Mode (Approach 5) Additional
+
+| File | Path | Status |
+|------|------|--------|
+| NativeCryptoModule.kt | android/app/src/main/java/…/NativeCryptoModule.kt | |
+| NativeCryptoPackage.kt | android/app/src/main/java/…/NativeCryptoPackage.kt | |
+| NativeCryptoModule.swift | ios/NativeCryptoModule.swift | |
+| NativeCryptoModule.m | ios/NativeCryptoModule.m | |
+| native-crypto.module.ts | src/services/security/native-crypto.module.ts | |
+
+### EC Mode (Approach 6) — JS or Native Layer
+
+| File | Path | Status |
+|------|------|--------|
+| types.ts (EC additions) | src/services/security/types.ts | |
+| ec-key.service.ts | src/services/security/ec-key.service.ts | |
+| ec-crypto.util.ts | src/services/security/ec-crypto.util.ts | |
+| keychain.service.ts | src/services/security/keychain.service.ts | |
+| hmac.service.ts | src/services/security/hmac.service.ts | |
+| encryption-config.ts | src/services/security/encryption-config.ts | |
+| encryption.interceptor.ts | src/services/security/encryption.interceptor.ts | |
+| axiosInstance.ts | src/api/axiosInstance.ts | |
+| index.js polyfill | index.js (prepend) | |
+
+### EC Session-Init Additional Files
+
+| File | Path | Status |
+|------|------|--------|
+| auth-api.service.ts | src/services/security/auth-api.service.ts | |
+
+### React JS Web Production Mode (Approach 7) — RSA-OAEP Mode
+
+| File | Path | Status |
+|------|------|--------|
+| crypto-utils.ts | src/services/security/crypto-utils.ts | |
+| aes.service.ts | src/services/security/aes.service.ts | |
+| rsa.service.ts | src/services/security/rsa.service.ts | |
+| rsa-key.service.ts | src/services/security/rsa-key.service.ts | |
+| hmac.service.ts | src/services/security/hmac.service.ts | |
+| storage.service.ts | src/services/security/storage.service.ts | |
+| encryption.interceptor.ts | src/services/security/encryption.interceptor.ts | |
+| encryption-config.ts | src/services/security/encryption-config.ts | |
+| types.ts | src/services/security/types.ts | |
+| axiosInstance.ts (patch) | src/api/axiosInstance.ts | |
+| .env.example | .env.example | |
+
+### React JS Web Production Mode (Approach 7) — ECDH-Session Additional Files
+
+| File | Path | Status |
+|------|------|--------|
+| base64url.ts | src/core/security/ecdh-session/base64url.ts | |
+| aad.ts | src/core/security/ecdh-session/aad.ts | |
+| ecdhSession.ts | src/core/security/ecdh-session/ecdhSession.ts | |
+| aesGcm.ts | src/core/security/ecdh-session/aesGcm.ts | |
+| ecdhSessionService.ts | src/core/security/ecdh-session/ecdhSessionService.ts | |
+
+---
+
+## Runtime Behaviour
+
+- Methods encrypted: POST, PUT, PATCH (default)
+- Methods skipped: GET, DELETE, FormData
+- Request mapping strategy: `requestId (randomHex16) → { aesKey, iv }` in-memory Map
+- Key refresh trigger: `KEY_ID_NOT_FOUND` (401) → invalidate cache → retry once
+- Auth tag failure: trigger session reset / force logout
+- Request map cleanup: immediately after response (success or failure)
+- [Native mode] Native module availability check: at JS startup, before first encrypted request
+- [Native mode] Behavior if NativeModules.NativeCryptoModule is undefined at runtime:
+- [Approach 7] `crypto.subtle` availability check: at bootstrap, surface `ERR_CRYPTO_NOT_AVAILABLE` if undefined
+- [Approach 7] Request key map type: `Map<string, { cryptoKey: CryptoKey; iv: Uint8Array }>`
+- [Approach 7] Request ID generation: `crypto.randomUUID()`
+- [Approach 7] `KEY_ID_NOT_FOUND` (401): refresh RSA key → retry exactly once (no loop)
+- [Approach 7] `DOMException` on decryption: fail with `ERR_CRYPTO_REJECTED` — no fallback to plaintext
+- [Approach 7 ECDH-Session] 401 response: `clearSession()` + `ERR_SESSION_EXPIRED`
+- [Approach 7 ECDH-Session] DECRYPTION_FAILED / INVALID_PAYLOAD (400): `clearSession()` + `ERR_CRYPTO_REJECTED`
+- [Approach 7 ECDH-Session] 500 responses: pass through without session invalidation
+
+---
+
+## Feature Flags
+
+- `ENCRYPTION_ENABLED` source: env var (react-native-config or process.env)
+- Default by environment: `false` in dev, `true` in staging/prod
+- `ENCRYPTION_MODEL` source: env var; values: `rsa` / `ec` (default: `rsa`)
+- [Native mode] `ENCRYPTION_LAYER` source: env var; values: `rn` / `native`
+- `ENCRYPTION_HMAC_SECRET` source: env var at runtime; never written to disk
+- [EC] `EC_PUBLIC_KEY_ENDPOINT` source: env var
+- [EC] `EC_KEY_RETRY` source: env var; default `3`
+- [Approach 7] `ENCRYPTION_ENABLED` prefix: `VITE_` / `REACT_APP_` / `NEXT_PUBLIC_` (framework-specific)
+- [Approach 7] `RSA_PUBLIC_KEY_ENDPOINT` prefix: same framework prefix
+- [Approach 7] `ENCRYPTION_HMAC_SECRET` prefix: same framework prefix; runtime only — never commit to source
+- [Approach 7 ECDH-Session] `ECDH_SESSION_INIT_URL` prefix: same framework prefix
+
+---
+
+## Build Verification
+
+- Build command (from `platform-matrix.json`):
+- Max retries: 3
+- Expected exit code: 0
+
+---
+
+## Testing Plan
+
+### Both Modes
+
+- Unit tests: EncryptionService encrypt/decrypt round-trip
+- Integration tests: POST request encrypted end-to-end with real server
+- Negative tests: tampered ciphertext → verify 400 DECRYPTION_FAILED; duplicate nonce → verify 400 INVALID_NONCE
+- Concurrent request test: multiple in-flight requests with independent key maps
+
+### Native Mode Only
+
+- AES round-trip on physical Android device (API 23+)
+- AES round-trip on physical iOS device (iOS 13+)
+- `NativeModules.NativeCryptoModule` accessible from JS confirmed
+- `encryptAES` + `decryptAES` + `encryptRSA` all return Promises and resolve correctly
+
+### EC Mode (Approach 6)
+
+- EC public key fetch returns 65-byte uncompressed P-256 point (first byte 0x04)
+- `ecEncryptPayload` round-trip: encrypts and server decrypts successfully
+- Ephemeral key pair confirmed discarded after `computeSecret()` (no key reference retained)
+- Derived AES key confirmed NOT present in request envelope
+- Only `ephemeral_public_key` (base64, 65 bytes) sent in envelope
+- Hermes Buffer: `toBase64()` helper used instead of `Buffer.toString('base64')` — verified no mangled output
+- `byteCopy()` used for Buffer slices passed to quick-crypto native code
+- Dual Buffer imports compile without conflict
+- [Session-init] HKDF info string matches backend contract exactly
+- [Session-init] Nonce generator uses `randomBytes` — confirmed no `Math.random()` usage
+- [Session-init] AAD JSON keys are alphabetically sorted before encryption
+- [Session-init] `device_id` matches across init, HKDF derivation, AAD, and all encrypted requests
+- [Session-init] `initEncryptionSession` validated against reference client output (if reference exists)
+
+### React JS Web Production Mode (Approach 7)
+
+- `crypto.subtle` available on target origin (HTTPS or localhost)
+- `tsconfig.json` `"lib": ["DOM"]` confirmed — `crypto.subtle` TypeScript types resolve
+- RSA-OAEP: `importKey('spki', ...)` succeeds (PEM headers stripped correctly)
+- RSA-OAEP: `encryptRSAOAEP` returns Base64 ciphertext
+- AES-GCM: round-trip encrypt/decrypt completes without `DOMException`
+- Per-request AES key map: `Map<requestId, {cryptoKey, iv}>` — entry created on request, deleted on response (success and error)
+- `KEY_ID_NOT_FOUND` (401): RSA key cache invalidated, retried exactly once — no retry loop
+- Auth tag tamper: `DOMException` thrown, `ERR_CRYPTO_REJECTED` surfaced — no fallback to plaintext
+- No `crypto-js`, `node-forge`, or Buffer polyfill imported
+- `sessionStorage` used for non-token state; `localStorage` never used for sensitive data
+- HMAC-SHA256 signs request (when enabled); no secret in source files
+- [ECDH-Session] ECDH P-256 key pair generated via `crypto.subtle.generateKey`
+- [ECDH-Session] Derived AES key is `extractable: false` — cannot be exported
+- [ECDH-Session] ECDH private key stored as JWK in `sessionStorage` only; cleared on `clearSession()`
+- [ECDH-Session] `deriveKey` uses native HKDF-SHA256 — no manual HMAC chain
+- [ECDH-Session] AAD keys alphabetically sorted (template literal, not `JSON.stringify`)
+- [ECDH-Session] 401 response → `clearSession()` + `ERR_SESSION_EXPIRED`
+- [ECDH-Session] 400 DECRYPTION_FAILED → `clearSession()` + `ERR_CRYPTO_REJECTED`
+- [ECDH-Session] `X-Request-ID`, `X-Nonce`, `X-Timestamp` headers on every request
+- [ECDH-Session] `X-Timestamp` formatted as ISO 8601 UTC (`new Date().toISOString()`)