devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/template.md

@@ -0,0 +1,241 @@
+# Skill Execution Template: Encryption-Decryption Generator
+
+Use this template whenever this skill is invoked. Follow steps in order.
+
+---
+
+## 0) Pre-Flight: Dependency Chain Check (React Native projects only)
+
+Before asking any questions, verify the dependency chain will work:
+
+```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 React Native >= 0.76 and `react-native-quick-crypto` >= 1.0 will be used:
+- `react-native-nitro-modules` MUST be installed (peer dep, not auto-installed reliably)
+- `react-native-worklets` MUST be installed (peer dep)
+- After install, Android `.cxx` cache MUST be cleaned before building
+- See `references/dependency-guidance.md` → "CRITICAL: Transitive Dependencies" for version matrix
+
+---
+
+## 1) Platform and Approach Gate (Ask First)
+
+Before any other question, confirm:
+
+1. **Which platform?**
+   Options: `angular`, `web`, `node`, `android`, `ios`, `flutter`, `react`, `react-native`
+   Default for this workspace: `react-native`
+
+2. **For React Native — which encryption layer?**
+   - **React Native (JS)** — JS-based crypto using `react-native-quick-crypto`. Default = approach 4.
+   - **Native** — Device OS-level crypto. Android `javax.crypto.Cipher` + iOS CryptoKit/CommonCrypto. Default = approach 5.
+   If omitted, apply default (React Native JS / approach 4) and continue.
+
+3. **For React Native — which encryption model?**
+   - **RSA** (default) — RSA-OAEP key wrapping. Approach 4 (JS) or 5 (Native).
+   - **EC** — ECDH P-256 + HKDF-SHA256 + AES-256-GCM. Approach 6. Per-request or session-init contract.
+   If omitted, apply RSA default.
+
+4. **Which approach?** (validate against `assets/platform-matrix.json`)
+
+Collect all remaining configuration questions in one pass using `templates/config-questionnaire.md`.
+Do not write any files until all answers are received and validated.
+Apply documented defaults automatically for unanswered non-critical fields.
+
+---
+
+## 2) Confirmed Configuration Snapshot
+
+Record final selections before implementation (copy from `templates/config-questionnaire.md`):
+
+- Platform:
+- Approach:
+- Encryption layer (RN only): React Native (JS) / Native
+- RSA padding: Default = RSA-OAEP
+- RSA key source: Default = API
+- RSA key endpoint: Default = `<API_BASE_URL>/api/security/public-key`
+- RSA key retries: Default = 3
+- RSA key response format: Default = `{ public_key: string, key_id: string, expires_at?: string }`
+- RSA key caching policy: Default = in-memory only (never persist to disk or storage)
+- [EC model only] EC contract type: Default = per-request (**ask developer** for session-init; no default)
+- [EC model only] EC key endpoint: Default = `<API_BASE_URL>/api/security/ec-public-key`
+- [EC session-init only] `SESSION_INIT_ENDPOINT`: **REQUIRED — ask developer, no default**
+- [EC session-init only] `CREATE_SESSION_ENDPOINT`: **REQUIRED — ask developer, no default**
+- [EC session-init only] `HKDF_INFO` string: **REQUIRED — ask developer, no default** (never assume `'enc'`)
+- [EC session-init only] `AAD_SHAPE` (canonical JSON field list): **REQUIRED — ask developer, no default**
+- [EC session-init only] `NONCE_FORMAT` (length, charset, encoding): **REQUIRED — ask developer, no default**
+- [EC session-init only] `RESPONSE_ENCODING` (standard-base64 / base64url): **REQUIRED — ask developer, no default**
+- [EC session-init only] `DEVICE_ID_SOURCE`: **REQUIRED — ask developer, no default**
+- [EC session-init only] `encrypted_shared_aes_key` handling: **REQUIRED — ask developer** (used / ignored)
+- API client type: Default = Axios
+- API layer path: Default = `src/services/api.ts`
+- Encryption toggle: Default = env-flag
+- HMAC signing: Default = No
+- URL exclusions: Default = none
+- [Native mode only] Min iOS version: Default = 13
+- [Native mode only] Android Kotlin package: Default = `com.example.security`
+
+---
+
+## 3) Project Analysis
+
+Before writing any file, identify existing structure to avoid duplication:
+
+- API client file location:
+- Existing interceptor location (if any):
+- Config / env module (react-native-config, dotenv, etc.):
+- Token / storage service:
+- App startup / init file (`index.js`, `main.ts`, `App.tsx`, etc.):
+- [Native mode] Android native modules folder (`android/app/src/main/java/...`):
+- [Native mode] iOS native modules folder (`ios/`):
+- [Angular] NgModule or standalone (check for `src/app/app.module.ts`):
+
+Do not create unnecessary folders or duplicate existing architecture.
+
+---
+
+## 4) Dependency and Compatibility Check
+
+1. Read React Native / framework version from `package.json` or project manifest.
+2. Check existing crypto, keychain, and network dependencies.
+3. Use `references/dependency-guidance.md` to select compatible package versions.
+4. Identify which packages are already installed (skip those).
+5. Propose install command for new packages only.
+
+---
+
+## 5) Run detect.js
+
+```bash
+node scripts/detect.js --project-path <projectPath>
+```
+
+- Exit 0 (ENCRYPTION_NOT_FOUND): proceed normally.
+- Exit 1 (ENCRYPTION_FOUND): display the reuse/replace/refactor/cancel menu and wait for user input before continuing.
+- Exit 2 (input error): report and halt.
+
+---
+
+## 6) Implementation Plan
+
+Fill out `templates/implementation-plan.md` before writing any files:
+
+React Native JS mode files to write:
+- `src/services/security/types.ts`
+- `src/services/security/encryption.service.ts`
+- `src/services/security/decryption.service.ts`
+- `src/services/security/rsa-key.service.ts`
+- `src/services/security/keychain.service.ts`
+- `src/services/security/hmac.service.ts`
+- `src/services/security/encryption-config.ts`
+- `src/services/security/encryption.interceptor.ts`
+
+EC mode (approach 6) files to write:
+- `src/services/security/types.ts` (add EC types alongside RSA types)
+- `src/services/security/ec-key.service.ts`
+- `src/services/security/ec-crypto.util.ts` (per-request: `ecEncryptPayload`/`ecDeriveKey`; session-init: `deriveSessionKey`/`sessionEncrypt`/`sessionDecrypt`)
+- `src/services/security/keychain.service.ts`
+- `src/services/security/hmac.service.ts` (if HMAC enabled)
+- `src/services/security/encryption-config.ts`
+- Patch `src/services/api.ts` with `ENCRYPTION_MODEL` routing
+- `src/api/axiosInstance.ts` (create or patch)
+- `index.js` (prepend polyfill)
+
+Native mode additional files:
+- `android/…/NativeCryptoModule.kt`
+- `android/…/NativeCryptoPackage.kt`
+- `ios/NativeCryptoModule.swift`
+- `ios/NativeCryptoModule.m`
+- `src/services/security/native-crypto.module.ts`
+
+---
+
+## 7) Generate and Install Files
+
+1. Build a resolved config from `assets/encryption-config-template.json` merged with collected inputs.
+2. Write config to a temporary file (delete immediately after install regardless of exit code).
+3. Run: `node scripts/install.js --config-json <tempFile> [--detection-mode <mode>]`
+4. On exit 0: continue. On exit 1 or 2: report and halt.
+
+---
+
+## 8) Validation Checklist (Both Modes)
+
+- POST/PUT/PATCH encrypted correctly.
+- GET and FormData skipped.
+- Nonce generated per request.
+- Request map handles concurrency (unique `requestId` per request).
+- Key unavailable path fails securely (blocks encrypted calls).
+- Invalid auth tag path triggers secure logout/session reset.
+- No sensitive logging.
+- Auth tag verified on decryption.
+
+React Native JS mode:
+- AES-256-GCM and auth tag verified via `react-native-quick-crypto`.
+
+Native mode:
+- AES-256-GCM verified by native platform cipher (Android `javax.crypto.Cipher` / iOS CryptoKit).
+- `NativeModules.NativeCryptoModule` accessible from JS at startup.
+
+Run items from `references/security-checklist.md` (platform section) and `templates/delivery-checklist.md`.
+
+### EC Mode (Approach 6) Additional Validation
+
+- Server EC public key validated: 65 bytes, first byte `0x04`.
+- ECDH shared secret computed correctly.
+- Derived AES key never logged or transmitted — only `ephemeral_public_key` in envelope.
+- Ephemeral EC key pair discarded after `computeSecret()`.
+- `toBase64()` helper used everywhere — NOT `Buffer.toString('base64')` (broken on Hermes).
+- `byteCopy()` used on sliced buffers before passing to quick-crypto native code.
+- Dual Buffer imports compile without conflict (`Buffer from 'buffer'` + `Buffer as QCBuffer from 'react-native-quick-crypto'`).
+
+### Session-Init EC Mode (Additional Validation)
+
+- `deriveSessionKey()` uses backend's exact HKDF `info` string (not `'enc'`).
+- `buildSessionAad()` produces canonical JSON with alphabetically sorted keys.
+- `sessionEncrypt()` uses nonce-as-IV and correct AAD (confirmed from contract).
+- `sessionDecrypt()` uses correct IV source (confirmed from contract).
+- `urlSafeBase64ToStd()` applied to all base64url fields from server.
+- `initEncryptionSession` sends real freshly-generated `client_ecdh_pub`.
+- `createSession` runs only after `initEncryptionSession` succeeds.
+- `encrypted_shared_aes_key` handling matches confirmed contract.
+- `device_id` consistent across init, HKDF, AAD, and encrypted requests.
+- Nonce format matches backend contract exactly.
+- Nonce generator uses CSPRNG (`randomBytes`) — NOT `Math.random()` — nonce IS the AES-GCM IV.
+- Token persistence is separate from session key lifetime.
+- Dead debug code removed (unwrapSessionKey, tryAesGcmDecrypt, hkdfExpandOnly, hkdfSwapped).
+
+---
+
+## 9) Backend Alignment
+
+For approaches 4 and 5, print the full backend contract from `references/backend-alignment.md` so the user can share it with their server team.
+
+---
+
+## 10) Build Verification
+
+Read `buildCommand` from `assets/platform-matrix.json` for the selected platform and run it.
+Retry up to 3 times on failure, then report exit code 4.
+
+---
+
+## 11) Setup Report
+
+Print the 6-field setup report:
+
+```
+=== SETUP REPORT ===
+Platform                : <platform>
+Approach                : <approach>
+HMAC enabled            : <true|false>
+URL exclusions          : <comma-separated or blank>
+Files written/patched   : <integer>
+Build status            : <PASS|FAIL>
+====================
+```
+
+Include packages installed, any manual steps required (pod install, MainApplication registration), and residual risks.