devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/backend-alignment.md

@@ -0,0 +1,506 @@
+# Backend Alignment Specification
+
+**Purpose:** This document is written by the frontend team for the backend team.
+It defines exactly what the backend must implement so that the encrypted React Native
+client can integrate without ambiguity.
+
+This specification covers two key exchange models. Share **only the relevant section**
+with the backend team based on the model selected.
+
+---
+
+## PART A — RSA Model (Key Wrapping)
+
+The React Native app uses **envelope encryption** on every mutating API call
+(POST / PUT / PATCH). Each request payload is encrypted with a one-time
+AES-256-GCM key. That AES key is then wrapped with the server's RSA public key.
+The backend must unwrap the AES key with its RSA private key, decrypt the payload,
+process it, and — if the response also carries sensitive data — encrypt the response
+in the same envelope format.
+
+---
+
+## 2. Crypto Algorithms — 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 by the client                  |
+| Asymmetric cipher| RSA-OAEP (mandatory)         | PKCS1 v1.5 only for legacy systems with written approval — not acceptable for new deployments in 2026. |
+| RSA key size     | Minimum 2048 bits            | 4096 recommended for new deployments                  |
+| Hash for OAEP    | SHA-256                      |                                                       |
+| Encoding         | Base64 (standard, no line breaks) | All binary fields use Base64                     |
+
+> **Do not** negotiate algorithm parameters at runtime. Both sides must use the
+> same agreed algorithm. If there is a mismatch, decryption will fail with an
+> auth tag error.
+
+---
+
+## 3. RSA Public Key Endpoint
+
+The client fetches the RSA public key at startup (or when the cached key expires).
+
+### 3.1 Request
+
+```
+GET /api/security/public-key
+Authorization: Bearer <access_token>   (if the route is authenticated)
+```
+
+### 3.2 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-----…`) or Base64 DER            |
+| `key_id`     | string | yes      | Version tag used for key rotation tracking                   |
+| `expires_at` | string | no       | ISO 8601 UTC. Client uses this to schedule key refresh.      |
+
+### 3.3 Format Contract
+
+- PEM is **preferred** because it is self-describing.
+- If Base64 DER is returned, communicate this to the frontend team explicitly.
+- The key must be a **public key** (`BEGIN PUBLIC KEY`), not a certificate (`BEGIN CERTIFICATE`).
+
+### 3.4 Error Responses
+
+| HTTP Status | When to return                         |
+|-------------|----------------------------------------|
+| 401         | Token invalid or missing               |
+| 503         | Key temporarily unavailable (HSM down) |
+
+The client retries with bounded back-off (default 3 attempts). If the key
+cannot be fetched, the client **blocks** all encrypted calls and surfaces an error.
+
+---
+
+## 4. Encrypted Request Contract
+
+Every POST / PUT / PATCH body the client sends will have this shape. The original
+JSON payload is replaced entirely.
+
+```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"
+}
+```
+
+### 4.1 Field Descriptions
+
+| Field    | Type   | Description                                                                        |
+|----------|--------|------------------------------------------------------------------------------------|
+| `data`   | string | Base64 of `AES-256-GCM(plaintext_json)`. The **last 16 bytes are the auth tag** — appended by the AES-GCM library automatically. |
+| `key`    | string | Base64 of `RSA-OAEP(aes_key_bytes)`. Encrypted with the public key returned by the key endpoint. |
+| `iv`     | string | Base64 of the 12-byte IV used for AES-GCM.                                         |
+| `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 endpoint `key_id`. |
+
+### 4.2 Step-by-Step Backend Decryption
+
+```
+1. Read `key_id` → select the matching RSA private key from secure storage.
+2. Base64-decode `key` → decrypt with RSA-OAEP (SHA-256) using the private key → raw 32-byte AES key.
+3. Base64-decode `iv` → 12-byte IV.
+4. Base64-decode `data` → ciphertext_with_tag.
+   - Last 16 bytes  = auth tag.
+   - Remaining bytes = ciphertext.
+5. Decrypt with AES-256-GCM(key, iv, ciphertext, tag).
+   - If auth tag verification FAILS → return 400 (see Section 7).
+6. Parse decrypted bytes as UTF-8 JSON → this is the original request payload.
+7. Validate nonce (see Section 6).
+8. Process the business logic with the original payload.
+```
+
+### 4.3 Content-Type
+
+The client sends `Content-Type: application/json`. The encrypted envelope is still valid JSON.
+
+---
+
+## 5. Encrypted Response Contract (Required When Response Contains Sensitive Data)
+
+The backend **MUST** encrypt responses using the **same AES key and a freshly
+generated IV** from the request envelope. There is no alternative key derivation.
+
+### Why the same AES key?
+
+The client stores `requestId → { aesKey, iv }` in memory for the lifetime of
+that request. It expects to decrypt the response with the same `aesKey`. The
+response must use a **new IV** (not the request IV) to avoid IV reuse.
+
+### Response Envelope
+
+```json
+{
+  "data":  "<Base64(ciphertext + auth_tag)>",
+  "iv":    "<Base64(new 12-byte IV, generated server-side for this response)>",
+  "nonce": "<server_generated_nonce>"
+}
+```
+
+| Field   | Type   | Description                                                                     |
+|---------|--------|---------------------------------------------------------------------------------|
+| `data`  | string | Base64 of `AES-256-GCM(response_json)`. Last 16 bytes are the auth tag.         |
+| `iv`    | string | Base64 of a **new** 12-byte IV generated by the server for this response only.  |
+| `nonce` | string | Server-generated nonce for audit/logging. Not validated by client.              |
+
+> **Mandatory:** The server must generate a fresh IV for every response. Reusing
+> the request IV with the same AES key is a critical security violation.
+
+### Step-by-Step Server-Side Response Encryption
+
+```
+1. Retrieve the AES key decrypted from the incoming request's `key` field.
+2. Generate a new cryptographically random 12-byte IV.
+3. Serialize the response JSON to UTF-8 bytes.
+4. Encrypt with AES-256-GCM(aes_key, new_iv, response_bytes) → ciphertext + auth_tag.
+5. Concatenate: encrypted_data = ciphertext || auth_tag.
+6. Return { data: base64(encrypted_data), iv: base64(new_iv), nonce: server_nonce }.
+```
+
+---
+
+## 6. Nonce / Anti-Replay Validation
+
+### Format
+
+```
+<appId>^<unix_timestamp_ms>.<16-char random hex>
+```
+
+Example: `com.myapp^1745189241337.a3f9c2e1d8b047f6`
+
+### Backend Validation Rules
+
+1. **Parse** the nonce: split on `^`, then split the right side on `.`.
+2. **Timestamp check:** reject if `|server_time_ms - timestamp_ms| > 300000` (5-minute window).
+3. **Uniqueness check (mandatory):** store each accepted nonce in Redis (or a distributed cache)
+   with TTL = replay window. A local in-process map is **not** acceptable in multi-instance deployments.
+   Reject immediately if the nonce already exists.
+4. **App ID check** (optional): validate `appId` matches a registered client identifier.
+
+> **Production requirement:** Nonce validation is **not optional**.
+
+---
+
+## 7. Error Response Contract for Crypto Failures
+
+```json
+{
+  "error": {
+    "code": "DECRYPTION_FAILED",
+    "message": "Request payload could not be decrypted."
+  }
+}
+```
+
+### Error Codes the Client Handles
+
+| HTTP Status | `error.code`           | Client Behaviour                                                                   |
+|-------------|------------------------|------------------------------------------------------------------------------------|
+| 400         | `DECRYPTION_FAILED`    | Surface generic error. Do NOT expose crypto details.                               |
+| 400         | `INVALID_NONCE`        | Surface generic error. Log for investigation.                                      |
+| 400         | `EXPIRED_NONCE`        | Surface "request expired" message to user.                                         |
+| 401         | `KEY_ID_NOT_FOUND`     | Fetch fresh RSA public key, then **retry the original request exactly once**.      |
+| 422         | `PAYLOAD_PARSE_ERROR`  | Surface generic error. Do not retry automatically.                                 |
+
+> Never include the plaintext payload, raw cipher bytes, or key material in error responses.
+
+---
+
+## 8. RSA Key Rotation
+
+1. Support **multiple active key pairs** simultaneously (minimum: current + previous).
+2. Each key pair has a unique `key_id`.
+3. When rotating: publish new public key, keep old private key active for a grace period (recommended: 24 hours).
+4. The client identifies which key to use via the `key_id` field in the request.
+5. On `KEY_ID_NOT_FOUND` (401), the client fetches a fresh public key and retries the request once.
+
+---
+
+## 9. HTTPS and SSL Pinning
+
+- All endpoints **must** be served over HTTPS (TLS 1.2+; TLS 1.3 strongly recommended).
+- **SSL pinning is strongly recommended** for high-security environments.
+- Provide SHA-256 fingerprints of leaf and/or intermediate CA certificate to the frontend team.
+- When rotating certificates, provide the new fingerprint **at least 2 weeks before** expiry.
+- Pin both current and backup fingerprints on the client to avoid rotation outages.
+
+---
+
+## 10. Endpoints That Accept Encrypted Payloads
+
+| Method | Encrypted by Default | Override Possible  |
+|--------|----------------------|--------------------|
+| POST   | Yes                  | Yes (exclude list) |
+| PUT    | Yes                  | Yes (exclude list) |
+| PATCH  | Yes                  | Yes (exclude list) |
+| GET    | No                   | No                 |
+| DELETE | No                   | No                 |
+
+---
+
+## 11. Backend Implementation Checklist
+
+Hand this checklist to the backend developer. All items must be confirmed before
+integration testing begins.
+
+### Cryptography
+
+- [ ] RSA-OAEP (SHA-256) private key decryption implemented.
+- [ ] AES-256-GCM decryption with auth tag verification implemented.
+- [ ] Auth tag failure returns `400 DECRYPTION_FAILED` without leaking details.
+- [ ] Decryption logic covered by unit tests (valid case + tampered tag case).
+
+### Key Management
+
+- [ ] RSA key pair generated with minimum 2048-bit key (4096 preferred).
+- [ ] Private key stored in a secrets manager or HSM — never in code or `.env` committed to version control.
+- [ ] Public key endpoint (`GET /api/security/public-key`) implemented and returns `public_key` + `key_id`.
+- [ ] `key_id` is stable and versioned (e.g., `v1`, `v2`).
+- [ ] Key rotation plan documented with grace period defined.
+
+### Nonce
+
+- [ ] Nonce parsing implemented (format: `appId^timestamp.random`).
+- [ ] Timestamp window check implemented (±5 minutes or agreed window).
+- [ ] Nonce stored in **Redis** (or distributed cache) with TTL = replay window. Local in-process map is not acceptable in multi-instance deployments.
+- [ ] Nonce uniqueness enforced: duplicate nonce rejected with `400 INVALID_NONCE`.
+- [ ] `INVALID_NONCE` and `EXPIRED_NONCE` error codes returned correctly.
+
+### Transport and SSL
+
+- [ ] All endpoints served over HTTPS (TLS 1.2+, TLS 1.3 preferred).
+- [ ] SSL certificate SHA-256 fingerprint(s) provided to the frontend team.
+- [ ] Certificate rotation schedule documented and communicated.
+- [ ] No crypto material appears in response bodies or server logs.
+- [ ] Error responses follow the agreed `{ error: { code, message } }` shape.
+
+### Response Encryption
+
+- [ ] Response envelope format matches Section 5.
+- [ ] Response encrypted with the **same AES key** from the incoming request.
+- [ ] Response uses a **freshly generated IV** — never the request IV.
+- [ ] Response auth tag verified by client confirmed during integration test.
+
+---
+
+## 12. Questions for the Backend Team to Answer Before Integration
+
+Before the frontend begins wiring up the interceptor, the backend team must
+confirm the following:
+
+1. What is the exact URL for the public key endpoint?
+2. Is the public key returned as PEM or Base64 DER?
+3. What is the `key_id` value for the first key pair?
+4. What is the `expires_at` value (or is it omitted)?
+5. Is the public key endpoint authenticated (requires Bearer token)?
+6. Should responses be encrypted? If yes, which endpoints? (Default rule: use same AES key as request, fresh IV per response.)
+7. What is the agreed nonce replay window (default: 5 minutes)?
+8. Is SSL pinning enabled? If yes, provide the SHA-256 leaf certificate fingerprint and the backup fingerprint for rotation.
+9. Is there an exclude list for endpoints that should not receive encrypted payloads?
+
+---
+
+## 13. Integration Test Scenarios
+
+| Scenario                                         | Expected Outcome                         |
+|--------------------------------------------------|------------------------------------------|
+| Valid encrypted POST request                     | 200, business response returned          |
+| Valid encrypted PUT request                      | 200, business response returned          |
+| Tampered `data` field (auth tag mismatch)        | 400, `DECRYPTION_FAILED`                 |
+| Replayed request (same nonce sent twice)         | 400, `INVALID_NONCE`                     |
+| Request with timestamp > 5 min in the past       | 400, `EXPIRED_NONCE`                     |
+| Unknown `key_id` in request                      | 401, `KEY_ID_NOT_FOUND` → client retries |
+| Public key endpoint returns 503                  | Client blocks and surfaces error         |
+| GET request (unencrypted)                        | Passes through normally                  |
+| Plaintext POST to encrypted endpoint (no `data` field) | 400 or 422, clear error             |
+
+---
+
+*Applies to: react-native approaches 4 (Production JS), 5 (Production Native), and 6 (EC mode).
+Keep in sync with `references/architecture.md`.*
+
+---
+
+## PART B — EC Model (ECDH + HKDF-SHA256)
+
+**Use this section when `ENCRYPTION_MODEL=ec` is selected.**
+Share PART B (not PART A) with the backend team.
+
+### B.1 Overview
+
+The client uses **Elliptic Curve Diffie-Hellman (ECDH)** for key exchange. Each request:
+1. Client generates a fresh ephemeral P-256 key pair.
+2. ECDH between the ephemeral private key and the server’s **static** EC public key → 32-byte shared secret.
+3. HKDF-SHA256(IKM=sharedSecret, salt=nonceBytes, info=`'enc'`) → 32-byte AES key.
+4. AES-256-GCM encrypts the payload.
+5. The derived AES key is **never transmitted**. Only the 65-byte uncompressed ephemeral public key is sent.
+
+This is the generic per-request EC contract. Some backends instead use a session-init EC contract. If your backend does that, you must explicitly provide that variant to the frontend team before implementation.
+
+### B.1a Session-Init EC Variant Checklist
+
+If the backend uses an init-session flow instead of per-request ephemeral encryption, confirm all of these explicitly:
+
+- Init endpoint and request/response schema
+- Whether `encrypted_shared_aes_key` is authoritative, optional, or intentionally ignored by the reference client
+- Exact HKDF `info` string
+- Exact AAD bytes required for AES-GCM, if any
+- Whether encrypted response payload is standard base64 or base64url
+- Where the response IV comes from: explicit `iv`, `nonce`, or some other field
+- Which `device_id` must be reused across init, key derivation, AAD, and encrypted API calls
+
+Example from a real backend integrated in this project:
+
+- HKDF `info`: `HDFC-LI-Session:v1|{keyId}|{deviceId}`
+- AAD: `{"api_ver":"v1","device_id":"DEV1001","key_id":"LI-DEV1001-EMP1005"}`
+- `encryptedResponse`: standard base64 of `ciphertext || auth_tag`
+- `server_ecdh_pub` and `salt`: base64url with padding omitted
+
+### B.2 Crypto Algorithms — Non-Negotiable (EC mode)
+
+| Parameter | Required Value | Notes |
+|-----------|---------------|-------|
+| Key exchange | ECDH P-256 (secp256r1) | Server holds a static EC key pair |
+| Key derivation | HKDF-SHA256 | salt = nonce bytes; info = `'enc'` (UTF-8); output = 32 bytes |
+| Symmetric cipher | AES-256-GCM | 256-bit key, 12-byte IV, 16-byte auth tag |
+| Public key format | Uncompressed P-256 point | 65 bytes: `0x04 \|\| X(32) \|\| Y(32)`, base64-encoded |
+| Encoding | Base64 (standard, no line breaks) | All binary fields |
+
+### B.3 EC Public Key Endpoint
+
+```
+GET /api/security/ec-public-key
+Authorization: Bearer <access_token>
+```
+
+**Response — 200 OK:**
+
+```json
+{
+  "public_key": "<base64(65-byte uncompressed P-256 public key)>",
+  "key_id": "ec-v1",
+  "expires_at": "2026-07-01T00:00:00Z"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `public_key` | yes | base64 of the 65-byte uncompressed EC point (`0x04` prefix). Must NOT be a compressed point (33 bytes). |
+| `key_id` | yes | Version tag for key rotation. |
+| `expires_at` | no | ISO 8601 UTC. Client uses this to schedule refresh. |
+
+> **Validation**: The client will reject any key where `base64decode(public_key).length !== 65` or `base64decode(public_key)[0] !== 0x04`.
+
+### B.4 Encrypted Request Envelope (EC mode)
+
+```json
+{
+  "data":                 "<base64(ciphertext + 16-byte GCM auth_tag)>",
+  "ephemeral_public_key": "<base64(65-byte uncompressed P-256 ephemeral public key)>",
+  "iv":                   "<base64(12-byte IV)>",
+  "nonce":                "<appId>^<unix_timestamp_ms>.<random_hex_16>",
+  "key_id":               "ec-v1"
+}
+```
+
+**No `key` field** — the AES key is derived independently by both sides via ECDH+HKDF. It is never transmitted.
+
+### B.5 Step-by-Step Backend Decryption (EC mode)
+
+```
+1. Base64-decode `ephemeral_public_key` → 65-byte uncompressed P-256 point.
+   Reject if length != 65 or first byte != 0x04.
+
+2. Read `key_id` → select the matching server EC private key.
+
+3. ECDH: sharedSecret = serverPrivateKey.computeSecret(ephemeralPublicKey)
+   → 32-byte shared secret.
+
+4. HKDF-SHA256:
+   - IKM  = sharedSecret (32 bytes)
+   - salt = UTF-8 bytes of the nonce string (entire nonce field value)
+   - info = 'enc' (UTF-8 bytes: 0x65, 0x6E, 0x63)
+   - output length = 32 bytes
+   PRK = HMAC-SHA256(salt, IKM)
+   OKM = HMAC-SHA256(PRK, info || 0x01)[0:32]
+   → aesKey (32 bytes)
+
+5. Base64-decode `iv` → 12-byte IV.
+
+6. Base64-decode `data` → ciphertext_with_tag.
+   - Last 16 bytes  = GCM auth tag.
+   - Remaining bytes = ciphertext.
+
+7. AES-256-GCM-Decrypt(key=aesKey, iv=iv, ciphertext, tag).
+   If auth tag FAILS → return 400 DECRYPTION_FAILED.
+
+8. Parse decrypted bytes as UTF-8 JSON → original request payload.
+
+9. Validate nonce (same rules as RSA mode, Section 6 of PART A).
+
+10. Process business logic.
+```
+
+### B.6 Response Encryption (EC mode)
+
+The server encrypts responses using the **same derived AES key** (from ECDH+HKDF) and a **fresh server-generated IV**:
+
+```json
+{
+  "data":  "<base64(ciphertext + 16-byte GCM auth_tag)>",
+  "iv":    "<base64(new 12-byte IV, server-generated for this response)>",
+  "nonce": "<server_generated_nonce>"
+}
+```
+
+> **Critical**: The response IV must be freshly generated by the server. Never reuse the request IV.
+
+### B.7 EC Key Rotation
+
+1. Server generates a new P-256 key pair.
+2. Publishes the new uncompressed public key at the endpoint with a new `key_id`.
+3. Keeps the old private key active for a grace period (24 hours recommended) to handle in-flight requests.
+4. After the grace period, retires the old private key.
+5. Client: on `KEY_ID_NOT_FOUND` (401), fetches a fresh EC public key and retries the original request exactly once.
+
+### B.8 Backend Implementation Checklist (EC mode)
+
+- [ ] P-256 static key pair generated and private key stored securely (HSM or secrets manager).
+- [ ] EC public key endpoint (`GET /api/security/ec-public-key`) returns 65-byte uncompressed point, base64-encoded.
+- [ ] ECDH implemented: `sharedSecret = serverPrivateKey.computeSharedSecret(clientEphemeralPublicKey)`.
+- [ ] HKDF-SHA256 implemented exactly as specified: salt=nonce bytes, info=`'enc'`, output=32 bytes.
+- [ ] AES-256-GCM decryption with auth tag verification implemented.
+- [ ] Response encrypted with derived AES key + fresh server IV.
+- [ ] Nonce validation implemented (same as RSA mode).
+- [ ] `KEY_ID_NOT_FOUND` (401) returned when `key_id` does not match any active key pair.
+- [ ] Auth tag failure returns `400 DECRYPTION_FAILED` without leaking crypto details.
+- [ ] Integration test: valid ECDH request → correct decryption → encrypted response → client decrypts correctly.
+
+### B.9 Questions for the Backend Team (EC mode)
+
+1. What is the exact URL for the EC public key endpoint?
+2. Confirm the EC public key will be returned as base64 of the 65-byte uncompressed P-256 point.
+3. What is the initial `key_id` value?
+4. Is HKDF confirmed as the key derivation function (not direct SHA-256 of the shared secret)?
+5. Should responses be encrypted? If yes, which endpoints?
+6. What is the nonce replay window (default: 5 minutes)?
+7. If this is a session-init EC backend rather than per-request EC, what exact HKDF `info` string must the client use?
+8. If AES-GCM AAD is required, what exact canonical bytes must the client send and verify?
+9. Are response payload bytes standard base64 or base64url?
+10. Where does the response IV come from for decryption?