devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/references/ec-implementation.md

@@ -0,0 +1,832 @@
+# EC (ECDH) Encryption — Implementation Reference
+
+Covers both **EC + React Native JS** and **EC + Native** modes.
+The interceptor structure, request mapping, and secure storage are identical to RSA modes.
+Only the key exchange mechanism and envelope shape differ.
+
+This document covers two distinct EC backend contracts:
+
+- Per-request EC envelope: the client generates an ephemeral key pair per encrypted request.
+- Session-init EC: the client performs a session handshake first, derives one session AES key, and reuses that key for subsequent encrypted APIs.
+
+Do not implement one while the backend expects the other.
+
+---
+
+## Contract Check First
+
+Before copying any EC code from this reference, confirm all of the following with the backend or a known-good client:
+
+1. Is the EC flow per-request or session-init?
+2. What exact endpoint establishes the EC session, if any?
+3. Is `encrypted_shared_aes_key` authoritative, or is it present but ignored by the reference client?
+4. What exact HKDF `info` string is used?
+5. Is AES-GCM AAD required, and if yes what canonical JSON must be used?
+6. Is the encrypted response payload standard base64 or base64url?
+7. Does the response IV come from an explicit `iv` field, the `nonce` field, or some other backend rule?
+
+This project exposed a backend that does **not** follow the generic per-request EC contract below. It uses a session-init contract instead.
+
+---
+
+## Session-Init EC Variant
+
+Use this variant when the backend exposes an auth/session initialization endpoint and then expects subsequent APIs to use a derived session AES key.
+
+### Working implementation sequence for this project
+
+This project required the following concrete order. If the backend contract matches this pattern, implement it exactly in this order instead of adapting the generic per-request sample:
+
+1. Generate a fresh client P-256 key pair.
+2. Call `initEncryptionSession` with the real generated `client_ecdh_pub`, stable `device_id`, `user_id`, `api_version`, and `platform`.
+3. Read `key_id`, `server_ecdh_pub`, `salt`, and any other session metadata from the init response.
+4. Derive the session AES key directly from ECDH + HKDF.
+5. Call `createSession` using the `key_id` from the init response.
+6. Persist only the auth token; keep the derived AES key in memory.
+7. Encrypt/decrypt business APIs with that cached session AES key.
+
+If a stored auth token exists later, do not assume the in-memory encryption session still exists after app restart. Re-establish the encryption session if the business API requires it.
+
+### Confirmed integration fixes from this project
+
+- Send the real generated `client_ecdh_pub` from the same ECDH instance whose private key is used for HKDF derivation.
+- Do not assume `encrypted_shared_aes_key` must be decrypted. In this backend, the working Flutter client ignored it and derived the session key directly.
+- Base64url fields such as `server_ecdh_pub` and `salt` must be normalized and padded before decoding.
+- Keep the session `device_id` stable. Do not derive HKDF with one device ID and send encrypted requests with another.
+- Confirm whether the login flow depends on both `initEncryptionSession` and `createSession`; in this project both were required.
+- The session key derivation was:
+  - `sharedSecret = ECDH(clientPrivateKey, serverPublicKey)`
+  - `prk = HMAC-SHA256(salt, sharedSecret)`
+  - `sessionKey = HMAC-SHA256(prk, "HDFC-LI-Session:v1|{keyId}|{deviceId}" || 0x01)[0:32]`
+- The backend required AES-GCM AAD with this exact canonical JSON shape:
+  - `{"api_ver":"v1","device_id":"DEV1001","key_id":"LI-DEV1001-EMP1005"}`
+- The `device_id` used in init, HKDF context, AAD, and encrypted requests must be the same stable session device identifier.
+- `encryptedResponse` was standard base64 of `ciphertext || 16-byte tag`.
+- Nonce had to be exactly 12 characters for this backend. Treat nonce length and character set as contract data, not a local preference.
+- The response IV contract had to be verified separately from payload decoding; do not infer it from the per-request EC example.
+- In React Native/Hermes, use a verified base64 encoder for public keys and payloads; do not assume every `Buffer` implementation behaves identically.
+- In React Native, sliced `Buffer` values handed to native crypto code may need explicit byte copies if typed-array views cause incorrect native reads.
+
+### Session-init TypeScript sketch
+
+```typescript
+function buildSessionAad(keyId: string, deviceId: string, apiVersion = 'v1'): Buffer {
+  return Buffer.from(
+    `{"api_ver":"${apiVersion}","device_id":"${deviceId}","key_id":"${keyId}"}`,
+    'utf8',
+  );
+}
+
+function deriveSessionKey(
+  clientEcdh: ReturnType<typeof createECDH>,
+  serverPubBase64Url: string,
+  saltBase64Url: string,
+  keyId: string,
+  deviceId: string,
+  apiVersion = 'v1',
+): Buffer {
+  const serverPub = Buffer.from(urlSafeBase64ToStd(serverPubBase64Url), 'base64');
+  const salt = Buffer.from(urlSafeBase64ToStd(saltBase64Url), 'base64');
+  const sharedSecret = clientEcdh.computeSecret(serverPub) as Buffer;
+  const contextInfo = `HDFC-LI-Session:${apiVersion}|${keyId}|${deviceId}`;
+  return hkdfSha256(sharedSecret, salt, Buffer.from(contextInfo, 'utf8'));
+}
+```
+
+### Session-init implementation notes
+
+- Persist only the auth token. Keep the derived session AES key in memory.
+- If the app restarts and only the token remains, you may need to re-establish the encryption session before encrypted APIs can work again.
+- Do not mix a stored JWT `deviceId` claim with the encryption session `device_id` if the backend expects a fixed session device identifier.
+
+### Session-init implementation checklist
+
+- [ ] `initEncryptionSession` sends the actual freshly generated `client_ecdh_pub`
+- [ ] `createSession` runs only after `initEncryptionSession` succeeds
+- [ ] `createSession` uses the returned `key_id`
+- [ ] nonce generation matches the backend's exact length and character rules
+- [ ] base64url fields are normalized and padded before decoding
+- [ ] session key derivation uses the exact backend `info` string
+- [ ] AAD bytes match the backend's canonical JSON exactly
+- [ ] encrypted response decoding uses the correct base64 alphabet
+- [ ] response IV source is confirmed from contract or reference client
+- [ ] stored auth token reuse does not bypass required encryption-session re-init
+
+### Session-init nonce guidance
+
+Do not hardcode a generic nonce policy for session-init backends. Confirm one of these explicitly:
+
+- 12 random raw bytes, then standard base64 encoded
+- 12 random raw bytes, then base64url encoded
+- 12-character alphanumeric string
+- another backend-specific format
+
+This project required a 12-character alphanumeric nonce. Using a different alphabet or length caused request rejection or decryption mismatches.
+
+**CRITICAL**: For session-init EC, the nonce IS the AES-GCM IV. The nonce generator MUST use a CSPRNG (`randomBytes` from quick-crypto), NOT `Math.random()`. A predictable IV under AES-GCM breaks both confidentiality and authenticity. See the `generateNonce()` implementation in the auth.service.ts sample below.
+
+---
+
+## EC Envelope Shape
+
+```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 derived AES key is never transmitted.
+
+---
+
+## Step 1: Add EC Types to `types.ts`
+
+Add alongside existing RSA types (do not remove them):
+
+```typescript
+// src/services/security/types.ts
+
+// Per-request cryptographic material stored in the in-memory request map.
+// Used by both RSA and EC modes (aesKey is the session AES key regardless of how it was obtained).
+// Use Uint8Array (not Buffer) — the `buffer` polyfill's Buffer and quick-crypto's Buffer are
+// different classes. Uint8Array is the safe common supertype.
+export type RequestCryptoMaterial = {
+  aesKey: Uint8Array;      // 32-byte AES-256-GCM session key (random for RSA, HKDF-derived for EC)
+  requestIv: Uint8Array;   // 12-byte IV used for this request's encryption (for reference only; response uses server IV)
+  keyId?: string;          // key_id from the active public key (for audit/logging)
+};
+
+export type EcPublicKeyResponse = {
+  public_key: string;   // base64(65-byte uncompressed P-256 point: 0x04 || X(32) || Y(32))
+  key_id: string;
+  expires_at?: string;
+};
+
+// Per-request EC envelope shape
+export type EcEncryptedEnvelope = {
+  data: string;                 // base64(ciphertext + 16-byte GCM auth_tag)
+  ephemeral_public_key: string; // base64(65-byte uncompressed ephemeral P-256 public key)
+  iv: string;                   // base64(12-byte IV)
+  nonce: string;                // Per-request: appId^unix_timestamp_ms.random_hex_16
+                                // Session-init: backend-specific (e.g. 12-char alphanumeric)
+  key_id?: string;
+};
+```
+
+---
+
+## Step 2: Create EC Key Service (`ec-key.service.ts`)
+
+Mirrors `RsaKeyService`. Validates the 65-byte uncompressed EC point on every fetch.
+
+```typescript
+// src/services/security/ec-key.service.ts
+import axios from 'axios';
+import Config from 'react-native-config';
+import type { EcPublicKeyResponse } from './types';
+
+const DEFAULT_EC_KEY_PATH = '/api/security/ec-public-key';
+const DEFAULT_RETRY_COUNT = 3;
+
+export class EcKeyService {
+  private cachedKey: EcPublicKeyResponse | null = null;
+
+  constructor(private readonly apiBaseUrl: string) {}
+
+  getCached(): EcPublicKeyResponse | null { return this.cachedKey; }
+  clearCache(): void { this.cachedKey = null; }
+
+  async getPublicKey(accessToken?: string): Promise<EcPublicKeyResponse> {
+    if (this.cachedKey) return this.cachedKey;
+    return this.refreshPublicKey(accessToken);
+  }
+
+  async refreshPublicKey(accessToken?: string): Promise<EcPublicKeyResponse> {
+    const configured = Config.EC_PUBLIC_KEY_ENDPOINT;
+    const url = configured && /^https:\/\//i.test(configured)
+      ? configured
+      : `${this.apiBaseUrl.replace(/\/$/, '')}${DEFAULT_EC_KEY_PATH}`;
+
+    const retries = Number(Config.EC_KEY_RETRY || DEFAULT_RETRY_COUNT);
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        const response = await axios.get<EcPublicKeyResponse>(url, {
+          timeout: 10000,
+          headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : undefined,
+        });
+        if (!response.data?.public_key) throw new Error('EC public key response missing public_key');
+        const decoded = Buffer.from(response.data.public_key, 'base64');
+        if (decoded.length !== 65 || decoded[0] !== 0x04) {
+          throw new Error('Invalid EC public key: must be 65-byte uncompressed P-256 point');
+        }
+        this.cachedKey = response.data;
+        return response.data;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error('Failed to fetch EC public key');
+  }
+}
+```
+
+---
+
+## Step 3: Create EC Crypto Utility (`ec-crypto.util.ts`)
+
+The code below is the generic per-request EC implementation. Do not use it for a session-init backend.
+
+### Critical: Hermes Buffer Compatibility
+
+React Native with Hermes has these known incompatibilities with crypto code:
+
+1. **`Buffer.toString('base64')` is broken** — the `buffer` polyfill relies on `base64-js` internals that fail with Hermes typed arrays. Use the `toBase64()` helper below instead.
+2. **Two `Buffer` classes exist** — `buffer` package's `Buffer` and `react-native-quick-crypto`'s `Buffer`. They are NOT interchangeable. `setAAD()` requires quick-crypto's `Buffer`.
+3. **`Buffer.slice()` returns views** — quick-crypto's native C++ code ignores `byteOffset` on typed-array views, reading wrong data. Always use `byteCopy()` before passing sliced buffers to crypto operations.
+
+### Required helpers (include in every EC crypto module)
+
+```typescript
+// Must import BOTH buffer packages
+import {
+  createCipheriv,
+  createDecipheriv,
+  createECDH,
+  createHmac,
+  randomBytes,
+  Buffer as QCBuffer,      // quick-crypto's Buffer — needed for setAAD()
+} from 'react-native-quick-crypto';
+import { Buffer } from 'buffer'; // Standard buffer polyfill — used for concat, from, etc.
+
+// btoa is available in Hermes (RN 0.73+) but not in TS lib types
+declare function btoa(input: string): string;
+
+/**
+ * Hermes-safe base64 encoding.
+ * DO NOT use Buffer.toString('base64') — it is broken on Hermes.
+ */
+export 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);
+}
+
+/** Convert any Buffer-like value from quick-crypto to a standard Buffer. */
+function toBuffer(input: unknown): Buffer {
+  if (Buffer.isBuffer(input)) return input;
+  return Buffer.from(input as Uint8Array);
+}
+
+/**
+ * Create a byte COPY (not a view) from a Buffer slice.
+ * quick-crypto's native code ignores byteOffset on typed-array views,
+ * reading the ENTIRE parent ArrayBuffer instead of just the slice.
+ * Passing `new Uint8Array(view)` guarantees a fresh ArrayBuffer.
+ */
+function byteCopy(buf: Buffer | Uint8Array, start?: number, end?: number): Uint8Array {
+  const view = start !== undefined ? buf.slice(start, end) : buf;
+  return new Uint8Array(view);
+}
+
+/**
+ * Convert URL-safe base64 to standard base64.
+ * Servers may return keys/salt with `-` and `_` instead of `+` and `/`.
+ */
+function urlSafeBase64ToStd(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+  return normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+}
+```
+
+### HKDF-SHA256 (used by both per-request and session-init)
+
+```typescript
+const AES_ALGO = 'aes-256-gcm';
+const AES_KEY_SIZE = 32;
+const IV_SIZE = 12;
+
+/**
+ * HKDF-SHA256: Extract + single-block Expand.
+ * PRK = HMAC-SHA256(salt, IKM)
+ * OKM = HMAC-SHA256(PRK, info || 0x01)[0:32]
+ *
+ * All args are byteCopy'd before use — quick-crypto may misread views.
+ */
+function hkdfSha256(ikm: Buffer, salt: Buffer, info: Buffer): Buffer {
+  const prk = toBuffer(
+    createHmac('sha256', byteCopy(salt)).update(byteCopy(ikm)).digest(),
+  );
+  const t1 = toBuffer(
+    createHmac('sha256', byteCopy(prk))
+      .update(byteCopy(Buffer.concat([info, Buffer.from([0x01])])))
+      .digest(),
+  );
+  return t1.slice(0, AES_KEY_SIZE);
+}
+```
+
+### Full per-request implementation (React Native JS mode)
+
+```typescript
+export async function ecEncryptPayload(
+  payload: unknown,
+  serverEcPublicKeyBase64: string,
+  nonce: string,
+  keyId?: string,
+): Promise<{ envelope: EcEncryptedEnvelope; material: RequestCryptoMaterial }> {
+  const ecdh = createECDH('prime256v1');
+  ecdh.generateKeys();
+  const ephemeralPublicKeyBytes = toBuffer(ecdh.getPublicKey()); // 65 bytes
+
+  const serverPublicKeyBytes = Buffer.from(serverEcPublicKeyBase64, 'base64');
+  const sharedSecret = toBuffer(ecdh.computeSecret(serverPublicKeyBytes as any));
+
+  // HKDF: salt = nonce bytes, info = 'enc' (per-request contract)
+  const aesKey = hkdfSha256(
+    sharedSecret,
+    Buffer.from(nonce, 'utf8'),
+    Buffer.from('enc', 'utf8'),
+  );
+
+  const iv = toBuffer(randomBytes(IV_SIZE));
+  const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+
+  // byteCopy every arg before handing to quick-crypto cipher
+  const cipher = createCipheriv(AES_ALGO, byteCopy(aesKey), byteCopy(iv));
+  const encrypted = toBuffer(cipher.update(byteCopy(plaintext)));
+  const finalBlock = toBuffer(cipher.final());
+  const authTag = toBuffer(cipher.getAuthTag());
+
+  const data = Buffer.concat([encrypted, finalBlock, authTag]);
+
+  return {
+    envelope: {
+      data: toBase64(data),                           // NOT data.toString('base64')
+      ephemeral_public_key: toBase64(ephemeralPublicKeyBytes), // NOT .toString('base64')
+      iv: toBase64(iv),                               // NOT iv.toString('base64')
+      nonce,
+      key_id: keyId,
+    },
+    material: { aesKey, requestIv: iv, keyId },
+  };
+}
+
+// ECDH + HKDF only — for EC + Native mode (AES runs natively)
+export async function ecDeriveKey(
+  serverEcPublicKeyBase64: string,
+  nonce: string,
+): Promise<{ derivedAesKeyBase64: string; ephemeralPublicKeyBase64: string }> {
+  const ecdh = createECDH('prime256v1');
+  ecdh.generateKeys();
+  const ephemeralPublicKeyBytes = toBuffer(ecdh.getPublicKey());
+  const serverPublicKeyBytes = Buffer.from(serverEcPublicKeyBase64, 'base64');
+  const sharedSecret = toBuffer(ecdh.computeSecret(serverPublicKeyBytes as any));
+  const aesKey = hkdfSha256(sharedSecret, Buffer.from(nonce, 'utf8'), Buffer.from('enc', 'utf8'));
+  return {
+    derivedAesKeyBase64: toBase64(aesKey),               // NOT aesKey.toString('base64')
+    ephemeralPublicKeyBase64: toBase64(ephemeralPublicKeyBytes), // NOT .toString('base64')
+  };
+}
+
+// Per-request EC: Response decryption — identical to RSA mode
+export { decryptResponsePayload, isEncryptedResponse } from './crypto.util';
+```
+
+### Session-init EC: Full encrypt/decrypt functions
+
+These are the WORKING implementations for session-init EC backends. They differ from
+per-request EC in critical ways: the nonce is the IV, AAD is mandatory, and the
+session AES key is reused across requests.
+
+```typescript
+/**
+ * Build canonical AAD for AES-GCM.
+ * Keys MUST be alphabetically sorted. The backend must produce the exact same JSON.
+ */
+export function buildSessionAad(
+  keyId: string,
+  deviceId: string,
+  apiVersion = 'v1',
+): Buffer {
+  // Alphabetical key order is part of the contract
+  return Buffer.from(
+    `{"api_ver":"${apiVersion}","device_id":"${deviceId}","key_id":"${keyId}"}`,
+    'utf8',
+  );
+}
+
+/**
+ * Derive a session AES-256 key from ECDH shared secret + server salt.
+ * Called once after encryption session init.
+ *
+ * IMPORTANT: The `info` string is backend-specific.
+ * This project uses "HDFC-LI-Session:{apiVersion}|{keyId}|{deviceId}".
+ * Do NOT assume "enc" — confirm with the backend team.
+ */
+export function deriveSessionKey(
+  clientEcdh: ReturnType<typeof createECDH>,
+  serverEcdhPubBase64: string,
+  saltBase64: string,
+  keyId: string,
+  deviceId: string,
+  apiVersion = 'v1',
+): Buffer {
+  // Normalize base64url → standard base64 (with padding)
+  const serverPubBytes = Buffer.from(urlSafeBase64ToStd(serverEcdhPubBase64), 'base64');
+  const sharedSecret = toBuffer(clientEcdh.computeSecret(serverPubBytes as any));
+  const saltBytes = Buffer.from(urlSafeBase64ToStd(saltBase64), 'base64');
+
+  // Backend-specific info string — confirm this with your backend
+  const contextInfo = `HDFC-LI-Session:${apiVersion}|${keyId}|${deviceId}`;
+  return hkdfSha256(sharedSecret, saltBytes, Buffer.from(contextInfo, 'utf8'));
+}
+
+/**
+ * Encrypt a payload with a pre-derived session AES key.
+ * Uses nonce (12 chars) as the IV (not a random IV).
+ * Returns base64(ciphertext || 16-byte GCM auth tag).
+ */
+export function sessionEncrypt(
+  payload: unknown,
+  aesKey: Buffer,
+  nonce: string,
+  aad?: Buffer,
+): string {
+  const iv = Buffer.from(nonce, 'utf8');
+  const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+
+  const cipher = createCipheriv(AES_ALGO, byteCopy(aesKey), byteCopy(iv));
+  // AAD must be set with QCBuffer.from() — the buffer polyfill's Buffer
+  // is a different class and setAAD will silently fail or throw.
+  if (aad && aad.length > 0) {
+    cipher.setAAD(QCBuffer.from(byteCopy(aad)));
+  }
+  const encrypted = toBuffer(cipher.update(byteCopy(plaintext)));
+  const finalBlock = toBuffer(cipher.final());
+  const authTag = toBuffer(cipher.getAuthTag());
+
+  const data = Buffer.concat([encrypted, finalBlock, authTag]);
+  return toBase64(data);
+}
+
+/**
+ * Decrypt a server response with a pre-derived session AES key.
+ * Input: base64(ciphertext || 16-byte GCM auth tag).
+ *
+ * Response IV source varies by backend:
+ * - This project: the nonce string (UTF-8 bytes) is the IV.
+ * - Other backends may return a separate `iv` field in the response.
+ *
+ * If decryption fails, this function probes multiple IV/AAD combinations
+ * to help identify the correct contract. Once confirmed, remove the probe
+ * and hardcode the working strategy.
+ */
+export function sessionDecrypt(
+  encryptedBase64: string,
+  aesKey: Buffer,
+  nonce: string,
+  aad?: Buffer,
+): string {
+  const decoded = Buffer.from(encryptedBase64, 'base64');
+  if (decoded.length < 16) {
+    throw new Error(`Response too short: ${decoded.length} bytes`);
+  }
+
+  // byteCopy every slice — Buffer.slice() returns views, not copies
+  const authTag = byteCopy(decoded, decoded.length - 16);
+  const ciphertext = byteCopy(decoded, 0, decoded.length - 16);
+
+  // Build IV candidates to probe
+  const ivCandidates: Array<{ label: string; iv: Buffer }> = [
+    { label: 'utf8-nonce', iv: Buffer.from(nonce, 'utf8') },
+  ];
+  try {
+    const decodedNonce = Buffer.from(urlSafeBase64ToStd(nonce), 'base64');
+    if (decodedNonce.length > 0) {
+      ivCandidates.push({ label: 'base64-nonce', iv: decodedNonce });
+    }
+  } catch { /* ignore invalid base64 */ }
+  ivCandidates.push({ label: 'zero-iv', iv: Buffer.alloc(12, 0) });
+
+  const aadCandidates: Array<{ label: string; aadValue?: Buffer }> = [
+    { label: 'with-aad', aadValue: aad },
+    { label: 'without-aad', aadValue: undefined },
+  ];
+
+  let lastError: unknown;
+  for (const ivCandidate of ivCandidates) {
+    for (const aadCandidate of aadCandidates) {
+      try {
+        const decipher = createDecipheriv(
+          AES_ALGO,
+          byteCopy(aesKey),
+          byteCopy(ivCandidate.iv),
+        );
+        if (aadCandidate.aadValue && aadCandidate.aadValue.length > 0) {
+          decipher.setAAD(QCBuffer.from(byteCopy(aadCandidate.aadValue)));
+        }
+        decipher.setAuthTag(QCBuffer.from(authTag));
+
+        const decrypted = toBuffer(decipher.update(ciphertext));
+        const finalBlock = toBuffer(decipher.final());
+        const plaintext = Buffer.concat([decrypted, finalBlock]).toString('utf8');
+
+        // Log which strategy worked so you can hardcode it later.
+        // NEVER log the plaintext itself — only the strategy labels.
+        console.log('[sessionDecrypt] SUCCESS via', ivCandidate.label, aadCandidate.label);
+        return plaintext;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error('Session decrypt failed');
+}
+```
+
+### Session-init auth service pattern (`auth.service.ts`)
+
+For session-init EC, the encryption lifecycle is owned by a stateful service class,
+not by generic interceptors. The service holds the derived session AES key in memory
+and uses it for all encrypted API calls within that session.
+
+```typescript
+// src/services/auth.service.ts
+import axios, { AxiosInstance } from 'axios';
+import { createECDH, randomBytes } from 'react-native-quick-crypto';
+import { Buffer } from 'buffer';
+import {
+  deriveSessionKey,
+  sessionEncrypt,
+  sessionDecrypt,
+  buildSessionAad,
+  toBase64,
+} from './security/ec-crypto.util';
+
+const DEFAULT_ENCRYPTION_DEVICE_ID = 'DEV1001';
+
+/**
+ * Generate a cryptographically secure random alphanumeric nonce.
+ * MUST use CSPRNG (randomBytes) — not Math.random() — because for
+ * session-init EC the nonce IS the AES-GCM IV. A predictable IV
+ * under AES-GCM completely breaks confidentiality and authenticity.
+ */
+function generateNonce(length = 12): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  const bytes = randomBytes(length);
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars[bytes[i] % chars.length];
+  }
+  return result;
+}
+
+class AuthApiService {
+  private authClient: AxiosInstance;
+  private sessionAesKey: Buffer | null = null;
+  private encryptionKeyId: string | null = null;
+  private sessionDeviceId: string | null = null;
+  private sessionApiVersion = 'v1';
+
+  constructor(baseUrl: string) {
+    this.authClient = axios.create({
+      baseURL: baseUrl,
+      timeout: 30_000,
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    });
+  }
+
+  /**
+   * Step 1: Initialize encryption session.
+   * Generates ECDH key pair, sends public key to server, derives session key.
+   */
+  async initEncryptionSession(userId: string, deviceId?: string) {
+    const devId = deviceId || DEFAULT_ENCRYPTION_DEVICE_ID;
+
+    // Generate a REAL ECDH key pair — the private key is needed for HKDF
+    const ecdh = createECDH('prime256v1');
+    ecdh.generateKeys();
+    const clientPubKeyBase64 = toBase64(new Uint8Array(ecdh.getPublicKey() as any));
+
+    const response = await this.authClient.post(
+      '/api/v1/auth-services/api/auth/encryption/session/init',
+      {
+        client_ecdh_pub: clientPubKeyBase64,  // MUST be the real generated key
+        device_id: devId,
+        user_id: userId,
+        api_version: 'v1',
+        platform: 'web',
+        session_duration_minutes: 120,
+      },
+    );
+
+    const data = response.data;
+
+    // Derive session key directly from ECDH + HKDF.
+    // encrypted_shared_aes_key from server is IGNORED (confirmed from Flutter reference).
+    this.sessionAesKey = deriveSessionKey(
+      ecdh, data.server_ecdh_pub, data.salt, data.key_id, devId,
+    );
+
+    this.encryptionKeyId = data.key_id;
+    this.sessionDeviceId = devId;
+    return data;
+  }
+
+  /**
+   * Step 2: Create auth session (uses key_id from init).
+   */
+  async createSession(body: CreateSessionRequest) {
+    // ... standard auth call using this.encryptionKeyId ...
+  }
+
+  /**
+   * Step 3: Encrypted business API call (example — replace with your actual API).
+   */
+  async exampleApiTesting(token: string, payload: Record<string, unknown>) {
+    if (!this.encryptionKeyId || !this.sessionAesKey) {
+      throw new Error('Encryption session not initialized');
+    }
+
+    const nonce = generateNonce(); // 12-char alphanumeric
+    const aad = buildSessionAad(
+      this.encryptionKeyId,
+      this.sessionDeviceId!,
+      this.sessionApiVersion,
+    );
+
+    // Replace the payload and endpoint with your actual API contract
+    const encryptedData = sessionEncrypt(payload, this.sessionAesKey, nonce, aad);
+
+    const response = await this.authClient.post('/api/v1/your-service/your-endpoint', {
+      encryptedRequest: encryptedData,
+      keyId: this.encryptionKeyId,
+    }, {
+      headers: {
+        'X-Nonce': nonce,
+        'X-Device-ID': this.sessionDeviceId,
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    // Decrypt response
+    if (response.data?.encryptedResponse) {
+      const decrypted = sessionDecrypt(
+        response.data.encryptedResponse,
+        this.sessionAesKey,
+        response.data.nonce || nonce,
+        aad,
+      );
+      return JSON.parse(decrypted);
+    }
+    return response.data;
+  }
+}
+```
+
+---
+
+## Step 4: Wire EC into API Service (`api.ts`)
+
+```typescript
+// New env variables read at module level
+const ENCRYPTION_MODEL = (Config.ENCRYPTION_MODEL || 'rsa').toLowerCase(); // 'rsa' or 'ec'
+
+// In constructor — instantiate EC key service alongside RSA key service:
+private ecKeyService: EcKeyService;
+
+// In setAuthToken — prefetch the active key service:
+if (ENCRYPTION_ENABLED && token) {
+  if (ENCRYPTION_MODEL === 'ec') {
+    void this.ecKeyService.refreshPublicKey(token).catch(() => undefined);
+  } else {
+    void this.rsaKeyService.refreshPublicKey(token).catch(() => undefined);
+  }
+}
+
+// In request interceptor — branch on ENCRYPTION_MODEL (JS layer only):
+// Note: use ENCRYPTION_LAYER === 'js' guard so EC+Native falls through to the native block below.
+if (ENCRYPTION_MODEL === 'ec' && ENCRYPTION_LAYER === 'js') {
+  const keyData = await this.ecKeyService.getPublicKey(this.token || undefined);
+  const requestId = buildNonce(APP_ID);
+  const { envelope, material } = await ecEncryptPayload(
+    nextConfig.data, keyData.public_key, requestId, keyData.key_id,
+  );
+  this.requestMaterials.set(requestId, material);
+  nextConfig.headers.set('X-Request-Id', requestId);
+  if (keyData.key_id) {
+    nextConfig.headers.set('X-Key-Id', keyData.key_id);
+  }
+  // HMAC signing (EC mode — no `key` field, trailing `|` in canonical string)
+  if (Config.HMAC_ENABLED === 'true') {
+    const signature = buildHmacSignature(
+      { method: nextConfig.method ?? 'POST', url: nextConfig.url ?? '',
+        nonce: requestId, keyId: keyData.key_id, envelope },
+      Config.HMAC_SHARED_SECRET ?? '',
+    );
+    nextConfig.headers.set('X-Payload-Signature', signature);
+    nextConfig.headers.set('X-Signature-Algorithm', 'HMAC-SHA256');
+  }
+  nextConfig.data = envelope;
+  nextConfig.metadata = { ...nextConfig.metadata, requestId };
+} else if (ENCRYPTION_MODEL === 'rsa') {
+  // existing RSA JS path (unchanged)
+}
+
+// In request interceptor — branch on ENCRYPTION_MODEL (Native layer):
+if (ENCRYPTION_MODEL === 'ec' && ENCRYPTION_LAYER === 'native') {
+  const keyData = await this.ecKeyService.getPublicKey(this.token || undefined);
+  const requestId = buildNonce(APP_ID);
+  const { derivedAesKeyBase64, ephemeralPublicKeyBase64 } = await ecDeriveKey(
+    keyData.public_key, requestId,
+  );
+  const { ciphertext, iv } = await nativeEncryptAES(JSON.stringify(nextConfig.data), derivedAesKeyBase64);
+  nextConfig.data = {
+    data: ciphertext,
+    ephemeral_public_key: ephemeralPublicKeyBase64,
+    iv,
+    nonce: requestId,
+    key_id: keyData.key_id,
+  };
+  this.requestMaterials.set(requestId, {
+    aesKey: Buffer.from(derivedAesKeyBase64, 'base64'),
+    requestIv: Buffer.from(iv, 'base64'),
+    keyId: keyData.key_id,
+  });
+  nextConfig.metadata = { ...nextConfig.metadata, requestId };
+}
+
+// On KEY_ID_NOT_FOUND (401) — refresh the active key service:
+if (ENCRYPTION_MODEL === 'ec') {
+  return this.ecKeyService.refreshPublicKey(this.token || undefined)
+    .then(() => this.instance.request(retryConfig));
+} else {
+  return this.rsaKeyService.refreshPublicKey(this.token || undefined)
+    .then(() => this.instance.request(retryConfig));
+}
+```
+
+---
+
+## Step 5: Environment Variables
+
+```
+ENCRYPTION_MODEL=ec
+EC_PUBLIC_KEY_ENDPOINT=https://api.example.com/api/security/ec-public-key
+EC_KEY_RETRY=3
+
+# EC + Native mode only:
+ENCRYPTION_LAYER=native
+```
+
+---
+
+## Deliverables Summary
+
+### EC + React Native JS
+
+| File | Action |
+|------|--------|
+| `src/services/security/types.ts` | Add `EcPublicKeyResponse`, `EcEncryptedEnvelope` |
+| `src/services/security/ec-key.service.ts` | Create |
+| `src/services/security/ec-crypto.util.ts` | Create (`ecEncryptPayload`, `ecDeriveKey`) |
+| `src/services/api.ts` | Add `ENCRYPTION_MODEL` routing |
+| `.env` / `.env.example` | Add EC env vars |
+
+### EC + Native
+
+All EC JS deliverables above, plus:
+
+| File | Action |
+|------|--------|
+| `src/services/security/ec-crypto.util.ts` | Use `ecDeriveKey` (no AES in JS) |
+| `src/services/api.ts` | Call `ecDeriveKey` → pass `derivedAesKeyBase64` to existing `nativeEncryptAES` |
+| `.env` | Add `ENCRYPTION_LAYER=native` |
+
+No new Kotlin or Swift files required — existing `NativeCryptoModule` is reused.
+
+---
+
+## Security Requirements (EC mode)
+
+- EC public key MUST be validated on every fetch: decoded length == 65, first byte == `0x04`.
+- Ephemeral EC key pair is discarded immediately after `computeSecret()` returns.
+- Derived AES key is NEVER transmitted — only the 65-byte ephemeral public key is sent.
+- HKDF salt MUST be the per-request nonce to bind the derived key to this specific request.
+- On `KEY_ID_NOT_FOUND` (401): refresh EC public key and retry exactly once — no loop.
+
+Additional requirements for session-init EC backends:
+
+- Do not unwrap `encrypted_shared_aes_key` unless the backend contract explicitly requires it.
+- Normalize and pad base64url fields before decoding.
+- Treat AAD as part of the contract, not an optional add-on.
+- Confirm whether the response IV comes from `iv`, `nonce`, or another field before implementing decryption.