devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/approach-2-rsa-aes-cbc.md

@@ -0,0 +1,111 @@
+# Approach 2 — RSA + AES-256-CBC (jsencrypt + crypto-js)
+
+## Overview
+
+Uses **jsencrypt** for RSA key wrapping and **crypto-js** for AES-256-CBC.  
+Supported on all 6 platforms via equivalent library bindings.  
+Requires a generated RSA key pair.
+
+---
+
+## Payload Shape
+
+```json
+{
+  "encryptedKey":  "<base64 RSA-encrypted AES key bytes>",
+  "iv":            "<base64 16-byte IV>",
+  "salt":          "<base64 8-byte PBKDF2 salt>",
+  "encryptedData": "<base64 AES-CBC ciphertext>"
+}
+```
+
+---
+
+## Encryption Flow (TypeScript/JavaScript)
+
+```ts
+import JSEncrypt from 'jsencrypt';
+import CryptoJS  from 'crypto-js';
+
+function encrypt(body: object, publicKeyPem: string): object {
+  // 1. Generate random AES key + IV + salt
+  const aesKey = CryptoJS.lib.WordArray.random(32); // 256-bit
+  const iv     = CryptoJS.lib.WordArray.random(16);
+  const salt   = CryptoJS.lib.WordArray.random(8);
+
+  // 2. AES-256-CBC encrypt
+  const plaintext  = JSON.stringify(body);
+  const encrypted  = CryptoJS.AES.encrypt(plaintext, aesKey, { iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 });
+
+  // 3. RSA-encrypt the AES key bytes
+  const jsEncrypt = new JSEncrypt();
+  jsEncrypt.setPublicKey(publicKeyPem);
+  const encryptedKey = jsEncrypt.encrypt(CryptoJS.enc.Base64.stringify(aesKey));
+
+  return {
+    encryptedKey:  encryptedKey || '',
+    iv:            CryptoJS.enc.Base64.stringify(iv),
+    salt:          CryptoJS.enc.Base64.stringify(salt),
+    encryptedData: encrypted.toString(),
+  };
+}
+```
+
+---
+
+## Decryption Flow (backend — Java/Spring example)
+
+```java
+import javax.crypto.Cipher;
+import javax.crypto.spec.IvParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.security.PrivateKey;
+import java.util.Base64;
+
+public String decrypt(Map<String,String> payload, PrivateKey privateKey) throws Exception {
+    byte[] encryptedKeyBytes = Base64.getDecoder().decode(payload.get("encryptedKey"));
+    Cipher rsaCipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
+    rsaCipher.init(Cipher.DECRYPT_MODE, privateKey);
+    byte[] aesKeyBytes = rsaCipher.doFinal(encryptedKeyBytes);
+
+    byte[] iv            = Base64.getDecoder().decode(payload.get("iv"));
+    byte[] encryptedData = Base64.getDecoder().decode(payload.get("encryptedData"));
+
+    SecretKeySpec aesKey = new SecretKeySpec(aesKeyBytes, "AES");
+    Cipher aesCipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
+    aesCipher.init(Cipher.DECRYPT_MODE, aesKey, new IvParameterSpec(iv));
+    return new String(aesCipher.doFinal(encryptedData), "UTF-8");
+}
+```
+
+---
+
+## Key Generation (OpenSSL)
+
+```bash
+openssl genrsa -out private.pem 2048
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+---
+
+## Required Config Fields
+
+| Field         | Required | Notes                          |
+|---------------|----------|-------------------------------|
+| approach      | Yes      | Must be `2`                   |
+| publicKeyPem  | Yes      | PEM string                    |
+| privateKeyPem | No       | Only if response is encrypted |
+
+---
+
+## Platform Dependencies (install.js uses platform-matrix.json)
+
+| Platform  | Packages                           |
+|-----------|------------------------------------|
+| angular   | `jsencrypt`, `crypto-js`           |
+| web       | `jsencrypt`, `crypto-js`           |
+| node      | `jsencrypt`, `crypto-js`           |
+| android   | Built-in `javax.crypto`            |
+| ios       | `CryptoSwift` or `CommonCrypto`    |
+| flutter   | `encrypt`, `pointycastle`          |

package/.github/skills/encryption-decryption-utility/references/approach-3-aes-sharedkey.md

@@ -0,0 +1,114 @@
+# Approach 3 — AES-256-CBC Shared Key (crypto-js)
+
+## Overview
+
+Symmetric-only approach. Both client and server share the same secret key.  
+No RSA key pair required.  
+Supported on all 6 platforms.  
+Simplest to set up; suitable when PKI infrastructure is not available.
+
+---
+
+## Payload Shape
+
+```json
+{
+  "iv":            "<base64 16-byte IV>",
+  "encryptedData": "<base64 AES-CBC ciphertext>"
+}
+```
+
+---
+
+## Encryption Flow (TypeScript/JavaScript via crypto-js)
+
+```ts
+import CryptoJS from 'crypto-js';
+
+function encrypt(body: object, sharedKey: string): object {
+  // 1. Derive a 256-bit key from the shared secret via SHA-256
+  const key = CryptoJS.SHA256(sharedKey);
+
+  // 2. Generate a random 16-byte IV
+  const iv = CryptoJS.lib.WordArray.random(16);
+
+  // 3. AES-256-CBC encrypt
+  const encrypted = CryptoJS.AES.encrypt(
+    JSON.stringify(body),
+    key,
+    { iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }
+  );
+
+  return {
+    iv:            CryptoJS.enc.Base64.stringify(iv),
+    encryptedData: encrypted.toString(),
+  };
+}
+
+function decrypt(payload: { iv: string; encryptedData: string }, sharedKey: string): object {
+  const key       = CryptoJS.SHA256(sharedKey);
+  const iv        = CryptoJS.enc.Base64.parse(payload.iv);
+  const decrypted = CryptoJS.AES.decrypt(payload.encryptedData, key, { iv, mode: CryptoJS.mode.CBC });
+  return JSON.parse(decrypted.toString(CryptoJS.enc.Utf8));
+}
+```
+
+---
+
+## Decryption Flow (backend — Node.js)
+
+```js
+const crypto = require('crypto');
+
+function decrypt(payload, sharedKey) {
+  const key = crypto.createHash('sha256').update(sharedKey).digest();
+  const iv  = Buffer.from(payload.iv, 'base64');
+  const enc = Buffer.from(payload.encryptedData, 'base64');
+
+  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  const decrypted = Buffer.concat([decipher.update(enc), decipher.final()]);
+  return JSON.parse(decrypted.toString('utf8'));
+}
+```
+
+---
+
+## Shared Key Generation (OpenSSL)
+
+```bash
+# Generate a 256-bit (32-byte) random key and encode as base64
+openssl rand -base64 32
+```
+
+Store this value as `sharedKey` in both the config and the server environment.
+
+---
+
+## Required Config Fields
+
+| Field      | Required | Notes                                |
+|------------|----------|-------------------------------------|
+| approach   | Yes      | Must be `3`                         |
+| sharedKey  | Yes      | 32+ character string or base64 key  |
+
+---
+
+## Security Considerations
+
+- The shared key must NEVER be committed to source control
+- Use environment variables or a secrets manager (Azure Key Vault, AWS Secrets Manager)
+- Rotate the key whenever a team member with access leaves
+- Use different keys per environment (dev/staging/prod)
+
+---
+
+## Platform Dependencies (install.js uses platform-matrix.json)
+
+| Platform  | Packages                         |
+|-----------|----------------------------------|
+| angular   | `crypto-js`                      |
+| web       | `crypto-js`                      |
+| node      | `crypto-js` or built-in `crypto` |
+| android   | Built-in `javax.crypto`          |
+| ios       | Built-in `CommonCrypto`          |
+| flutter   | `encrypt`, `pointycastle`        |

package/.github/skills/encryption-decryption-utility/references/architecture.md

@@ -0,0 +1,233 @@
+# Architecture Reference
+
+This skill supports two production crypto backend modes for React Native (approaches 4 and 5).
+The interceptor layer, key management contract, request envelope shape, and secure storage are
+identical across both modes. Only the crypto primitives change.
+
+For all other platforms (Angular, Web, Node.js, Android, iOS, Flutter) using approaches 1–3,
+the architecture is simpler: a single interceptor/middleware wraps an `EncryptionService` that
+performs AES-CBC or RSA+AES-CBC synchronously. See the platform-specific reference files.
+
+---
+
+## Mode A: React Native JS (Approach 4 — Current Default)
+
+Crypto runs inside JavaScript using `react-native-quick-crypto`. No native module changes required.
+
+### Core Components
+
+- **Encryption service** (`src/services/security/encryption.service.ts`)
+  - Creates a per-request AES key (32 bytes) and IV (12 bytes) using JS `randomBytes`.
+  - Encrypts payload with AES-256-GCM in JS.
+  - Produces ciphertext + 16-byte auth tag (appended), Base64-encoded.
+  - Runs asynchronously — never blocks the UI thread.
+- **RSA key service** (`src/services/security/rsa-key.service.ts`)
+  - Fetches or loads the server RSA public key.
+  - Default padding: RSA-OAEP (SHA-256). PKCS1 v1.5 only with explicit written approval for legacy systems.
+  - Caches the key in memory only.
+  - Retries key fetch with bounded strategy (default 3 attempts).
+  - Provides `invalidateRsaKey()` for key rotation handling.
+- **API interceptor** (`src/services/security/encryption.interceptor.ts`)
+  - Request interceptor: encrypts eligible methods (POST, PUT, PATCH) asynchronously.
+  - Response interceptor: decrypts using in-memory request mapping (`requestId → { aesKey, iv }`).
+  - Clears the mapping immediately after each response (success or failure).
+  - On `KEY_ID_NOT_FOUND` (401): refreshes RSA key and retries the request exactly once.
+- **Decryption service** (`src/services/security/decryption.service.ts`)
+  - Splits auth tag (last 16 bytes) from ciphertext.
+  - Decrypts using AES-256-GCM with the per-request AES key and the response IV.
+- **Secure storage** (`src/services/security/keychain.service.ts`)
+  - Stores long-lived tokens and sensitive persisted fields via `react-native-keychain`.
+  - Never stores AES keys, IVs, or decrypted response payloads.
+- **HMAC service** (`src/services/security/hmac.service.ts`)
+  - HMAC-SHA256 request signing when enabled.
+  - Secret read from `ENCRYPTION_HMAC_SECRET` env var at runtime — never written to disk.
+- **Config** (`src/services/security/encryption-config.ts`)
+  - Feature flags: `ENCRYPTION_ENABLED`, `HMAC_ENABLED`, `ENCRYPTION_LAYER`.
+  - `EXCLUDED_PATHS` list for endpoints that bypass encryption.
+  - `RSA_KEY_ENDPOINT` for server key fetch URL.
+
+---
+
+## Mode B: React Native Native (Approach 5)
+
+Crypto operations run inside the device's OS-level crypto engine (`javax.crypto.Cipher` on
+Android, `CryptoKit` on iOS). The per-request AES key is generated in JS using `randomBytes(32)`
+and passed into every native encrypt/decrypt call as a base64 parameter — it is ephemeral and
+lives only in the JS request map. No RSA key material is stored on the client.
+
+### Core Components
+
+All of Mode A, plus:
+
+- **NativeCryptoModule (Android)** (`android/.../NativeCryptoModule.kt`)
+  - Registered via `NativeCryptoPackage.kt` in `MainApplication`.
+  - `encryptAES(plaintext, keyBase64)` — `Cipher.getInstance("AES/GCM/NoPadding")` using caller-provided key; returns `{ ciphertext, iv }` where ciphertext includes the appended 16-byte GCM auth tag, all Base64.
+  - `decryptAES(ciphertextBase64, ivBase64, keyBase64)` — `Cipher.DECRYPT_MODE` with `GCMParameterSpec`; GCM verifies auth tag automatically.
+  - `encryptRSA(publicKeyPEM, dataBase64)` — `Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")` using the server's PEM public key.
+- **NativeCryptoModule (iOS)** (`ios/NativeCryptoModule.swift`)
+  - Bridged via `ios/NativeCryptoModule.m`.
+  - `encryptAES(plaintext, keyBase64)` — `CryptoKit.AES.GCM.seal` (iOS 13+) using caller-provided key; returns `{ ciphertext, iv }` where ciphertext includes the appended auth tag, all Base64.
+  - `decryptAES(ciphertextBase64, ivBase64, keyBase64)` — `CryptoKit.AES.GCM.open`; splits last 16 bytes as auth tag.
+  - `encryptRSA(publicKeyPEM, dataBase64)` — `SecKeyCreateEncryptedData` with `.rsaEncryptionOAEPSHA256`.
+  - All methods use `do/try/catch` — `try!` is **never** used.
+- **JS Bridge Interface** (`src/services/security/native-crypto.module.ts`)
+  - Exposes `nativeEncryptAES`, `nativeDecryptAES`, `nativeEncryptRSA` to the JS codebase.
+  - Same function signatures used in the interceptor regardless of which native platform is running.
+- **API interceptor** (same structure as Mode A)
+  - Request interceptor calls `nativeEncryptAES` + `nativeEncryptRSA` instead of JS equivalents.
+  - Response interceptor calls `nativeDecryptAES`.
+  - Request mapping and cleanup are identical to Mode A.
+
+### Native Data Flow
+
+1. App startup: native module registered; RSA public key loaded and cached.
+2. Outbound request (POST/PUT/PATCH):
+   - JS interceptor generates `aesKey = randomBytes(32)` and `requestId = randomBytes(16).toString('hex')`.
+   - Calls `nativeEncryptAES(plaintext, aesKey.toString('base64'))` → `{ ciphertext, iv }`.
+   - Calls `nativeEncryptRSA(publicKeyPEM, aesKey.toString('base64'))` → `encryptedKey`.
+   - Stores `requestId → { aesKeyBase64, iv }` in request map.
+   - Sends envelope `{ data, key, iv, nonce, key_id }` over HTTPS.
+3. Response:
+   - Interceptor retrieves `{ aesKeyBase64, iv }` from request map by `requestId`.
+   - Calls `nativeDecryptAES(encResp.data, encResp.iv, aesKeyBase64)` → plaintext.
+   - Deletes request map entry immediately.
+
+### Feature Flag
+
+```
+ENCRYPTION_ENABLED=true
+ENCRYPTION_LAYER=native   # or: rn  (React Native JS mode)
+```
+
+The interceptor reads `ENCRYPTION_LAYER` to decide which crypto path to use.
+
+---
+
+## Request Contract (Both Modes — Identical Envelope)
+
+```json
+{
+  "data":   "base64(ciphertext + 16-byte GCM auth_tag)",
+  "key":    "base64(RSA-OAEP encrypted AES key bytes)",
+  "iv":     "base64(12-byte IV)",
+  "nonce":  "appId^unix_timestamp_ms.random_hex_16",
+  "key_id": "v1"
+}
+```
+
+## Response Contract (Both Modes — When Response Is Encrypted)
+
+```json
+{
+  "data":  "base64(ciphertext + 16-byte GCM auth_tag)",
+  "iv":    "base64(fresh 12-byte IV — server-generated, never the request IV)",
+  "nonce": "server_nonce"
+}
+```
+
+---
+
+## Security Constraints (Both Modes)
+
+- Never persist AES keys or IVs.
+- Never reuse IVs (response must use a fresh server-generated IV).
+- Never log cryptographic secrets.
+- Fail secure on auth tag mismatch — trigger session reset/force logout.
+- Block encrypted endpoints when RSA key is unavailable (after retries exhausted).
+- Clear request key mapping immediately after response processing (success or failure).
+- All crypto operations must be asynchronous and non-blocking.
+- SSL pinning recommended for high-security environments (pin current + backup fingerprints).
+- On `KEY_ID_NOT_FOUND`: refresh RSA key and retry exactly once. No retry loop.
+
+### Additional Constraints — Native Mode Only
+
+- Per-request AES keys are ephemeral: generated in JS, passed to native as parameters, and discarded after response. They are **never stored in Android Keystore or iOS Secure Enclave**.
+- Android Keystore is for persistent long-lived keys, not per-request ephemeral keys.
+- Native modules must be registered in `MainApplication.java` / `MainApplication.kt` (Android) and the Xcode `.m` bridge file (iOS) before the first encrypted request.
+- Validate that `NativeModules.NativeCryptoModule` is accessible from JS at startup.
+
+---
+
+## Backend Integration
+
+For the full specification the backend team must implement, see `references/backend-alignment.md`.
+
+---
+
+## Model B: EC — ECDH + HKDF-SHA256 (Key Derivation, Approach 6)
+
+AES session key is derived via ECDH between a per-request ephemeral EC key pair (client) and the server's static EC public key. HKDF-SHA256 is applied to the shared secret to produce a 32-byte AES key. The derived key is **never transmitted** — only the 65-byte uncompressed ephemeral public key goes in the envelope.
+
+### Key Exchange Flow
+
+1. Client fetches server's static EC public key (base64, 65-byte uncompressed P-256 point) from API endpoint and caches it in memory.
+2. Per request: client generates a fresh ephemeral EC key pair (P-256).
+3. ECDH: `sharedSecret = ecdh.computeSecret(serverPublicKey)` → 32-byte shared secret.
+4. HKDF-SHA256: `aesKey = HKDF(IKM=sharedSecret, salt=nonceBytes, info='enc')` → 32 bytes.
+5. AES-256-GCM: encrypt payload with `aesKey` and fresh 12-byte IV.
+6. Ephemeral public key and ciphertext go into the envelope. Ephemeral private key is discarded.
+7. `aesKey` is stored in the in-memory request map for response decryption, then cleared immediately after.
+
+### Request Envelope (EC)
+
+```json
+{
+  "data":                 "base64(ciphertext+tag)",
+  "ephemeral_public_key": "base64(65-byte uncompressed P-256 ephemeral public key)",
+  "iv":                   "base64(12-byte IV)",
+  "nonce":                "appId^timestamp_ms.random_hex",
+  "key_id":               "v1"
+}
+```
+
+Note: **no `key` field** — the AES key is derived by both sides independently via ECDH+HKDF.
+
+### EC Key Service
+
+- `ec-key.service.ts` — mirrors `RsaKeyService`. Fetches server's static EC public key from `/api/security/ec-public-key`. Validates decoded length is 65 bytes and first byte is `0x04`. Caches in memory. Retries with bounded policy.
+- On `KEY_ID_NOT_FOUND` (401): refresh EC key and retry the original request exactly once.
+
+### EC Crypto Utility
+
+```
+ec-crypto.util.ts
+  — Helpers (exported) —
+  toBase64()             — Hermes-safe base64 encoder (btoa-based); use everywhere instead of Buffer.toString('base64')
+  toBuffer()             — Convert quick-crypto output to standard Buffer
+  byteCopy()             — Copy Buffer slice into fresh Uint8Array before passing to quick-crypto native code
+  urlSafeBase64ToStd()   — Normalize base64url → standard base64 with padding
+
+  — Per-request EC —
+  ecEncryptPayload()     — ECDH + HKDF-SHA256 + AES-256-GCM; returns envelope + RequestCryptoMaterial
+  ecDecryptResponse()    — Decrypt server response using stored AES key + nonce-as-IV
+  ecDeriveKey()          — ECDH + HKDF-SHA256 only (for EC + Native mode; no AES)
+  hkdfSha256()           — HKDF-Extract + single-block HKDF-Expand using HMAC-SHA256
+
+  — Session-init EC —
+  deriveSessionKey()     — ECDH + HKDF with backend-specific info string; called once after session init
+  buildSessionAad()      — Build canonical JSON AAD buffer with alphabetically sorted keys
+  sessionEncrypt()       — AES-256-GCM encrypt using session key + nonce-as-IV + AAD
+  sessionDecrypt()       — AES-256-GCM decrypt with strategy probe (hardcode once confirmed)
+```
+
+### EC Native Mode
+
+- **No new native modules required** if `NativeCryptoModule` already exists.
+- ECDH + HKDF-SHA256 run in JS (`react-native-quick-crypto`) to produce `derivedAesKeyBase64`.
+- `derivedAesKeyBase64` is passed into existing `nativeEncryptAES` / `nativeDecryptAES` as the key parameter.
+- The interceptor calls `ecDeriveKey()` in JS first, then calls `nativeEncryptAES` with the derived key.
+- `ENCRYPTION_LAYER=native` + `ENCRYPTION_MODEL=ec` env flags route to this path.
+
+---
+
+## HMAC Request Signing (When Enabled)
+
+When `HMAC_ENABLED=true`, sign each request **after** the encrypted envelope is built. The HMAC secret comes from the env (`ENCRYPTION_HMAC_SECRET`) — never hardcoded.
+
+### Canonical String Format
+
+```
+METHOD|url|nonce|keyId|data|iv|key
+```
+
+Where `key` is the RSA-wrapped AES key field (RSA mode) or an **empty string** for EC mode (no `key` field). The trailing separator IS included in EC mode: `METHOD|url|nonce|keyId|data|iv|`. Both the client and the backend MUST use this same canonical string format including the trailing `|` when no `key` field exists, otherwise HMAC verification will always fail for EC mode.