devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/react-native-crypto.md

@@ -0,0 +1,1001 @@
+# Platform: React Native
+
+## Overview
+
+React Native supports six encryption approaches:
+
+| Approach | Mode | Crypto | Libraries |
+|----------|------|--------|-----------|
+| 2 | Basic RSA+AES-CBC | jsencrypt + crypto-js | axios, jsencrypt, crypto-js, react-native-get-random-values |
+| 3 | Basic AES-CBC shared key | crypto-js | axios, crypto-js, react-native-get-random-values |
+| 4 | **Production JS** | AES-256-GCM + RSA-OAEP, per-request ephemeral keys, response decryption, keychain | react-native-quick-crypto, react-native-keychain |
+| 5 | **Production Native** | OS-level crypto (javax.crypto.Cipher / CryptoKit) + RSA-OAEP, same JS interceptor shape | react-native-aes-crypto, react-native-rsa-native, react-native-keychain |
+| 6 | **EC (ECDH+AES-256-GCM)** | ECDH key exchange (P-256) + HKDF-SHA256 + AES-256-GCM; per-request or session-init; EC + Native variant reuses NativeCryptoModule for AES | react-native-quick-crypto (createECDH, randomBytes), react-native-keychain, buffer |
+
+> **Approach 1 (Web Crypto API) is NOT supported** — `crypto.subtle` is absent from the React Native JS runtime.
+
+Approaches 2 and 3 are suitable for low-to-moderate sensitivity APIs or prototypes.
+**Approaches 4, 5, and 6 are required for production apps** handling PII, financial data, or any sensitive user information.
+
+**Approach 6 (EC)** provides forward secrecy: each request uses an ephemeral P-256 key pair. The derived AES key is never transmitted. See `references/ec-implementation.md` for full implementation details including Hermes Buffer compatibility helpers (`toBase64`, `byteCopy`, `QCBuffer`), HKDF-SHA256, and session-init variant code.
+
+---
+
+## Approaches 2 & 3 — Basic (AES-CBC)
+
+### File Naming Convention
+
+| Role          | Path                                      |
+|---------------|-------------------------------------------|
+| Config        | `src/encryption/encryption.config.ts`     |
+| Service       | `src/encryption/encryption.service.ts`    |
+| Interceptor   | `src/encryption/encryption.interceptor.ts`|
+| Module wiring | `src/api/axiosInstance.ts`                |
+
+### Module Wiring
+
+Import `react-native-get-random-values` at the very top of `index.js` (app entry point) — this must happen before any crypto-js import.
+
+```ts
+// index.js
+import 'react-native-get-random-values'; // MUST be first import
+import { AppRegistry } from 'react-native';
+import App from './App';
+import { name as appName } from './app.json';
+AppRegistry.registerComponent(appName, () => App);
+```
+
+```ts
+// src/api/axiosInstance.ts
+import axios from 'axios';
+import { applyEncryptionInterceptor } from '../encryption/encryption.interceptor';
+const axiosInstance = axios.create({});
+applyEncryptionInterceptor(axiosInstance);
+// ENCRYPTION_INTERCEPTOR_PLACEHOLDER
+export default axiosInstance;
+```
+
+### Interceptor Pattern (Approaches 2 & 3)
+
+```ts
+import { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { EncryptionService } from './encryption.service';
+import { encryptionConfig } from './encryption.config';
+
+const encryptionService = new EncryptionService();
+
+export function applyEncryptionInterceptor(instance: AxiosInstance): void {
+  const cfg = encryptionConfig.encryption;
+  instance.interceptors.request.use(
+    async (config: InternalAxiosRequestConfig) => {
+      if (!cfg.enabled)                   return config;
+      if (!config.data)                   return config;
+      if (config.data instanceof FormData) return config;
+      if (cfg.excludeUrls?.some((u: string) => config.url?.startsWith(u))) return config;
+      try {
+        config.data = await encryptionService.encrypt(config.data);
+        config.headers['Content-Type'] = 'application/json';
+      } catch {}
+      return config;
+    },
+    (error: unknown) => Promise.reject(error)
+  );
+}
+```
+
+### Dependencies (Approaches 2 & 3)
+
+```bash
+npm install axios jsencrypt crypto-js react-native-get-random-values
+npm install --save-dev @types/crypto-js
+npx pod-install  # bare React Native only
+```
+
+---
+
+## Approach 4 — Production React Native JS Mode (AES-256-GCM)
+
+### Architecture
+
+- AES-256-GCM with 32-byte per-request ephemeral key, 12-byte IV, 16-byte auth tag
+- RSA-OAEP (SHA-256) key wrapping — server's public key fetched from API at startup
+- Per-request in-memory key map (`requestId → { aesKey, iv }`) — cleared immediately after response
+- Response decryption using the same per-request AES key with a fresh server-generated IV
+- Secure token storage via `react-native-keychain`
+- Feature flag: `ENCRYPTION_ENABLED`
+
+### File Naming Convention
+
+| Role                   | Path                                          |
+|------------------------|-----------------------------------------------|
+| Types                  | `src/services/security/types.ts`              |
+| Encryption service     | `src/services/security/encryption.service.ts` |
+| Decryption service     | `src/services/security/decryption.service.ts` |
+| RSA key service        | `src/services/security/rsa-key.service.ts`    |
+| Keychain storage       | `src/services/security/keychain.service.ts`   |
+| HMAC service           | `src/services/security/hmac.service.ts`       |
+| Encryption config      | `src/services/security/encryption-config.ts`  |
+| Request interceptor    | `src/services/security/encryption.interceptor.ts` |
+| Module wiring          | `src/api/axiosInstance.ts`                    |
+
+### TypeScript Envelope Types
+
+```ts
+// src/services/security/types.ts
+export interface EncryptedEnvelope {
+  data: string;    // base64(ciphertext + 16-byte GCM auth_tag)
+  key: string;     // base64(RSA-OAEP encrypted AES key bytes)
+  iv: string;      // base64(12-byte IV)
+  nonce: string;   // appId^unix_timestamp_ms.random_hex_16
+  key_id: string;  // RSA key version identifier from key endpoint
+}
+
+export interface EncryptedResponse {
+  data: string;    // base64(ciphertext + 16-byte GCM auth_tag)
+  iv: string;      // base64(new server-generated 12-byte IV — never the request IV)
+  nonce?: string;  // optional server nonce
+}
+```
+
+### Encryption Service (Approach 4)
+
+```ts
+// src/services/security/encryption.service.ts
+import { randomBytes, createCipheriv } from 'react-native-quick-crypto';
+
+export const encryptPayload = async (
+  plaintext: string,
+  rsaPublicKeyPem: string
+): Promise<{ ciphertext: string; aesKey: Buffer; iv: Buffer }> => {
+  const aesKey = randomBytes(32);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', aesKey, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = (cipher as any).getAuthTag() as Buffer;
+  const ciphertext = Buffer.concat([encrypted, tag]).toString('base64');
+  return { ciphertext, aesKey, iv };
+};
+```
+
+### RSA Key Service (Approach 4)
+
+```ts
+// src/services/security/rsa-key.service.ts
+import axios from 'axios';
+
+let cachedPublicKey: string | null = null;
+let cachedKeyId: string | null = null;
+const MAX_RETRIES = 3;
+
+export const getRsaPublicKey = async (
+  endpoint: string
+): Promise<{ publicKey: string; keyId: string }> => {
+  if (cachedPublicKey && cachedKeyId) return { publicKey: cachedPublicKey, keyId: cachedKeyId };
+  let lastError: Error | null = null;
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const { data } = await axios.get(endpoint);
+      cachedPublicKey = data.public_key;
+      cachedKeyId = data.key_id;
+      return { publicKey: data.public_key, keyId: data.key_id };
+    } catch (e: any) {
+      lastError = e;
+    }
+  }
+  throw new Error(`RSA key fetch failed after ${MAX_RETRIES} attempts: ${lastError?.message}`);
+};
+
+export const invalidateRsaKey = () => {
+  cachedPublicKey = null;
+  cachedKeyId = null;
+};
+```
+
+### Decryption Service (Approach 4)
+
+```ts
+// src/services/security/decryption.service.ts
+import { createDecipheriv } from 'react-native-quick-crypto';
+
+export const decryptResponse = (
+  ciphertextBase64: string,
+  ivBase64: string,
+  aesKey: Buffer
+): string => {
+  const combined = Buffer.from(ciphertextBase64, 'base64');
+  const tag = combined.slice(combined.length - 16);
+  const ciphertext = combined.slice(0, combined.length - 16);
+  const iv = Buffer.from(ivBase64, 'base64');
+  const decipher = createDecipheriv('aes-256-gcm', aesKey, iv);
+  (decipher as any).setAuthTag(tag);
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return decrypted.toString('utf8');
+};
+```
+
+### Keychain Storage Service (Approach 4)
+
+```ts
+// src/services/security/keychain.service.ts
+import * as Keychain from 'react-native-keychain';
+
+export const storeToken = async (key: string, value: string): Promise<void> => {
+  await Keychain.setGenericPassword(key, value, { service: key });
+};
+
+export const getToken = async (key: string): Promise<string | null> => {
+  const result = await Keychain.getGenericPassword({ service: key });
+  return result ? result.password : null;
+};
+
+export const deleteToken = async (key: string): Promise<void> => {
+  await Keychain.resetGenericPassword({ service: key });
+};
+```
+
+### HMAC Service (Approach 4 — when enabled)
+
+```ts
+// src/services/security/hmac.service.ts
+import { createHmac } from 'react-native-quick-crypto';
+
+export const buildCanonicalString = (
+  method: string,
+  url: string,
+  nonce: string,
+  encryptedData: string
+): string => `${method.toUpperCase()}|${url}|${nonce}|${encryptedData}`;
+
+export const signRequest = (canonical: string, hmacSecret: string): string => {
+  if (!hmacSecret) throw new Error('HMAC_SECRET is not configured');
+  const hmac = createHmac('sha256', hmacSecret);
+  hmac.update(canonical);
+  return hmac.digest('base64');
+};
+```
+
+### Encryption Config (Approach 4)
+
+```ts
+// src/services/security/encryption-config.ts
+export const EXCLUDED_PATHS: string[] = [];
+// Add paths that must NOT be encrypted, e.g. '/api/health', '/api/auth/register'
+
+export const ENCRYPTION_ENABLED = process.env.ENCRYPTION_ENABLED === 'true';
+export const RSA_KEY_ENDPOINT = process.env.RSA_KEY_ENDPOINT ?? '<API_BASE_URL>/api/security/public-key';
+export const HMAC_ENABLED = process.env.HMAC_ENABLED === 'true';
+export const HMAC_SECRET = process.env.HMAC_SECRET ?? '';
+```
+
+### Request + Response Interceptors (Approach 4)
+
+```ts
+// src/services/security/encryption.interceptor.ts
+import axios, { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse } from 'axios';
+import { randomBytes, publicEncrypt } from 'react-native-quick-crypto';
+import { encryptPayload } from './encryption.service';
+import { decryptResponse } from './decryption.service';
+import { getRsaPublicKey, invalidateRsaKey } from './rsa-key.service';
+import { buildCanonicalString, signRequest } from './hmac.service';
+import { ENCRYPTION_ENABLED, EXCLUDED_PATHS, RSA_KEY_ENDPOINT, HMAC_ENABLED, HMAC_SECRET } from './encryption-config';
+
+// In-memory request map: requestId → { aesKey, iv }
+const requestMap = new Map<string, { aesKey: Buffer; iv: Buffer }>();
+
+export function applyProductionEncryptionInterceptor(instance: AxiosInstance): void {
+  // ── Request interceptor ──────────────────────────────────────────────────────
+  instance.interceptors.request.use(
+    async (config: InternalAxiosRequestConfig) => {
+      if (!ENCRYPTION_ENABLED) return config;
+      if (!config.data) return config;
+      if (config.data instanceof FormData) return config;
+      if (EXCLUDED_PATHS.some(p => config.url?.includes(p))) return config;
+      const method = (config.method ?? '').toUpperCase();
+      if (!['POST', 'PUT', 'PATCH'].includes(method)) return config;
+
+      try {
+        const { publicKey, keyId } = await getRsaPublicKey(RSA_KEY_ENDPOINT);
+        const plaintext = typeof config.data === 'string' ? config.data : JSON.stringify(config.data);
+        const { ciphertext, aesKey, iv } = await encryptPayload(plaintext, publicKey);
+
+        // RSA-OAEP wrap the AES key
+        const encryptedKey = publicEncrypt({ key: publicKey, padding: 4 /* RSA_PKCS1_OAEP_PADDING */ }, aesKey).toString('base64');
+
+        const requestId = randomBytes(16).toString('hex');
+        const nonce = `${(config as any).appId ?? 'app'}^${Date.now()}.${randomBytes(8).toString('hex')}`;
+
+        requestMap.set(requestId, { aesKey, iv });
+        (config as any).__requestId = requestId;
+
+        config.data = { data: ciphertext, key: encryptedKey, iv: iv.toString('base64'), nonce, key_id: keyId };
+        config.headers['Content-Type'] = 'application/json';
+        config.headers['X-Request-Id'] = requestId;
+
+        if (HMAC_ENABLED) {
+          const canonical = buildCanonicalString(method, config.url ?? '', nonce, ciphertext);
+          const signature = signRequest(canonical, HMAC_SECRET);
+          config.headers['X-Request-Signature'] = signature;
+          config.headers['X-Nonce'] = nonce;
+        }
+      } catch (err: any) {
+        // Never block the request; log at debug only
+        if (__DEV__) console.debug('[EncryptionInterceptor] encrypt error:', err?.message);
+      }
+      return config;
+    },
+    (error: unknown) => Promise.reject(error)
+  );
+
+  // ── Response interceptor ─────────────────────────────────────────────────────
+  instance.interceptors.response.use(
+    (response: AxiosResponse) => {
+      const requestId = (response.config as any).__requestId;
+      if (!requestId || !requestMap.has(requestId)) return response;
+      const { aesKey } = requestMap.get(requestId)!;
+      requestMap.delete(requestId); // always clean up
+
+      try {
+        const encResp = response.data;
+        if (encResp?.data && encResp?.iv) {
+          response.data = JSON.parse(decryptResponse(encResp.data, encResp.iv, aesKey));
+        }
+      } catch (err: any) {
+        // Auth tag mismatch or tamper — trigger session reset
+        if (__DEV__) console.debug('[EncryptionInterceptor] decrypt error:', err?.message);
+        // Caller should handle session reset based on error type
+        throw Object.assign(new Error('DECRYPTION_AUTH_TAG_FAILURE'), { isAuthTagFailure: true });
+      }
+      return response;
+    },
+    async (error: any) => {
+      const requestId = error?.config?.__requestId;
+      if (requestId) requestMap.delete(requestId); // always clean up
+
+      // KEY_ID_NOT_FOUND: refresh key and retry exactly once
+      if (error?.response?.status === 401 && error?.response?.data?.code === 'KEY_ID_NOT_FOUND') {
+        invalidateRsaKey();
+        return instance.request(error.config);
+      }
+      return Promise.reject(error);
+    }
+  );
+}
+```
+
+### Dependencies (Approach 4)
+
+```bash
+npm install react-native-quick-crypto react-native-keychain
+# RSA library — choose one compatible with your RN version:
+# npm install react-native-rsa-native   (for RSA-OAEP support)
+npx pod-install  # bare React Native
+```
+
+**Install rules:**
+- Prefer pinning exact versions in production environments.
+- Validate iOS pod install and Android Gradle sync after install.
+- Confirm crypto methods available at runtime before shipping.
+
+---
+
+## Approach 5 — Production Native Mode (OS-level crypto)
+
+All of approach 4 applies. The only difference is the crypto backend:
+- AES-256-GCM and RSA-OAEP operations run inside `javax.crypto.Cipher` (Android) and CryptoKit (iOS).
+- Per-request AES keys are **generated in JS** using `randomBytes(32)` and **passed as parameters** into native calls — they are never stored in Android Keystore or iOS Secure Enclave.
+
+### Additional Files (beyond approach 4)
+
+| Role                  | Path                                                                       |
+|-----------------------|----------------------------------------------------------------------------|
+| Android module        | `android/app/src/main/java/.../NativeCryptoModule.kt`                      |
+| Android package       | `android/app/src/main/java/.../NativeCryptoPackage.kt`                     |
+| iOS module            | `ios/NativeCryptoModule.swift`                                             |
+| iOS bridge            | `ios/NativeCryptoModule.m`                                                 |
+| JS bridge interface   | `src/services/security/native-crypto.module.ts`                            |
+
+### NativeCryptoModule.kt (Android)
+
+```kotlin
+package com.example.security
+
+import android.util.Base64
+import com.facebook.react.bridge.*
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+import java.security.KeyFactory
+import java.security.spec.X509EncodedKeySpec
+
+class NativeCryptoModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+  override fun getName() = "NativeCryptoModule"
+
+  @ReactMethod
+  fun encryptAES(plaintext: String, keyBase64: String, promise: Promise) {
+    try {
+      val keyBytes = Base64.decode(keyBase64, Base64.NO_WRAP)
+      require(keyBytes.size == 32) { "AES key must be 32 bytes" }
+      val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+      cipher.init(Cipher.ENCRYPT_MODE, SecretKeySpec(keyBytes, "AES"))
+      val cipherWithTag = cipher.doFinal(plaintext.toByteArray(Charsets.UTF_8))
+      val result = WritableNativeMap().apply {
+        putString("ciphertext", Base64.encodeToString(cipherWithTag, Base64.NO_WRAP))
+        putString("iv", Base64.encodeToString(cipher.iv, Base64.NO_WRAP))
+      }
+      promise.resolve(result)
+    } catch (e: Exception) { promise.reject("ERR_ENCRYPT", e.message, e) }
+  }
+
+  @ReactMethod
+  fun decryptAES(ciphertextBase64: String, ivBase64: String, keyBase64: String, promise: Promise) {
+    try {
+      val keyBytes = Base64.decode(keyBase64, Base64.NO_WRAP)
+      require(keyBytes.size == 32) { "AES key must be 32 bytes" }
+      val cipherWithTag = Base64.decode(ciphertextBase64, Base64.NO_WRAP)
+      val iv = Base64.decode(ivBase64, Base64.NO_WRAP)
+      val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+      cipher.init(Cipher.DECRYPT_MODE, SecretKeySpec(keyBytes, "AES"), GCMParameterSpec(128, iv))
+      promise.resolve(String(cipher.doFinal(cipherWithTag), Charsets.UTF_8))
+    } catch (e: Exception) { promise.reject("ERR_DECRYPT", e.message, e) }
+  }
+
+  @ReactMethod
+  fun encryptRSA(publicKeyPem: String, dataBase64: String, promise: Promise) {
+    try {
+      val pem = publicKeyPem.replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "").replace("\n", "").trim()
+      val pubKey = KeyFactory.getInstance("RSA").generatePublic(X509EncodedKeySpec(Base64.decode(pem, Base64.NO_WRAP)))
+      val cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")
+      cipher.init(Cipher.ENCRYPT_MODE, pubKey)
+      promise.resolve(Base64.encodeToString(cipher.doFinal(Base64.decode(dataBase64, Base64.NO_WRAP)), Base64.NO_WRAP))
+    } catch (e: Exception) { promise.reject("ERR_RSA_ENCRYPT", e.message, e) }
+  }
+}
+```
+
+### NativeCryptoPackage.kt (Android)
+
+```kotlin
+package com.example.security
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class NativeCryptoPackage : ReactPackage {
+  override fun createNativeModules(ctx: ReactApplicationContext): List<NativeModule> =
+    listOf(NativeCryptoModule(ctx))
+  override fun createViewManagers(ctx: ReactApplicationContext): List<ViewManager<*, *>> = emptyList()
+}
+```
+
+> Register `NativeCryptoPackage` in `MainApplication.kt` / `MainApplication.java` `getPackages()`.
+
+### NativeCryptoModule.swift (iOS)
+
+```swift
+// NativeCryptoModule.swift
+import CryptoKit
+import Foundation
+
+@objc(NativeCryptoModule)
+class NativeCryptoModule: NSObject {
+
+  @objc func encryptAES(_ plaintext: String, keyBase64: String,
+    resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      guard let data = plaintext.data(using: .utf8),
+            let keyData = Data(base64Encoded: keyBase64), keyData.count == 32 else {
+        return reject("ERR_INVALID_INPUT", "Invalid plaintext or key", nil)
+      }
+      let key = SymmetricKey(data: keyData)
+      let nonce = try AES.GCM.Nonce()
+      let sealed = try AES.GCM.seal(data, using: key, nonce: nonce)
+      resolve(["ciphertext": (sealed.ciphertext + sealed.tag).base64EncodedString(),
+               "iv": Data(nonce).base64EncodedString()])
+    } catch { reject("ERR_ENCRYPT", error.localizedDescription, error) }
+  }
+
+  @objc func decryptAES(_ ciphertextBase64: String, ivBase64: String, keyBase64: String,
+    resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      guard let combined = Data(base64Encoded: ciphertextBase64),
+            let ivData = Data(base64Encoded: ivBase64),
+            let keyData = Data(base64Encoded: keyBase64),
+            keyData.count == 32, combined.count > 16 else {
+        return reject("ERR_INVALID_INPUT", "Invalid inputs", nil)
+      }
+      let key = SymmetricKey(data: keyData)
+      let nonce = try AES.GCM.Nonce(data: ivData)
+      let box = try AES.GCM.SealedBox(nonce: nonce, ciphertext: combined.dropLast(16), tag: combined.suffix(16))
+      guard let plain = String(data: try AES.GCM.open(box, using: key), encoding: .utf8) else {
+        return reject("ERR_DECODE", "UTF-8 decode failed", nil)
+      }
+      resolve(plain)
+    } catch { reject("ERR_DECRYPT", error.localizedDescription, error) }
+  }
+
+  @objc func encryptRSA(_ publicKeyPEM: String, dataBase64: String,
+    resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    guard let data = Data(base64Encoded: dataBase64) else {
+      return reject("ERR_INVALID_INPUT", "Invalid data", nil)
+    }
+    let pem = publicKeyPEM
+      .replacingOccurrences(of: "-----BEGIN PUBLIC KEY-----", with: "")
+      .replacingOccurrences(of: "-----END PUBLIC KEY-----", with: "")
+      .replacingOccurrences(of: "\n", with: "")
+    guard let keyData = Data(base64Encoded: pem),
+          let secKey = SecKeyCreateWithData(keyData as CFData,
+            [kSecAttrKeyType: kSecAttrKeyTypeRSA, kSecAttrKeyClass: kSecAttrKeyClassPublic] as CFDictionary, nil) else {
+      return reject("ERR_KEY_LOAD", "Failed to load RSA key", nil)
+    }
+    var error: Unmanaged<CFError>?
+    guard let encrypted = SecKeyCreateEncryptedData(secKey, .rsaEncryptionOAEPSHA256, data as CFData, &error) else {
+      return reject("ERR_RSA_ENCRYPT", error?.takeRetainedValue().localizedDescription ?? "RSA encrypt failed", nil)
+    }
+    resolve((encrypted as Data).base64EncodedString())
+  }
+}
+```
+
+### NativeCryptoModule.m (iOS bridge)
+
+```objc
+// NativeCryptoModule.m
+#import <React/RCTBridgeModule.h>
+@interface RCT_EXTERN_MODULE(NativeCryptoModule, NSObject)
+RCT_EXTERN_METHOD(encryptAES:(NSString *)plaintext keyBase64:(NSString *)keyBase64 resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(decryptAES:(NSString *)ciphertextBase64 ivBase64:(NSString *)ivBase64 keyBase64:(NSString *)keyBase64 resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(encryptRSA:(NSString *)publicKeyPEM dataBase64:(NSString *)dataBase64 resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+@end
+```
+
+### JS Bridge Interface (Approach 5)
+
+```ts
+// src/services/security/native-crypto.module.ts
+import { NativeModules } from 'react-native';
+const { NativeCryptoModule } = NativeModules;
+
+if (!NativeCryptoModule) {
+  throw new Error('[NativeCryptoModule] Native module not registered. Verify MainApplication and Xcode wiring.');
+}
+
+export const nativeEncryptAES = (plaintext: string, keyBase64: string): Promise<{ ciphertext: string; iv: string }> =>
+  NativeCryptoModule.encryptAES(plaintext, keyBase64);
+
+export const nativeDecryptAES = (ciphertextBase64: string, ivBase64: string, keyBase64: string): Promise<string> =>
+  NativeCryptoModule.decryptAES(ciphertextBase64, ivBase64, keyBase64);
+
+export const nativeEncryptRSA = (publicKeyPEM: string, dataBase64: string): Promise<string> =>
+  NativeCryptoModule.encryptRSA(publicKeyPEM, dataBase64);
+```
+
+### Feature Flags (Approach 5)
+
+```
+ENCRYPTION_ENABLED=true
+ENCRYPTION_LAYER=native   # rn = JS mode (approach 4), native = OS-level (approach 5)
+```
+
+> The interceptor reads `ENCRYPTION_LAYER` at startup to choose the JS or native crypto path. This allows toggling between modes without a code change.
+
+**Security architecture note:** All crypto is asynchronous and non-blocking. SSL pinning is recommended for high-security environments — pin both the current and a backup certificate fingerprint to prevent MITM during certificate rotation.
+
+### Dependencies (Approach 5)
+
+```bash
+npm install react-native-aes-crypto react-native-rsa-native react-native-keychain
+npx pod-install
+# Android: verify minSdkVersion >= 23 in android/app/build.gradle
+# iOS: verify deployment target >= 13.0 in ios/Podfile
+```
+
+**iOS CommonCrypto fallback (if deployment target < 13.0):**
+
+If the iOS deployment target is below 13.0, CryptoKit is unavailable. Use `CommonCrypto` instead:
+- AES-256-GCM via `CCCryptorGCM` (`kCCAlgorithmAES`, `kCCModeGCM`)
+- RSA-OAEP via `SecKeyCreateEncryptedData` with `.rsaEncryptionOAEPSHA256` (available since iOS 11)
+
+Update the `NativeCryptoModule.swift` to detect OS version at runtime:
+```swift
+if #available(iOS 13.0, *) {
+    // CryptoKit path
+} else {
+    // CommonCrypto path using CCCryptorGCM
+}
+```
+
+> Prefer raising the deployment target to >= 13.0 for new projects. CommonCrypto is only for legacy app maintenance.
+
+**Install rules:**
+- Prefer pinning exact versions in production environments.
+- Validate iOS pod install and Android Gradle sync after install.
+- Confirm native modules appear in `NativeModules` in JS.
+- Confirm AES encrypt + decrypt round-trip produces correct plaintext on both platforms before shipping.
+
+---
+
+## Request Envelope (Approaches 4 & 5 — Identical Shape)
+
+```json
+{
+  "data":    "base64(ciphertext + 16-byte auth_tag)",
+  "key":     "base64(RSA-OAEP encrypted 32-byte AES key)",
+  "iv":      "base64(12-byte IV)",
+  "nonce":   "appId^unix_timestamp_ms.random_hex_16",
+  "key_id":  "v1"
+}
+```
+
+## Backend Alignment (Approaches 4 & 5)
+
+**Purpose:** This section is written for the backend team. It defines the exact contract the server must implement.
+
+### RSA Public Key Endpoint
+
+```
+GET /api/security/public-key
+Authorization: Bearer <access_token>   (if route is authenticated)
+```
+
+**Response — 200 OK:**
+
+```json
+{
+  "public_key": "<PEM or Base64-encoded DER RSA public key>",
+  "key_id": "v1",
+  "expires_at": "2026-07-01T00:00:00Z"
+}
+```
+
+| Field        | Type   | Required | Description                                                  |
+|--------------|--------|----------|--------------------------------------------------------------|
+| `public_key` | string | yes      | PEM (`-----BEGIN PUBLIC KEY-----…`) preferred; or Base64 DER |
+| `key_id`     | string | yes      | Version tag used for key rotation tracking                   |
+| `expires_at` | string | no       | ISO 8601 UTC. Client may use to schedule proactive key refresh. |
+
+- PEM is preferred (self-describing).
+- The key must be a **public key** (`BEGIN PUBLIC KEY`), not a certificate (`BEGIN CERTIFICATE`).
+
+The client retries with exponential back-off (default 3 attempts). If unavailable, the client **blocks all encrypted calls** and surfaces an error.
+
+### Crypto Parameters (Non-Negotiable)
+
+| Parameter        | Required Value              | Notes                                            |
+|------------------|-----------------------------|--------------------------------------------------|
+| Symmetric cipher | AES-256-GCM                 | 256-bit key, authenticated mode                  |
+| AES key size     | 32 bytes                    | Generated fresh per request on the client        |
+| IV/Nonce size    | 12 bytes                    | Generated fresh per request, never reused        |
+| Auth tag size    | 16 bytes (128 bits)         | Appended to ciphertext                           |
+| Asymmetric       | RSA-OAEP SHA-256 (mandatory)| PKCS1 v1.5 only for legacy with written approval — **not acceptable for new deployments in 2026** |
+| RSA key size     | >= 2048 bits                | 4096 bits recommended for new deployments        |
+| Encoding         | Base64 (no line breaks)     |                                                  |
+
+> Do not negotiate algorithm parameters at runtime. Mismatches cause auth tag failures.
+
+### Encrypted Request Contract
+
+Every POST / PUT / PATCH body the client sends replaces the original payload with:
+
+```json
+{
+  "data":   "<Base64(ciphertext + auth_tag)>",
+  "key":    "<Base64(RSA-OAEP encrypted AES key)>",
+  "iv":     "<Base64(12-byte IV)>",
+  "nonce":  "<appId>^<unix_timestamp_ms>.<random_hex_16>",
+  "key_id": "v1"
+}
+```
+
+| Field    | Type   | Description                                                              |
+|----------|--------|--------------------------------------------------------------------------|
+| `data`   | string | Base64 of AES-256-GCM(plaintext_json). Last 16 bytes are the auth tag — appended automatically by AES-GCM. |
+| `key`    | string | Base64 of RSA-OAEP(aes_key_bytes). Encrypted with the public key from the key endpoint. |
+| `iv`     | string | Base64 of the 12-byte IV used for AES-GCM. Must be passed to decryption step. |
+| `nonce`  | string | Anti-replay identifier. Format: `<appId>^<epoch_ms>.<16-char random hex>`. |
+| `key_id` | string | Identifies which RSA key pair to use for unwrapping. Must match the `key_id` from public key endpoint. |
+
+Client sends `Content-Type: application/json` — the envelope is valid JSON.
+
+### Backend Decryption Steps
+
+```
+1. Read key_id → select matching RSA private key from secure storage.
+2. Base64-decode key → RSA-OAEP-decrypt (SHA-256) → 32-byte AES key.
+3. Base64-decode iv → 12-byte IV.
+4. Base64-decode data → ciphertext+tag (last 16 bytes = auth tag; remaining = ciphertext).
+5. AES-256-GCM decrypt(key, iv, ciphertext, tag) → if auth tag FAILS → return 400.
+6. Parse UTF-8 JSON → original request payload.
+7. Validate nonce (anti-replay — see below).
+8. Process business logic with the original payload.
+```
+
+### Nonce / Anti-Replay Validation
+
+Format: `<appId>^<unix_timestamp_ms>.<16-char random hex>`
+
+Example: `com.myapp^1745189241337.a3f9c2e1d8b047f6`
+
+Backend validation rules:
+1. Parse: split on `^`, then split the right side on `.`.
+2. Timestamp check: reject if `|server_time_ms - timestamp_ms| > 300000` (5-minute window, configurable).
+3. Nonce store: reject if the exact nonce value has been seen before within the window (prevents replay).
+
+### Encrypted Response Contract
+
+The server MUST use the **same AES key** from the request (the client stores it in memory keyed by `requestId`) and a **freshly generated IV** (not the request IV):
+
+```json
+{
+  "data":  "base64(ciphertext + auth_tag)",
+  "iv":    "base64(NEW server-generated 12-byte IV)",
+  "nonce": "server_nonce"
+}
+```
+
+**Step-by-step server-side response encryption:**
+```
+1. Retrieve the AES key that was decrypted from the incoming request.
+2. Generate a new cryptographically random 12-byte IV (never reuse the request IV).
+3. Serialize response JSON to UTF-8 bytes.
+4. Encrypt with AES-256-GCM(aes_key, new_iv, response_bytes) → ciphertext + auth_tag.
+5. Return { data: base64(ciphertext || auth_tag), iv: base64(new_iv), nonce: server_nonce }.
+```
+
+> **Critical:** Reusing the request IV with the same AES key is a security violation.
+
+---
+
+## Security Checklist (Approaches 4 & 5)
+
+### Crypto (Both Modes)
+- [ ] AES key: 32 bytes. IV: 12 bytes. Auth tag: 16 bytes.
+- [ ] AES mode is GCM — no other mode acceptable.
+- [ ] Random generation uses cryptographically secure `randomBytes` (JS) or OS-provided `SecRandomCopyBytes` / `KeyGenerator` (Native).
+- [ ] RSA padding: RSA-OAEP SHA-256. PKCS1 v1.5 only for legacy with written approval.
+
+### Key Handling (Both Modes)
+- [ ] RSA public key format validated (PEM/Base64 as expected).
+- [ ] RSA key source is HTTPS — never HTTP.
+- [ ] RSA key cached in memory only; retry bounded at 3.
+- [ ] AES key and IV are never persisted to disk or AsyncStorage.
+- [ ] Request key mapping cleared immediately after response processing (success or failure).
+- [ ] Block encrypted endpoints when RSA key is unavailable after retries.
+
+### Key Handling (Native Mode Only)
+- [ ] Per-request AES keys generated in JS using `randomBytes(32)` and passed as base64 to native calls — NOT stored in Android Keystore.
+- [ ] AES key lives only in the JS request map for one request/response cycle; deleted immediately after.
+- [ ] RSA public key fetched from API over HTTPS; cached in memory; not stored in Keystore.
+- [ ] No RSA private key exists on the client — private key resides on the server.
+
+### Transport and API (Both Modes)
+- [ ] Encryption applied to POST/PUT/PATCH by default.
+- [ ] GET excluded unless explicitly configured.
+- [ ] Request mapping safe under concurrent requests (each has its own `requestId`).
+- [ ] Request map entry deleted immediately after each response (success or failure).
+- [ ] Missing request map entry handled with secure fallback.
+- [ ] All crypto operations run asynchronously — never block the UI thread.
+- [ ] SSL pinning configured for high-security environments; current and backup certificate fingerprints pinned.
+
+### Native Module Wiring (Native Mode Only)
+- [ ] `NativeCryptoModule` registered in `MainApplication.java` / `MainApplication.kt` (Android).
+- [ ] `NativeCryptoModule` bridge `.m` file present and linked in Xcode project (iOS).
+- [ ] `pod install` completed successfully after adding native module.
+- [ ] `NativeModules.NativeCryptoModule` accessible from JS at runtime.
+- [ ] `encryptAES`, `decryptAES`, `encryptRSA` callable and return Promises from JS.
+- [ ] `ENCRYPTION_LAYER` env flag set and read correctly in interceptor setup.
+
+### Error Handling (Both Modes)
+- [ ] Invalid auth tag triggers session reset/force logout — not a silent fallback.
+- [ ] Decryption failure does not leak plaintext.
+- [ ] RSA key fetch retry is bounded (default 3).
+- [ ] KEY_ID_NOT_FOUND triggers key refresh and exactly one retry — no retry loop.
+- [ ] Sensitive fields excluded from logs (no keys, IVs, plaintext, auth tags).
+
+### Storage (Both Modes)
+- [ ] Tokens stored via `react-native-keychain`.
+- [ ] Sensitive persisted fields stored via keychain.
+- [ ] No secrets stored in plain `AsyncStorage`.
+
+### Environment (Both Modes)
+- [ ] `ENCRYPTION_ENABLED` supported.
+- [ ] `ENCRYPTION_LAYER` supported (values: `rn` / `native`).
+- [ ] Production default is secure (encryption enabled, no debug logging).
+- [ ] Development override is explicit and controlled.
+
+---
+
+## Error Handling (Approaches 4 & 5)
+
+| Error | Behavior |
+|-------|----------|
+| RSA key fetch failure | Retry up to 3 times; block encrypted calls if all fail |
+| KEY_ID_NOT_FOUND (401) | Invalidate cached key, retry request exactly once |
+| Auth tag mismatch | Trigger force logout / session reset |
+| Missing request map entry | Fail securely; do not retry |
+| Keychain unavailable | Treat as session-expired; force re-login; never fallback to AsyncStorage |
+| Native module undefined (approach 5) | Block all encrypted calls; surface clear setup error |
+| Native encrypt/decrypt rejection (approach 5) | Non-recoverable for that request; log error code only |
+| Decryption parse failure | Catch JSON parse exceptions after decryption; return sanitized error; never log plaintext payload |
+| AES key lifecycle mismatch | Symptom: decryption succeeds but produces garbage, or auth tag fails. Cause: different key used in encrypt vs decrypt, or request map cleared before response arrived. Resolution: ensure request map stores exact `aesKeyBase64` used in encryption and passes it unchanged into decryption; clear only after decryption completes |
+
+---
+
+## Build Command
+
+```bash
+npx react-native run-android
+# or for Expo:
+npx expo start
+```
+
+---
+
+## Delivery Checklist (Approaches 4 & 5)
+
+### Configuration
+- [ ] All configuration questions answered and validated.
+- [ ] Encryption layer selected and recorded (JS mode or Native).
+
+### Implementation — JS Mode (Approach 4)
+- [ ] Encryption module implemented (`react-native-quick-crypto`).
+- [ ] Decryption module implemented.
+- [ ] RSA key service implemented (fetch/cache/retry).
+- [ ] Request + response interceptors integrated.
+- [ ] Keychain storage integrated.
+- [ ] Feature flag wired.
+
+### Implementation — Native Mode (Approach 5, all of above plus)
+- [ ] Android `NativeCryptoModule.kt` created and registered in `NativeCryptoPackage.kt`.
+- [ ] `NativeCryptoPackage` registered in `MainApplication.java` / `MainApplication.kt`.
+- [ ] iOS `NativeCryptoModule.swift` created with `do/try/catch` — `try!` not present anywhere.
+- [ ] iOS bridge `NativeCryptoModule.m` created and added to Xcode project.
+- [ ] JS bridge interface `native-crypto.module.ts` created.
+- [ ] Interceptors updated to use native bridge calls.
+- [ ] AES key generated in JS, passed into native calls, not generated inside native module.
+- [ ] `ENCRYPTION_LAYER` env flag added and read in interceptor setup.
+- [ ] `pod install` completed (iOS).
+- [ ] Gradle sync completed (Android).
+- [ ] `NativeModules.NativeCryptoModule` confirmed accessible from JS at runtime.
+
+### Security
+- [ ] No sensitive logging (no keys, IVs, plaintext, tags in logs).
+- [ ] No persistent AES key/IV storage.
+- [ ] HTTPS enforced for RSA key endpoint and all API traffic.
+- [ ] Auth tag verification enforced; mismatch triggers session reset.
+- [ ] Native mode: AES key never written to native storage; exists only in JS request map.
+
+### Operational
+- [ ] Handles concurrent requests correctly (each has its own requestId).
+- [ ] Handles missing key / RSA key refetch flow.
+- [ ] Handles invalid auth tag → force logout flow.
+- [ ] Native mode: tested on physical Android device (not emulator-only).
+- [ ] Native mode: tested on physical iOS device (not simulator-only).
+
+### Final Output
+- [ ] Files changed listed (including native module files if applicable).
+- [ ] Dependency changes listed.
+- [ ] Backend alignment spec shared with server team.
+- [ ] Residual risks noted.
+- [ ] Suggested next validation steps included.
+
+| Role           | Path                                                  |
+|----------------|-------------------------------------------------------|
+| Config         | `src/encryption/encryption.config.ts`                 |
+| Service        | `src/encryption/encryption.service.ts`                |
+| Interceptor    | `src/encryption/encryption.interceptor.ts`            |
+| Module wiring  | `src/api/axiosInstance.ts`                            |
+
+---
+
+## Module Wiring
+
+Create a shared Axios instance in `src/api/axiosInstance.ts` and register the interceptor there.  
+Import `react-native-get-random-values` at the very top of `index.js` (app entry point) — this must happen before any crypto-js import.
+
+### `index.js` (entry point polyfill)
+
+```ts
+import 'react-native-get-random-values'; // MUST be first import
+import { AppRegistry } from 'react-native';
+import App from './App';
+import { name as appName } from './app.json';
+
+AppRegistry.registerComponent(appName, () => App);
+```
+
+### `src/api/axiosInstance.ts`
+
+```ts
+import axios from 'axios';
+import { applyEncryptionInterceptor } from '../encryption/encryption.interceptor';
+import { encryptionConfig } from '../encryption/encryption.config';
+
+const axiosInstance = axios.create({
+  baseURL: encryptionConfig.apiUrl,
+});
+
+applyEncryptionInterceptor(axiosInstance);
+// ENCRYPTION_INTERCEPTOR_PLACEHOLDER
+
+export default axiosInstance;
+```
+
+The `// ENCRYPTION_INTERCEPTOR_PLACEHOLDER` comment is the marker used by install.js `patchFile()`.
+
+---
+
+## Interceptor Pattern
+
+Identical to the React interceptor pattern — Axios request interceptor:
+
+```ts
+import { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { encryptionService } from './encryption.service';
+import { encryptionConfig } from './encryption.config';
+
+export function applyEncryptionInterceptor(instance: AxiosInstance): void {
+  const cfg = encryptionConfig.encryption;
+
+  instance.interceptors.request.use(
+    async (config: InternalAxiosRequestConfig) => {
+      if (!cfg.enabled)                                          return config;
+      if (!config.data)                                          return config;
+      if (config.data instanceof FormData)                       return config;
+      if (cfg.excludeUrls?.some(u => config.url?.startsWith(u))) return config;
+
+      try {
+        config.data = await encryptionService.encrypt(config.data);
+        config.headers['Content-Type'] = 'application/json';
+      } catch {}
+
+      return config;
+    },
+    (error) => Promise.reject(error)
+  );
+}
+```
+
+---
+
+## URL Exclusion Pattern
+
+```ts
+const excludeUrls: string[] = encryptionConfig.encryption.excludeUrls;
+if (excludeUrls.some(prefix => config.url?.startsWith(prefix))) {
+  return config;
+}
+```
+
+---
+
+## Dependencies (Approach 2 or 3)
+
+```bash
+npm install axios jsencrypt crypto-js react-native-get-random-values
+npm install --save-dev @types/crypto-js
+```
+
+`react-native-get-random-values` provides the `crypto.getRandomValues` polyfill required by `crypto-js` in the React Native JS runtime.  
+For bare React Native projects, also run:
+
+```bash
+npx pod-install
+```
+
+Approach 1 is NOT available — `crypto.subtle` is absent from the React Native JS runtime.
+
+---
+
+## Build Command
+
+```bash
+npx react-native run-android
+```
+
+For Expo-managed projects:
+
+```bash
+npx expo start
+```