devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/dependency-guidance.md

@@ -0,0 +1,234 @@
+# Dependency Guidance
+
+Applies to all platforms and approaches. Read this before proposing or running any package install.
+
+---
+
+## React Native — Approach 4 (Production JS Mode — RSA)
+
+### Required Libraries
+
+| Library | Purpose |
+|---------|---------|
+| `react-native-quick-crypto` | AES-256-GCM encrypt/decrypt, `randomBytes`, HMAC-SHA256 |
+| `buffer` | Hermes-safe `Buffer` API — use `buffer` (npm), NOT `@craftzdog/react-native-buffer` |
+| `react-native-keychain` | Secure token and sensitive data storage |
+| `react-native-get-random-values` | `crypto.getRandomValues` polyfill — must be first import in `index.js` |
+| `react-native-nitro-modules` | **REQUIRED peer dep** of quick-crypto >= 1.0 — must be installed explicitly |
+| `react-native-worklets` | **REQUIRED peer dep** of quick-crypto >= 1.0 — must be installed explicitly |
+
+> **Warning:** `@craftzdog/react-native-buffer` is the old package name. Use `buffer` (npm >= 6.0.0) instead. Both the `buffer` package `Buffer` and quick-crypto's own `Buffer` (imported as `QCBuffer`) are needed for EC mode — they are different classes.
+
+### RN Version Compatibility
+
+| Package | RN >= 0.76 (New Arch) | RN 0.70–0.75 | Notes |
+|---------|----------------------|--------------|-------|
+| react-native-quick-crypto | `^1.0.19` | `^0.7.x` | >= 1.0 requires Nitro Modules |
+| react-native-nitro-modules | `^0.35.4` | Not required | Only needed with quick-crypto >= 1.0 |
+| react-native-worklets | `^0.8.1` | Not required | Only needed with quick-crypto >= 1.0 |
+| react-native-keychain | `^9.0.0` (new arch) | `^8.2.0` | |
+| buffer | `^6.0.0` | `^6.0.0` | Required for EC mode Hermes helpers |
+| react-native-get-random-values | `^1.9.0` | `^1.9.0` | |
+
+---
+
+## CRITICAL: Transitive Dependencies of react-native-quick-crypto >= 1.0
+
+`react-native-quick-crypto@^1.0` depends on **Nitro Modules** (a C++/JSI bridge framework). This is the #1 source of build failures. You MUST install these manually:
+
+```bash
+npm install react-native-nitro-modules react-native-worklets
+```
+
+`react-native-quick-base64` is also a peer dep but is usually auto-installed. Verify: `npm ls react-native-quick-base64`.
+
+After install, ALWAYS clean Android before rebuilding:
+
+```powershell
+Remove-Item "android\app\.cxx","android\app\build","android\build" -Recurse -Force
+cd android; .\gradlew.bat clean; .\gradlew.bat app:installDebug
+```
+
+| Error | Cause | Fix |
+|---|---|---|
+| `ninja: build stopped: subcommand failed` | Missing `react-native-nitro-modules` | `npm install react-native-nitro-modules@^0.35.4` |
+| `autolinking.cpp` build failure | Stale .cxx cache | Delete `.cxx` and rebuild |
+| `undefined reference to NitroModules` | Version mismatch | Align versions per table above |
+
+### Post-Install Verification
+
+- [ ] `npm ls react-native-nitro-modules` — NOT `UNMET PEER DEP`
+- [ ] `npm ls react-native-worklets` — installed
+- [ ] `npm ls react-native-quick-base64` — >= 2.1.0
+- [ ] `npm ls buffer` — >= 6.0.0
+- [ ] Android clean build succeeds
+- [ ] iOS pod install succeeds
+
+---
+
+## React Native — Approach 6 (EC / ECDH Mode)
+
+### Required Libraries
+
+| Library | Purpose |
+|---------|---------|
+| `react-native-quick-crypto` | ECDH via `createECDH('prime256v1')`, AES-256-GCM, HMAC for HKDF, `randomBytes` |
+| `buffer` | `Buffer` polyfill (>= 6.0.0); `Buffer` from `buffer` pkg + `QCBuffer` from quick-crypto are different classes |
+| `react-native-keychain` | Secure token storage |
+| `react-native-get-random-values` | Polyfill |
+| `react-native-nitro-modules` | **REQUIRED peer dep** of quick-crypto >= 1.0 |
+| `react-native-worklets` | **REQUIRED peer dep** of quick-crypto >= 1.0 |
+
+> **No RSA library required** for EC mode. `react-native-quick-crypto` covers all EC crypto primitives.
+
+> **NEVER use `Buffer.toString('base64')` on Hermes** — it is broken. Use the `toBase64()` helper from `ec-crypto.util.ts` instead.
+
+### ECDH with react-native-quick-crypto
+
+```typescript
+import { createECDH, createHmac } from 'react-native-quick-crypto';
+import { Buffer } from 'buffer';
+import { Buffer as QCBuffer } from 'react-native-quick-crypto';
+
+const ecdh = createECDH('prime256v1');  // P-256 / secp256r1
+ecdh.generateKeys();
+const ephemeralPublicKey = ecdh.getPublicKey();           // Buffer, 65 bytes uncompressed
+const sharedSecret = ecdh.computeSecret(serverPublicKey); // Buffer, 32 bytes
+```
+
+Supported curves: `prime256v1` (P-256), `secp384r1` (P-384), `secp521r1` (P-521). Default: `prime256v1`.
+
+---
+
+## React Native — Approach 5 (Production Native Mode — RSA)
+
+### Required Libraries (instead of react-native-quick-crypto)
+
+| Library | Purpose |
+|---------|---------|
+| `react-native-aes-crypto` | Wraps `javax.crypto.Cipher` (Android) and CryptoKit/CommonCrypto (iOS) for AES-GCM |
+| `react-native-rsa-native` | Wraps `Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")` (Android) and `SecKeyCreateEncryptedData` (iOS) |
+| `react-native-keychain` | Same as JS mode |
+| `react-native-get-random-values` | Same as JS mode |
+
+> **Important:** Custom native modules `NativeCryptoModule.kt` + `NativeCryptoPackage.kt` (Android) and
+> `NativeCryptoModule.swift` + `NativeCryptoModule.m` (iOS) are still required alongside these libraries.
+> The libraries provide AES and RSA primitives; the custom modules expose them to JS with the exact
+> `encryptAES(plaintext, keyBase64)` / `decryptAES(ciphertextBase64, ivBase64, keyBase64)` / `encryptRSA(publicKeyPEM, dataBase64)` signature the interceptor expects.
+
+### Platform Requirements (Approach 5)
+
+- **Android:** `minSdkVersion >= 23` — `javax.crypto.Cipher` with `AES/GCM/NoPadding` requires API 23+.
+  Check `android/app/build.gradle` before proceeding; halt with guidance if below.
+- **iOS:** deployment target `>= 13.0` for `CryptoKit.AES.GCM`.
+  If `< 13.0`: use `CommonCrypto` bridge (`CCCryptorGCM` for AES-256-GCM + `SecKeyCreateEncryptedData` for RSA-OAEP).
+
+---
+
+## React Native — Approaches 2 and 3 (Basic)
+
+| Library | Approach | Purpose |
+|---------|---------|---------|
+| `axios` | 2, 3 | HTTP client (if not already installed) |
+| `jsencrypt` | 2 only | RSA encryption in JS |
+| `crypto-js` | 2, 3 | AES-CBC encryption |
+| `@types/crypto-js` | 2, 3 | TypeScript types for crypto-js |
+| `react-native-get-random-values` | 2, 3 | Polyfill — must be first import |
+
+---
+
+## Angular — Approaches 1, 2, 3
+
+| Library | Approach | Purpose |
+|---------|---------|---------|
+| *(none)* | 1 | Web Crypto API is built in |
+| `jsencrypt` | 2 | RSA encryption |
+| `crypto-js` | 2, 3 | AES-CBC encryption |
+| `@types/crypto-js` | 2, 3 | TypeScript types |
+
+Add `allowedCommonJsDependencies: ["crypto-js", "jsencrypt"]` to `angular.json` for approaches 2/3.
+
+---
+
+## Web — Approaches 1, 2, 3
+
+Same as Angular. No build tool config change required for plain JS/Vite projects.
+
+---
+
+## Node.js — Approaches 2, 3
+
+| Library | Approach | Purpose |
+|---------|---------|---------|
+| `jsencrypt` | 2 | RSA encryption |
+| `crypto-js` | 2, 3 | AES-CBC encryption |
+| `@types/crypto-js` | 2, 3 | TypeScript types |
+
+---
+
+## Android — Approaches 2, 3
+
+No npm/gradle packages required. `javax.crypto.Cipher` is part of the Android SDK.
+Ensure `minSdkVersion >= 21` for basic AES support.
+
+---
+
+## iOS — Approaches 1, 2, 3
+
+No CocoaPods packages required. `CryptoKit` (iOS 13+) and `CommonCrypto` are system frameworks.
+
+---
+
+## Flutter — Approaches 2, 3
+
+Add to `pubspec.yaml`:
+```yaml
+dependencies:
+  encrypt: ^5.0.3
+  pointycastle: ^3.7.3
+  crypto: ^3.0.3
+  dio: ^5.0.0
+```
+
+---
+
+## Compatibility Process (All Platforms)
+
+1. Read the React Native / framework version from `package.json` or project manifest.
+2. Inspect existing crypto and networking dependencies already installed.
+3. Select versions from the compatibility table above (or `setup.js` `VERSION_COMPAT` table for RN).
+4. Avoid replacing the existing networking stack unless required.
+5. Install only what is missing — skip already-installed packages.
+6. For RN: detect package manager (yarn / pnpm / npm) from lock files before installing.
+
+## Install Rules
+
+- Prefer pinned versions in production environments.
+- Validate iOS `pod install` and Android Gradle sync after install.
+- Keep upgrades minimal — only security-related package changes.
+- Never force upgrade unrelated packages.
+
+## Conflict Handling
+
+- If a dependency conflict appears:
+  - Propose compatible alternative versions.
+  - Explain the trade-off briefly.
+  - Do not force unrelated upgrades.
+  - Never downgrade a package that is already above the minimum required version.
+
+## Post-Install Verification
+
+### React Native JS Mode (Approach 4)
+
+- Build and run on Android and iOS after installation.
+- Confirm `randomBytes`, `createCipheriv`, `createDecipheriv` are available from `react-native-quick-crypto` at runtime.
+- Confirm `react-native-keychain` initializes correctly.
+- Confirm `react-native-get-random-values` polyfill is the first import in `index.js`.
+
+### React Native Native Mode (Approach 5)
+
+- Run `pod install` and Android Gradle sync successfully.
+- Confirm `NativeModules.NativeCryptoModule` is accessible from JS.
+- Confirm `encryptAES`, `decryptAES`, and `encryptRSA` are callable and return Promises.
+- Confirm AES encrypt + decrypt round-trip produces correct plaintext on both platforms.
+- Test on a physical device (not emulator/simulator only).