devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/error-handling-playbook.md

@@ -0,0 +1,234 @@
+# Error Handling Playbook
+
+Applies to all platforms and approaches unless tagged otherwise.
+
+---
+
+## Public Key Retrieval Failure (Approaches 1, 2, 4, 5, 6)
+
+- Retry according to configured policy (default: 3 attempts).
+- If still unavailable after all retries, block all encrypted API calls.
+- Return a deterministic error message to the caller — no sensitive data.
+- Log the failure reason at debug level only (no key material in the log).
+
+## Missing Request Key Mapping (Approaches 4, 5, 6 — React Native production)
+
+- Treat as non-recoverable for that response.
+- Attempt a controlled key refresh for the active key service (RSA or EC, depending on `ENCRYPTION_MODEL`) if configuration allows.
+- Fail securely without leaking partial decryption data.
+- Trigger auth/session recovery policy at the application level.
+
+## Invalid Auth Tag (Approaches 1, 4, 5, 6 — AES-GCM only)
+
+- Assume tampering or key mismatch — do not silently ignore.
+- Invalidate the active session immediately.
+- Trigger force logout or equivalent session reset policy.
+- Never surface the raw decryption error to the user — show a generic message.
+
+For EC integrations, check these mismatch classes before changing algorithms:
+
+- Per-request EC was implemented but the backend actually expects a session-init EC flow.
+- HKDF `info` string is wrong.
+- Base64url fields (`server_ecdh_pub`, `salt`) were decoded without normalizing `-`, `_`, and padding.
+- AAD bytes do not exactly match the backend's canonical JSON.
+- The `device_id` used for AAD or HKDF context does not match the session-init `device_id`.
+- Response payload is standard base64 but the client decoded it as base64url.
+- Response IV source is wrong (`iv` field vs `nonce` vs embedded payload bytes).
+
+### EC Session-Init Auth Tag Mismatch Checklist
+
+- Verify the client sends the real generated `client_ecdh_pub` from the same ECDH instance used for key derivation.
+- Verify whether `encrypted_shared_aes_key` must be decrypted or ignored.
+- Verify both required APIs are called in the correct order when the backend expects session init plus token creation.
+- Log the exact AAD string sent into AES-GCM.
+- Log which `device_id` is used in session init, HKDF context, and encrypted API calls.
+- Log the exact nonce string, nonce length, and the backend's expected nonce format.
+- Log whether the encrypted response contains `+` or `/` to distinguish standard base64 from base64url.
+- Confirm whether the nonce is raw UTF-8, base64-encoded IV bytes, or only a session identifier.
+
+### React Native / Hermes Practical Checks
+
+- If base64 output differs from a reference Flutter or backend client, verify the JS encoder path. A safe helper using `btoa()` may be more reliable than assuming `Buffer.toString('base64')` behavior.
+- If AES-GCM inputs are sliced out of a larger buffer and native crypto keeps failing unexpectedly, test with copied byte arrays instead of shared typed-array views.
+
+### Resolution Code for Common EC Failures
+
+**Base64url normalization** — apply to `server_ecdh_pub`, `salt`, and any base64url field before decoding:
+
+```typescript
+function urlSafeBase64ToStd(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+  return normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+}
+```
+
+**Hermes-safe base64 encoding** — use instead of `Buffer.toString('base64')`:
+
+```typescript
+function toBase64(buf: Uint8Array): string {
+  const bytes = new Uint8Array(buf);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+```
+
+**byteCopy for Buffer views** — use before passing sliced buffers to quick-crypto:
+
+```typescript
+function byteCopy(buf: Buffer | Uint8Array, start?: number, end?: number): Uint8Array {
+  const view = start !== undefined ? buf.slice(start, end) : buf;
+  return new Uint8Array(view);
+}
+```
+
+**Canonical AAD builder** — keys must be alphabetically sorted:
+
+```typescript
+function buildSessionAad(keyId: string, deviceId: string, apiVersion = 'v1'): Buffer {
+  return Buffer.from(
+    `{"api_ver":"${apiVersion}","device_id":"${deviceId}","key_id":"${keyId}"}`,
+    'utf8',
+  );
+}
+```
+
+### Dead Code Cleanup Warning
+
+After debugging encryption issues, remove these probe/debug functions if they were added during troubleshooting:
+- `unwrapSessionKey` — only needed if the backend's `encrypted_shared_aes_key` must be decrypted
+- `tryAesGcmDecrypt` — debugging helper for probing multiple HKDF variants
+- `hkdfExpandOnly`, `hkdfSwapped` — alternative KDF implementations tried during debugging
+- Multi-strategy `sessionDecrypt` probe loops — once the correct IV/AAD combination is confirmed, hardcode it and remove the loop
+- Any `console.log` that outputs decrypted plaintext, shared secrets, or AES key hex
+
+## Decryption Parse Failure (Approaches 4, 5)
+
+- Catch all parsing exceptions individually.
+- Return a sanitized error object to the caller.
+- Never log the plaintext payload or any key material.
+
+## Storage Failure — Keychain (Approaches 4, 5)
+
+- If a keychain write or read fails, abort the sensitive operation.
+- Surface an actionable error for retry.
+- Do not fall back to insecure storage (`AsyncStorage`, `localStorage`, plain files).
+- Treat a missing token that should exist as a session-expired state — force re-login.
+
+## Shared Key Not Set (Approach 3)
+
+- Fail at startup / first encrypt attempt with a clear configuration error.
+- Do not send the plaintext payload as a fallback.
+- Instruct the developer to set the shared key in the env/config file.
+
+## Build Failure After File Generation
+
+- Retry up to 3 times (setup.js `MAX_BUILD_RETRIES`).
+- After 3 failures, print the first 5 lines of build stderr and exit with code 4.
+- Do not delete generated files on build failure — allow the developer to inspect them.
+
+---
+
+## Android C++ / CMake / Ninja Build Failures (Approaches 4, 6 — After Installing Crypto Packages)
+
+### Symptom
+`ninja: build stopped: subcommand failed` during Android build, or CMake errors referencing `NitroModules` or `autolinking.cpp`.
+
+### Root Cause
+`react-native-quick-crypto` >= 1.0 depends on `react-native-nitro-modules` as a **peer dependency**. It is NOT auto-installed reliably.
+
+### Resolution
+1. Install missing peer deps: `npm install react-native-nitro-modules react-native-worklets`
+2. Clean Android build cache:
+   ```powershell
+   Remove-Item "android\app\.cxx","android\app\build","android\build" -Recurse -Force
+   cd android; .\gradlew.bat --stop; .\gradlew.bat clean
+   ```
+3. Rebuild: `.\gradlew.bat app:installDebug`
+4. If still failing: verify NDK version in `android/build.gradle` matches an installed NDK, and CMake 3.22.1 is installed in Android SDK.
+
+| Error message | Cause | Fix |
+|---|---|---|
+| `ninja: build stopped: subcommand failed` | Missing/wrong `react-native-nitro-modules` | `npm install react-native-nitro-modules@^0.35.4` |
+| `CMake Error: could not find NitroModules` | Nitro modules not installed | `npm install react-native-nitro-modules` |
+| `autolinking.cpp` build failure | Stale .cxx cache after adding native modules | Delete `.cxx` dir + rebuild |
+| `error: use of undeclared identifier` (C++) | NDK version mismatch | Delete `.cxx` dir + check NDK version |
+
+### Stale .cxx Cache After Native Module Changes
+
+- **Symptom:** Build worked before but fails after adding/removing/upgrading a native module.
+- **Cause:** CMake caches the previous native module list in `android/app/.cxx/`.
+- **Resolution:** Delete `android/app/.cxx/` and rebuild. Required every time a package with C++ native code is installed or upgraded.
+
+### Missing NDK or Wrong Version
+
+- **Symptom:** CMake error about missing NDK or toolchain.
+- **Cause:** `ndkVersion` in `android/build.gradle` doesn't match any installed NDK.
+- **Resolution:** Install the correct NDK version via Android SDK Manager, or update `ndkVersion` to match what's installed.
+
+### react-native-quick-base64 Version Mismatch
+
+- **Symptom:** Runtime crash or missing method error related to base64.
+- **Cause:** quick-crypto lists `react-native-quick-base64@>=2.1.0` as a peer dep. Version conflicts can cause issues.
+- **Resolution:** `npm ls react-native-quick-base64` — if missing or wrong version, install explicitly.
+
+---
+
+## React Native Native Mode — Additional Failure Paths (Approach 5)
+
+### Native Module Not Registered
+
+- **Symptom:** `NativeModules.NativeCryptoModule` is `undefined` at runtime.
+- **Cause:** Package not registered in `MainApplication` (Android) or bridge file not linked in Xcode (iOS).
+- **Resolution:** Verify registration, run `pod install`, clean build, and restart the app.
+- **Fail behavior:** Block all encrypted calls; surface a clear setup error, not a cryptic JS crash.
+
+### Keychain / Token Storage Unavailable
+
+- **Symptom:** `react-native-keychain` read/write throws an error or returns `null` for a token that should exist.
+- **Common cause:** Biometric policy change, device security policy reset, first run before any token was stored, or keychain access group misconfiguration.
+- **Resolution:** Treat as a session-expired state. Force the user to log in again to re-establish token storage.
+- **Fail behavior:** Show a clear "session expired, please log in" message. Do not silently proceed with a missing token.
+
+### Native Encrypt / Decrypt Rejection
+
+- **Symptom:** Native module `reject` callback fires with an error code (`ERR_ENCRYPT`, `ERR_DECRYPT`, `ERR_RSA_ENCRYPT`).
+- **Common causes:** Invalid key length (must be 32 bytes for AES-256), corrupted base64 input, IV length mismatch.
+- **Resolution:** Validate all inputs on the JS side before calling the native module. Log the error code but never the key material or plaintext.
+- **Fail behavior:** Treat as a non-recoverable crypto error for that request. Do not retry with different parameters.
+
+### AES Key Lifecycle Mismatch
+
+- **Symptom:** Decryption succeeds but produces garbage; auth tag verification fails.
+- **Common cause:** JS interceptor passed a different key into `decryptAES` than was used in `encryptAES`, or the request map entry was cleared before the response arrived.
+- **Resolution:** Ensure the request map stores the exact `aesKeyBase64` used for encryption and passes it unchanged into decryption. Clear only after decryption completes.
+
+### KEY_ID_NOT_FOUND — Retry Policy
+
+- **Trigger:** Server returns HTTP 401 with `error.code = "KEY_ID_NOT_FOUND"`.
+- **Action:** Call `invalidateRsaKey()`, then retry the original request **exactly once**.
+- **Fail behavior:** If the retry also returns `KEY_ID_NOT_FOUND`, surface a generic error to the user and stop. Never enter a retry loop.
+
+---
+
+## Angular-Specific (Approaches 1, 2, 3)
+
+- Interceptor errors must call `catchError` and return `next.handle(req)` (original request, unencrypted) — never block the HTTP pipeline.
+- `from(this.encryptionService.encrypt(...))` failures must be caught before `switchMap` — do not let them propagate as unhandled Observable errors.
+
+## Node.js Middleware (Approaches 2, 3)
+
+- Middleware catch block must call `next()` (not `next(err)`) to avoid Express error handler interception that could expose stack traces.
+- Never re-throw inside the middleware.
+
+## Android OkHttp Interceptor (Approaches 2, 3)
+
+- `chain.proceed(original)` must be called in the catch block to ensure the original request is forwarded even when encryption fails.
+- Never call `chain.proceed` more than once per request.
+
+## iOS URLRequest Mutator (Approaches 1, 2, 3)
+
+- Return the original `request` unmodified on any failure — never return `nil` or a partially mutated request.
+- All Swift throws must be caught within the function; do not propagate to the caller.

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

@@ -0,0 +1,105 @@
+# Platform: Flutter (Dart)
+
+## Overview
+
+Flutter uses a **Dio Interceptor** (`EncryptionInterceptor`) to transparently encrypt request bodies.  
+Crypto operations use the `encrypt` + `pointycastle` packages.  
+Supports Approaches 2 and 3 only (Approach 1 requires browser Web Crypto, unavailable in Dart).
+
+---
+
+## File Naming Convention
+
+| Role           | Path                                                            |
+|----------------|-----------------------------------------------------------------|
+| Config         | `lib/core/encryption/encryption_config.dart`                   |
+| Service        | `lib/core/encryption/encryption_service.dart`                  |
+| Interceptor    | `lib/core/encryption/encryption_interceptor.dart`              |
+| Module wiring  | `lib/core/network/dio_client.dart`                             |
+
+---
+
+## Module Wiring (Dio)
+
+```dart
+// In dio_client.dart
+Dio buildDio() {
+  final dio = Dio();
+  dio.interceptors.add(EncryptionInterceptor());
+  // ENCRYPTION_INTERCEPTOR_PLACEHOLDER
+  return dio;
+}
+```
+
+The `// ENCRYPTION_INTERCEPTOR_PLACEHOLDER` comment is the marker used by install.js `patchFile()`.
+
+---
+
+## Interceptor Pattern (Dart)
+
+```dart
+class EncryptionInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    if (!EncryptionConfig.encryptionEnabled) return handler.next(options);
+    if (EncryptionConfig.excludeUrls.any((prefix) => options.path.startsWith(prefix))) {
+      return handler.next(options);
+    }
+    try {
+      final body = options.data;
+      if (body == null || body is FormData) return handler.next(options);
+      final plaintext = body is String ? body : jsonEncode(body);
+      final encrypted = EncryptionService.encrypt(plaintext);
+      if (encrypted != null) options.data = encrypted;
+    } catch (_) {}
+    handler.next(options);
+  }
+}
+```
+
+---
+
+## URL Exclusion Pattern
+
+```dart
+if (EncryptionConfig.excludeUrls.any((prefix) => options.path.startsWith(prefix))) {
+  return handler.next(options);
+}
+```
+
+---
+
+## Dependencies (pubspec.yaml)
+
+```yaml
+dependencies:
+  encrypt: ^5.0.0
+  pointycastle: ^3.7.0
+  dio: ^5.0.0
+```
+
+```bash
+flutter pub get
+```
+
+---
+
+## Key Derivation (Approach 3 — Dart)
+
+```dart
+import 'package:pointycastle/digests/sha256.dart';
+
+Key deriveKey(String sharedKey) {
+  final digest = SHA256Digest();
+  final bytes  = Uint8List.fromList(utf8.encode(sharedKey));
+  return Key(digest.process(bytes));
+}
+```
+
+---
+
+## Build Command
+
+```bash
+flutter build apk --release
+```

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

@@ -0,0 +1,338 @@
+# Platform: iOS (Swift)
+
+## Overview
+
+iOS uses a **URLRequest mutator** (`EncryptionInterceptor`) called before requests are dispatched.  
+Supports Approaches 1, 2, 3 using **CryptoKit** (built-in, Swift 5.4+) or **CommonCrypto**.
+
+> File locations are determined at runtime by `assets/platform-matrix.json` for this platform.
+> Do not hardcode file paths in skill instructions or generated code.
+
+---
+
+## File Naming Convention
+
+| Role           | Path                                                      |
+|----------------|----------------------------------------------------------|
+| Config         | `Sources/Encryption/EncryptionConfig.swift`              |
+| Service        | `Sources/Encryption/EncryptionService.swift`             |
+| Interceptor    | `Sources/Encryption/EncryptionInterceptor.swift`         |
+| Module wiring  | `Sources/Network/NetworkManager.swift`                   |
+
+---
+
+## MANDATORY INTERACTIVE PROMPT SEQUENCE (Fresh Implementation)
+
+> **This section applies whenever no existing centralized `EncryptionService` is found in the project.**
+> **It is not optional. It is not skippable. It runs before Step 3 of the skill and before any file is generated.**
+> The agent MUST ask each question below, wait for the user's answer, and record the response before proceeding.
+> Do NOT infer, assume, or pre-fill any answer. Do NOT proceed to implementation until every question is answered.
+
+---
+
+### Prompt 1 — Encryption approach
+
+Ask the user exactly this question and wait for their answer:
+
+```
+Which encryption approach should be used for this iOS project?
+
+  1 — RSA-OAEP + AES-256-GCM (asymmetric hybrid; requires RSA public key PEM)
+  2 — RSA + AES-256-CBC       (asymmetric hybrid; requires RSA public key PEM)
+  3 — AES-256-CBC shared key  (symmetric; requires a shared secret string of 32+ characters)
+
+Enter 1, 2, or 3:
+```
+
+- Do not proceed until the user answers with 1, 2, or 3.
+- Do not default to any option if the user does not answer immediately.
+- If the user answers outside 1–3, re-ask.
+
+---
+
+### Prompt 2 — Key material
+
+After Prompt 1 is answered, ask the appropriate follow-up:
+
+**If approach 1 or 2:**
+```
+Provide the RSA public key PEM that will be used to encrypt the AES session key.
+The server must hold the corresponding private key to decrypt it.
+
+Paste the PEM (begins with -----BEGIN PUBLIC KEY----- or -----BEGIN RSA PUBLIC KEY-----):
+```
+
+**If approach 3:**
+```
+Provide the shared secret string (minimum 32 characters).
+This exact same secret must also be configured on the server.
+
+Enter shared secret:
+```
+
+**If the user says they want to reuse an existing Keychain entry:**
+```
+Provide the Keychain account name under service 'com.protect.common-storage'
+that holds the key material:
+```
+
+- Do not proceed until the user provides actual key material.
+- Do not accept a placeholder string (e.g. "MY_KEY", "test", "12345678901234567890123456789012").
+- Validate: shared keys must be ≥ 32 characters; PEM strings must contain valid PEM headers.
+- If validation fails, re-ask immediately.
+
+---
+
+### Prompt 3 — Backend decryption scope
+
+```
+Will a backend server decrypt the data encrypted by this service?
+
+  yes — server decryption is in scope; I confirm the server uses the same algorithm and key
+  no  — local/demo only; encryption and decryption happen within this app only
+
+Enter yes or no:
+```
+
+- If `yes`: confirm the server's expected payload format matches the approach (see approach reference files).
+- If `no`: the generated `EncryptionConfig` must include a comment stating the scope is local/demo only.
+
+---
+
+### Prompt 4 — HMAC signing
+
+```
+Should requests include an HMAC signature for integrity verification?
+
+  yes — HMAC-SHA256 signing enabled (requires ENCRYPTION_HMAC_SECRET environment variable at runtime)
+  no  — no HMAC signing
+
+Enter yes or no:
+```
+
+---
+
+### Prompt 5 — URL exclusions
+
+```
+Are there any URL prefixes that should NOT be encrypted?
+(e.g. /api/health, /api/upload for multipart endpoints)
+
+Enter comma-separated prefixes, or press Enter to skip:
+```
+
+---
+
+> **Only after all five prompts are answered may implementation proceed.**
+> Record all answers. Pass them into the config object at Step 6.
+> Never silently reuse a previous session's answers for a new fresh implementation.
+
+---
+
+## MANDATORY Pre-Implementation Rules
+
+> **HARD STOP. These rules are non-negotiable and sequential.**
+> **No encryption, decryption, key-management, or Keychain code may be written until every rule below is fully satisfied and explicitly confirmed.**
+> If any rule cannot be satisfied from available information, stop immediately and ask the user for the missing detail. Do not proceed with a default, a guess, or a "placeholder" value.
+
+---
+
+### Rule 1 — Algorithm and approach must be explicitly confirmed before any code is written
+
+**Never assume, infer, or default to any encryption algorithm** (AES-GCM, AES-CBC, RSA-OAEP, etc.).
+
+The approach (1, 2, or 3 as defined in the skill) **must be stated explicitly** by the user or present in a project-level definition before a single line of cryptographic code is generated.
+
+**Prohibited behaviours:**
+- Choosing AES-GCM because it is "modern" or "recommended"
+- Choosing AES-CBC because an existing backend uses it
+- Defaulting to approach 3 because no public key was provided
+- Proceeding with a comment such as `// TODO: confirm algorithm` and writing code anyway
+
+**Required action:** If the approach is not confirmed, stop and ask:
+> "Which encryption approach should be used (1 = RSA-OAEP + AES-256-GCM, 2 = RSA + AES-256-CBC, 3 = AES-256-CBC shared key)? This must be confirmed before implementation."
+
+---
+
+### Rule 2 — Key material source must be explicitly confirmed; random keys are forbidden for AES
+
+**Never generate a random symmetric key** (`SymmetricKey(size: .bits256)`, `SecRandomCopyBytes`, or any equivalent) as the actual encryption key in any context where data must be consistently decrypted — by the server, another device, or a future app session.
+
+A randomly generated key that exists only on the current device makes cross-party decryption impossible and corrupts any data already encrypted with a different session key.
+
+**The only permitted uses of random material are:**
+- Per-message nonces/IVs (random each encryption call — this is correct and required)
+- Ephemeral session keys in hybrid encryption where the key itself is RSA-encrypted and transmitted (Approach 1/2 only, and only when the server can unwrap it)
+
+**The actual root key must come from one of these explicitly confirmed sources:**
+
+| Confirmed source | Approach | Condition |
+|---|---|---|
+| User-supplied `sharedKey` string | 3 | Same key is configured on the server; confirmed by user |
+| User-supplied `publicKeyPem` | 1 or 2 | Server holds the matching private key; confirmed by user |
+| Existing Keychain entry by account name | Any | The same key is known to the decrypting party; confirmed by user |
+
+**If key material is not confirmed**, stop and ask:
+> "What is the source of the encryption key? (shared secret string / RSA public key PEM / existing Keychain entry) This must be confirmed before implementation."
+
+---
+
+### Rule 3 — Scan for existing encryption and Keychain implementations before creating anything new
+
+**Before writing any new file**, the centralized-module detection step (Step 2 of the skill) **must** be run against the project. If an existing `EncryptionService`, `CryptoService`, or equivalent is found:
+
+- **Do not create a new file.** The existing service is the canonical implementation.
+- **Do not modify the algorithm or key strategy** of the existing service unless the user explicitly requests a migration with a stated reason.
+- **Do not create a parallel Keychain account** for the same logical key. Use the namespace already established in the project (`com.protect.common-storage`).
+- Only generate the missing wiring layer (interceptor, config registration) around the existing service.
+
+**Similarly, if a Keychain wrapper or storage abstraction already exists in the project:**
+- Use it directly. Do not write new `SecItemAdd` / `SecItemCopyMatching` calls unless the existing abstraction is confirmed absent.
+- Do not introduce a second service namespace or a duplicate account key for the same secret.
+
+**Failure to scan first causes:**
+- Duplicate `EncryptionService` files with different keys — data encrypted by one cannot be decrypted by the other
+- Conflicting Keychain entries for the same logical secret
+- Silent encryption failures at runtime when the wrong service is called
+
+**Required action:** Run `detect.js` (or equivalent grep scan) and report findings before generating any file.
+
+---
+
+### Rule 4 — All new files must align with the existing project architecture; duplication is a defect
+
+**Every generated file must conform to:**
+- The existing folder structure (e.g. `Data/Security/` for service implementations)
+- The naming conventions already present in the project
+- The established Keychain service namespace: `com.protect.common-storage`
+- The existing dependency set — do not introduce new third-party packages unless the approach explicitly requires one and no built-in alternative exists
+
+**Duplication is not a workaround.** If the existing architecture cannot support the required encryption approach without modification, stop and raise the conflict to the user rather than creating a parallel structure alongside it.
+
+---
+
+### Rule 5 — Backend decryption capability must be confirmed before client-side encryption is implemented
+
+Encrypting data that the server cannot decrypt renders the API non-functional. Before writing any encryption code:
+
+- Confirm the server's decryption algorithm, key format, and expected payload shape
+- Confirm the server holds the correct key counterpart (private key for asymmetric; same shared key for symmetric)
+- If backend confirmation is not available, the implementation must be explicitly scoped as a demo/local-only build with no server integration — this must be stated in code comments and config
+
+---
+
+## Pre-Implementation Validation Gate
+
+> **All five items below must be checked BEFORE any code is written.**
+> If any item cannot be checked, STOP and collect the missing information.
+
+- [ ] **Algorithm confirmed** — approach (1, 2, or 3) stated explicitly by user or project definition; not assumed
+- [ ] **Key material source confirmed** — shared key / RSA public key PEM / Keychain entry; exact source identified
+- [ ] **Existing implementation scan completed** — `detect.js` or equivalent grep run; findings documented; no duplicate will be created
+- [ ] **Architecture alignment verified** — target folder, naming convention, and Keychain namespace (`com.protect.common-storage`) checked against existing project files
+- [ ] **Backend decryption confirmed** — server algorithm, key format, and payload shape agreed; or scope explicitly limited to local/demo use
+
+---
+
+## Centralized Module Detection (iOS-specific signals)
+
+`detect.js` uses the following signals to determine whether a **centralized** encryption service already exists:
+
+- A dedicated encryption service file that exports both `encrypt` and `decrypt` methods
+- The file is the **only** encryption entry point (no ad-hoc encrypt/decrypt calls outside it)
+- The interceptor or network layer already calls this service by reference
+
+If these conditions are all true → `centralized: true` → **reuse automatically** (State A).
+
+If encryption code exists but is scattered across multiple non-service files, or the service exists but the interceptor does not → `centralized: false` → **prompt user** (State B).
+
+---
+
+## Module Wiring
+
+```swift
+// In NetworkManager.swift
+func makeRequest(_ url: URL, body: Data?) async throws -> (Data, URLResponse) {
+    var request = URLRequest(url: url)
+    request.httpMethod = "POST"
+    request.httpBody   = body
+    request = EncryptionInterceptor.intercept(request: request)
+    // ENCRYPTION_INTERCEPTOR_PLACEHOLDER
+    return try await URLSession.shared.data(for: request)
+}
+```
+
+The `// ENCRYPTION_INTERCEPTOR_PLACEHOLDER` comment is the marker used by install.js `patchFile()`.
+
+---
+
+## Interceptor Pattern (Swift)
+
+```swift
+struct EncryptionInterceptor {
+    static func intercept(request: URLRequest) -> URLRequest {
+        guard EncryptionConfig.encryptionEnabled          else { return request }
+        guard let body     = request.httpBody             else { return request }
+        guard let plaintext = String(data: body, encoding: .utf8) else { return request }
+        guard let encrypted = EncryptionService.encrypt(plaintext) else { return request }
+        guard let encData   = encrypted.data(using: .utf8)         else { return request }
+
+        var modified          = request
+        modified.httpBody     = encData
+        return modified
+    }
+}
+```
+
+---
+
+## URL Exclusion Pattern
+
+```swift
+let url = request.url?.absoluteString ?? ""
+let excluded = EncryptionConfig.excludeUrls
+if excluded.contains(where: { url.hasPrefix($0) }) {
+    return request
+}
+```
+
+---
+
+## Approach 1 (CryptoKit — AES-GCM)
+
+> **Key source constraint:** `symmetricKey` must be derived from user-supplied key material only — a shared secret string hashed to 256 bits, or a session key unwrapped from an RSA-encrypted envelope. `SymmetricKey(size: .bits256)` (random key) **must never be used** as the production root key.
+
+```swift
+import CryptoKit
+let sealedBox = try AES.GCM.seal(data, using: symmetricKey)
+let combined  = sealedBox.combined!
+```
+
+## Approach 3 (CommonCrypto — AES-CBC)
+
+> **Key source constraint:** `keyBytes` must be derived from the user-supplied `sharedKey` (e.g. via SHA-256 hashing of the shared secret string). Random byte generation **must never be used** for the root key in any production or cross-party context.
+
+```swift
+import CommonCrypto
+var outBytes = [UInt8](repeating: 0, count: dataIn.count + kCCBlockSizeAES128)
+var numBytesEncrypted = 0
+CCCrypt(CCOperation(kCCEncrypt), CCAlgorithm(kCCAlgorithmAES),
+        CCOptions(kCCOptionPKCS7Padding), keyBytes, kCCKeySizeAES256,
+        ivBytes, dataIn, dataIn.count, &outBytes, outBytes.count, &numBytesEncrypted)
+```
+
+---
+
+## Dependencies
+
+- Approach 1: `CryptoKit` (built-in, iOS 13+)
+- Approach 2: `CryptoSwift` via Swift Package Manager
+- Approach 3: `CommonCrypto` (built-in)
+
+---
+
+## Build Command
+
+```bash
+xcodebuild -scheme YourScheme -configuration Debug build
+```