devendra-skill-package 1.0.2

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

@@ -0,0 +1,668 @@
+# Platform: React JS (Web) — Production Crypto (Approach 7)
+
+## Overview
+
+React JS web projects on approach 7 use the **built-in Web Crypto API** (`window.crypto.subtle`) for all cryptographic operations.  
+No external crypto packages are required. All crypto is native to the browser.
+
+Supports two modes:
+- **RSA-OAEP** (default) — per-request AES-256-GCM key wrapped with the server's RSA public key. Full request/response encryption. Per-request key isolation.
+- **ECDH-Session** — ECDH P-256 + HKDF-SHA256 session key derivation + AES-256-GCM with AAD. No RSA. Session key derived once per session. Use when integrating with ECDH-Session / HDFC-LI partner APIs.
+
+> **Approach 7 vs Approach 1 for React:**  
+> Approach 1 is a basic `crypto.subtle` encrypt-only interceptor with no response decryption, no RSA key management, and no session handling.  
+> Approach 7 is the full production-grade React JS equivalent of React Native approach 4 — it adds per-request key isolation, response decryption, RSA key service (fetch/cache/retry), in-memory request mapping with guaranteed cleanup, browser-safe storage, and ECDH-Session support.
+
+---
+
+## Prerequisite: Web Crypto API Availability
+
+`crypto.subtle` is only available on **secure origins** (HTTPS or `localhost`).  
+It is `undefined` on plain HTTP. Verify at startup:
+
+```typescript
+if (typeof window.crypto?.subtle === 'undefined') {
+  throw new Error('crypto.subtle unavailable — app must be served over HTTPS or localhost');
+}
+```
+
+---
+
+## Framework Detection (Env Var Prefix)
+
+Detect from `package.json` before implementation:
+
+| Framework | Env prefix | Detection |
+|---|---|---|
+| Vite (React) | `VITE_` | `vite` in devDependencies |
+| Create React App | `REACT_APP_` | `react-scripts` in dependencies |
+| Next.js | `NEXT_PUBLIC_` | `next` in dependencies |
+
+---
+
+## File Naming Convention (Approach 7)
+
+| Role | Path |
+|---|---|
+| Crypto utilities | `src/services/security/crypto-utils.ts` |
+| AES service | `src/services/security/aes.service.ts` |
+| RSA service | `src/services/security/rsa.service.ts` |
+| RSA key management | `src/services/security/rsa-key.service.ts` |
+| HMAC service | `src/services/security/hmac.service.ts` |
+| Browser storage | `src/services/security/storage.service.ts` |
+| Interceptor | `src/services/security/encryption.interceptor.ts` |
+| Config / feature flags | `src/services/security/encryption-config.ts` |
+| TypeScript types | `src/services/security/types.ts` |
+| ECDH Base64URL util | `src/core/security/ecdh-session/base64url.ts` |
+| ECDH AAD builder | `src/core/security/ecdh-session/aad.ts` |
+| ECDH key pair + derivation | `src/core/security/ecdh-session/ecdhSession.ts` |
+| AES-GCM with AAD | `src/core/security/ecdh-session/aesGcm.ts` |
+| ECDH session service | `src/core/security/ecdh-session/ecdhSessionService.ts` |
+
+---
+
+## Mode A: RSA-OAEP
+
+### Crypto Utilities (`crypto-utils.ts`)
+
+```typescript
+// No Buffer dependency — pure browser APIs
+export const bufferToBase64 = (buffer: ArrayBuffer): string => {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+};
+
+export const base64ToBuffer = (base64: string): ArrayBuffer => {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+};
+
+export const generateNonce = (appId: string): string => {
+  const randomBytes = crypto.getRandomValues(new Uint8Array(8));
+  const hex = Array.from(randomBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+  return `${appId}^${Date.now()}.${hex}`;
+};
+```
+
+### AES Service (`aes.service.ts`)
+
+```typescript
+import { bufferToBase64, base64ToBuffer } from './crypto-utils';
+
+export interface AESKeyMaterial {
+  cryptoKey: CryptoKey;   // for encrypt/decrypt calls
+  rawBytes: Uint8Array;   // for RSA-OAEP wrapping
+}
+
+export const generateAESKey = async (): Promise<AESKeyMaterial> => {
+  const cryptoKey = await crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true,
+    ['encrypt', 'decrypt'],
+  );
+  const rawBytes = new Uint8Array(await crypto.subtle.exportKey('raw', cryptoKey));
+  return { cryptoKey, rawBytes };
+};
+
+// Web Crypto AES-GCM appends the 16-byte auth tag automatically
+export const encryptAESGCM = async (
+  plaintext: string, key: CryptoKey, iv: Uint8Array,
+): Promise<ArrayBuffer> => {
+  const data = new TextEncoder().encode(plaintext);
+  return crypto.subtle.encrypt({ name: 'AES-GCM', iv, tagLength: 128 }, key, data);
+};
+
+export const decryptAESGCM = async (
+  cipherWithTag: ArrayBuffer, key: CryptoKey, iv: Uint8Array,
+): Promise<string> => {
+  // Throws DOMException on auth tag mismatch — treat as tamper detection
+  const plainBuffer = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv, tagLength: 128 }, key, cipherWithTag,
+  );
+  return new TextDecoder().decode(plainBuffer);
+};
+```
+
+### RSA Service (`rsa.service.ts`)
+
+```typescript
+import { base64ToBuffer } from './crypto-utils';
+
+// Input: PEM (strip headers) or raw Base64 DER → SPKI format required by crypto.subtle
+export const importRSAPublicKey = async (pemOrBase64: string): Promise<CryptoKey> => {
+  const base64 = pemOrBase64
+    .replace(/-----BEGIN PUBLIC KEY-----/g, '')
+    .replace(/-----END PUBLIC KEY-----/g, '')
+    .replace(/\s/g, '');
+  return crypto.subtle.importKey(
+    'spki',
+    base64ToBuffer(base64),
+    { name: 'RSA-OAEP', hash: 'SHA-256' },
+    false,
+    ['encrypt'],
+  );
+};
+
+export const encryptRSAOAEP = async (rsaKey: CryptoKey, aesKeyBytes: Uint8Array): Promise<ArrayBuffer> =>
+  crypto.subtle.encrypt({ name: 'RSA-OAEP' }, rsaKey, aesKeyBytes);
+```
+
+### TypeScript Types (`types.ts`)
+
+```typescript
+export interface EncryptedEnvelope {
+  data: string;    // base64(ciphertext + 16-byte GCM auth_tag)
+  key: string;     // base64(RSA-OAEP encrypted AES key bytes)
+  iv: string;      // base64(12-byte IV)
+  nonce: string;   // appId^unix_timestamp_ms.random_hex
+  key_id: string;  // RSA key version identifier
+}
+
+export interface EncryptedResponse {
+  data: string;    // base64(ciphertext + 16-byte GCM auth_tag)
+  iv: string;      // base64(new server-generated 12-byte IV — never the request IV)
+  nonce?: string;
+}
+```
+
+### Request Interceptor Pattern
+
+```typescript
+// src/services/security/encryption.interceptor.ts
+import { generateAESKey, encryptAESGCM, decryptAESGCM } from './aes.service';
+import { encryptRSAOAEP } from './rsa.service';
+import { bufferToBase64, base64ToBuffer, generateNonce } from './crypto-utils';
+import { getRSAPublicKey, getCurrentKeyId, refreshRSAPublicKey } from './rsa-key.service';
+import { ENCRYPTION_ENABLED, EXCLUDED_PATHS, APP_ID, HMAC_ENABLED, HMAC_SECRET } from './encryption-config';
+
+const ENCRYPT_METHODS = new Set(['post', 'put', 'patch']);
+const requestMap = new Map<string, { cryptoKey: CryptoKey; iv: Uint8Array }>();
+
+export const applyProductionEncryptionInterceptor = (axiosInstance: AxiosInstance): void => {
+
+  axiosInstance.interceptors.request.use(async (config) => {
+    if (!ENCRYPTION_ENABLED) return config;
+    if (!config.method || !ENCRYPT_METHODS.has(config.method.toLowerCase())) return config;
+    if (!config.data) return config;
+    if (config.data instanceof FormData) return config;
+    if (EXCLUDED_PATHS.some(path => config.url?.includes(path))) return config;
+
+    const rsaPublicKey = await getRSAPublicKey();
+    const { cryptoKey, rawBytes } = await generateAESKey();
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const nonce = generateNonce(APP_ID);
+    const requestId = crypto.randomUUID();
+
+    const plaintext = typeof config.data === 'string' ? config.data : JSON.stringify(config.data);
+    const cipherWithTag = await encryptAESGCM(plaintext, cryptoKey, iv);
+    const encryptedKey = await encryptRSAOAEP(rsaPublicKey, rawBytes);
+
+    requestMap.set(requestId, { cryptoKey, iv });
+
+    config.data = {
+      data: bufferToBase64(cipherWithTag),
+      key: bufferToBase64(encryptedKey),
+      iv: bufferToBase64(iv),
+      nonce,
+      key_id: getCurrentKeyId(),
+    };
+    config.headers['X-Request-ID'] = requestId;
+
+    if (HMAC_ENABLED && HMAC_SECRET) {
+      const canonical = `${(config.method ?? 'POST').toUpperCase()}|${config.url}|${nonce}|${config.data.data}`;
+      const keyMaterial = await crypto.subtle.importKey(
+        'raw', new TextEncoder().encode(HMAC_SECRET),
+        { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
+      );
+      const sig = await crypto.subtle.sign('HMAC', keyMaterial, new TextEncoder().encode(canonical));
+      config.headers['X-Request-Signature'] = bufferToBase64(sig);
+      config.headers['X-Nonce'] = nonce;
+    }
+    return config;
+  });
+
+  axiosInstance.interceptors.response.use(
+    async (response) => {
+      if (!ENCRYPTION_ENABLED) return response;
+      const requestId = response.config.headers['X-Request-ID'] as string;
+      const mapping = requestMap.get(requestId);
+      if (requestId) requestMap.delete(requestId); // always clean up
+
+      if (!mapping || !response.data?.data || !response.data?.iv) return response;
+
+      try {
+        const responseIv = new Uint8Array(base64ToBuffer(response.data.iv));
+        const cipherWithTag = base64ToBuffer(response.data.data);
+        const plaintext = await decryptAESGCM(cipherWithTag, mapping.cryptoKey, responseIv);
+        response.data = JSON.parse(plaintext);
+      } catch (err: unknown) {
+        if (err instanceof DOMException) {
+          throw new Error('ERR_CRYPTO_TAG_MISMATCH: payload tampered or wrong key');
+        }
+        throw err;
+      }
+      return response;
+    },
+    async (error) => {
+      const requestId = error.config?.headers?.['X-Request-ID'];
+      if (requestId) requestMap.delete(requestId); // cleanup on error
+
+      if (error.response?.status === 401 &&
+          error.response?.data?.error?.code === 'KEY_ID_NOT_FOUND') {
+        await refreshRSAPublicKey();
+        return axiosInstance.request(error.config);
+      }
+      return Promise.reject(error);
+    },
+  );
+};
+```
+
+### RSA Key Service (`rsa-key.service.ts`)
+
+```typescript
+import { importRSAPublicKey } from './rsa.service';
+import { RSA_KEY_ENDPOINT, RSA_KEY_RETRIES } from './encryption-config';
+
+let cachedKey: CryptoKey | null = null;
+let currentKeyId = '';
+
+export const getRSAPublicKey = async (): Promise<CryptoKey> => {
+  if (cachedKey) return cachedKey;
+  return fetchAndCacheRSAPublicKey();
+};
+
+const fetchAndCacheRSAPublicKey = async (retries = RSA_KEY_RETRIES): Promise<CryptoKey> => {
+  for (let i = 1; i <= retries; i++) {
+    try {
+      const res = await fetch(RSA_KEY_ENDPOINT, { credentials: 'include' });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const { public_key, key_id } = await res.json();
+      cachedKey = await importRSAPublicKey(public_key);
+      currentKeyId = key_id;
+      return cachedKey;
+    } catch (err) {
+      if (i === retries) throw new Error(`ERR_RSA_KEY_UNAVAILABLE: ${err}`);
+    }
+  }
+  throw new Error('ERR_RSA_KEY_UNAVAILABLE');
+};
+
+export const refreshRSAPublicKey = async (): Promise<void> => {
+  cachedKey = null;
+  currentKeyId = '';
+  await fetchAndCacheRSAPublicKey();
+};
+
+export const getCurrentKeyId = (): string => currentKeyId;
+```
+
+### Config + Feature Flags (`encryption-config.ts`)
+
+Auto-generated with the correct env prefix for the detected framework:
+
+```typescript
+// Vite:
+export const ENCRYPTION_ENABLED = import.meta.env.VITE_ENCRYPTION_ENABLED === 'true';
+export const RSA_KEY_ENDPOINT = import.meta.env.VITE_RSA_KEY_ENDPOINT ?? '/api/security/public-key';
+export const APP_ID = import.meta.env.VITE_APP_ID ?? 'web-app';
+export const HMAC_ENABLED = import.meta.env.VITE_HMAC_ENABLED === 'true';
+export const HMAC_SECRET = import.meta.env.VITE_HMAC_SECRET ?? '';
+export const RSA_KEY_RETRIES = 3;
+export const EXCLUDED_PATHS: string[] = [];
+```
+
+```typescript
+// CRA: replace VITE_ with REACT_APP_  and import.meta.env with process.env
+// Next.js: replace VITE_ with NEXT_PUBLIC_  and import.meta.env with process.env
+```
+
+### Browser Storage (`storage.service.ts`)
+
+```typescript
+// sessionStorage — cleared on tab close; acceptable for short-lived tokens
+export const setToken = (key: string, value: string): void => sessionStorage.setItem(key, value);
+export const getToken = (key: string): string | null => sessionStorage.getItem(key);
+export const removeToken = (key: string): void => sessionStorage.removeItem(key);
+export const clearAllTokens = (): void => sessionStorage.clear();
+```
+
+> HTTP-only cookie alternative (recommended for auth tokens): backend sets `Set-Cookie: HttpOnly; Secure; SameSite=Strict`.  
+> Configure Axios with `{ withCredentials: true }`. No client-side token storage code needed.
+
+### Module Wiring (`axiosInstance.ts`)
+
+```typescript
+import axios from 'axios';
+import { applyProductionEncryptionInterceptor } from '../services/security/encryption.interceptor';
+import { getRSAPublicKey } from '../services/security/rsa-key.service';
+import { ENCRYPTION_ENABLED } from '../services/security/encryption-config';
+
+const axiosInstance = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL });
+applyProductionEncryptionInterceptor(axiosInstance);
+// ENCRYPTION_INTERCEPTOR_PLACEHOLDER
+
+export default axiosInstance;
+
+// Bootstrap: call in App.tsx or auth provider before first API call
+export const bootstrapEncryption = async (): Promise<void> => {
+  if (ENCRYPTION_ENABLED) await getRSAPublicKey();
+};
+```
+
+### .env Files
+
+```
+VITE_ENCRYPTION_ENABLED=true
+VITE_RSA_KEY_ENDPOINT=https://<your-api-host>/api/security/public-key
+VITE_APP_ID=com.yourapp.web
+VITE_HMAC_ENABLED=false
+VITE_HMAC_SECRET=
+```
+
+Set `VITE_ENCRYPTION_ENABLED=false` in `.env.development` and `true` in `.env.production`.
+
+---
+
+## Mode B: ECDH-Session
+
+Use when integrating with ECDH-Session / HDFC-LI partner APIs.  
+Web Crypto API natively supports ECDH + HKDF — no manual RFC 5869 HMAC chain required.  
+Session key derived once per session from ECDH + HKDF-SHA256; IV is random per request.
+
+### ECDH-Session Questions (Additional, all blocking)
+
+Ask before implementation — no safe defaults:
+1. **Session init endpoint URL** — e.g. `POST <API_BASE_URL>/api/security/session/init`
+2. **HKDF info prefix** — default `HDFC-LI-Session:v1`
+3. **AAD field order** — default `{"api_ver":"v1","device_id":"<deviceId>","key_id":"<keyId>"}` (alphabetical, no spaces)
+4. **API version string** for AAD `api_ver` — default `v1`
+
+### Base64URL Utility (`base64url.ts`)
+
+```typescript
+export const toBase64URL = (buffer: ArrayBuffer): string => {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+};
+
+export const fromBase64URL = (str: string): ArrayBuffer => {
+  const b64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = b64.padEnd(b64.length + (4 - (b64.length % 4)) % 4, '=');
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+};
+```
+
+### AAD Builder (`aad.ts`)
+
+Fixed alphabetical key order — never use `JSON.stringify`:
+
+```typescript
+export const buildAAD = (apiVersion: string, deviceId: string, keyId: string): ArrayBuffer =>
+  new TextEncoder().encode(
+    `{"api_ver":"${apiVersion}","device_id":"${deviceId}","key_id":"${keyId}"}`
+  );
+```
+
+### ECDH Key Pair + HKDF Session Key (`ecdhSession.ts`)
+
+Web Crypto API handles HKDF natively in one `deriveKey` call:
+
+```typescript
+import { toBase64URL, fromBase64URL } from './base64url';
+
+export const generateECDHKeyPair = async (): Promise<{ privateKey: CryptoKey; publicKeyBase64URL: string }> => {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits'],
+  );
+  const publicKeyBytes = await crypto.subtle.exportKey('raw', keyPair.publicKey);
+  return { privateKey: keyPair.privateKey, publicKeyBase64URL: toBase64URL(publicKeyBytes) };
+};
+
+export const computeSessionAESKey = async (
+  privateKey: CryptoKey,
+  serverPublicKeyBase64URL: string,
+  saltBase64URL: string,
+  keyId: string,
+  deviceId: string,
+  infoPrefix = 'HDFC-LI-Session:v1',
+): Promise<CryptoKey> => {
+  const serverPublicKey = await crypto.subtle.importKey(
+    'raw', fromBase64URL(serverPublicKeyBase64URL),
+    { name: 'ECDH', namedCurve: 'P-256' }, false, [],
+  );
+  const sharedBits = await crypto.subtle.deriveBits(
+    { name: 'ECDH', public: serverPublicKey }, privateKey, 256,
+  );
+  const hkdfKey = await crypto.subtle.importKey('raw', sharedBits, { name: 'HKDF' }, false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF', hash: 'SHA-256',
+      salt: fromBase64URL(saltBase64URL),
+      info: new TextEncoder().encode(`${infoPrefix}|${keyId}|${deviceId}`),
+    },
+    hkdfKey,
+    { name: 'AES-GCM', length: 256 },
+    false,         // derived key is non-extractable — never stored
+    ['encrypt', 'decrypt'],
+  );
+};
+```
+
+### AES-GCM with AAD (`aesGcm.ts`)
+
+Format: `Base64URL(IV || ciphertext || authTag)` — same as the React Native ECDH-Session skill:
+
+```typescript
+import { toBase64URL, fromBase64URL } from './base64url';
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+export const encryptAESGCM = async (plaintext: string, aesKey: CryptoKey, aad: ArrayBuffer): Promise<string> => {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const data = new TextEncoder().encode(plaintext);
+  const cipherWithTag = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, aesKey, data,
+  );
+  const combined = new Uint8Array(IV_BYTES + cipherWithTag.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(cipherWithTag), IV_BYTES);
+  return toBase64URL(combined.buffer);
+};
+
+export const decryptAESGCM = async (payloadBase64URL: string, aesKey: CryptoKey, aad: ArrayBuffer): Promise<string> => {
+  const combined = new Uint8Array(fromBase64URL(payloadBase64URL));
+  if (combined.length < IV_BYTES + TAG_BYTES + 1) throw new Error('ERR_CRYPTO_PAYLOAD_TOO_SHORT');
+  const iv = combined.slice(0, IV_BYTES);
+  const cipherWithTag = combined.slice(IV_BYTES);
+  // DOMException thrown on auth tag failure — caller must handle as tamper detection
+  const plainBuffer = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, aesKey, cipherWithTag,
+  );
+  return new TextDecoder().decode(plainBuffer);
+};
+```
+
+### ECDH Session Service (`ecdhSessionService.ts`)
+
+```typescript
+import { generateECDHKeyPair, computeSessionAESKey } from './ecdhSession';
+
+const STORAGE_KEY = 'ecdh_session';
+
+export interface SessionMaterial {
+  privateKeyJwk: JsonWebKey;
+  serverPublicKeyBase64URL: string;
+  saltBase64URL: string;
+  keyId: string;
+  deviceId: string;
+  apiVersion: string;
+}
+
+let _sessionAESKey: CryptoKey | null = null;
+let _sessionMaterial: SessionMaterial | null = null;
+
+export const getSessionAESKey = (): CryptoKey => {
+  if (!_sessionAESKey) throw new Error('ERR_SESSION_NOT_INITIALIZED');
+  return _sessionAESKey;
+};
+
+export const getSessionMaterial = (): SessionMaterial => {
+  if (!_sessionMaterial) throw new Error('ERR_SESSION_NOT_INITIALIZED');
+  return _sessionMaterial;
+};
+
+const getOrCreateDeviceId = (): string => {
+  let id = sessionStorage.getItem('device_id');
+  if (!id) { id = crypto.randomUUID(); sessionStorage.setItem('device_id', id); }
+  return id;
+};
+
+export const restoreSession = async (): Promise<boolean> => {
+  const raw = sessionStorage.getItem(STORAGE_KEY);
+  if (!raw) return false;
+  const mat: SessionMaterial = JSON.parse(raw);
+  const privateKey = await crypto.subtle.importKey(
+    'jwk', mat.privateKeyJwk, { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits'],
+  );
+  _sessionMaterial = mat;
+  _sessionAESKey = await computeSessionAESKey(
+    privateKey, mat.serverPublicKeyBase64URL, mat.saltBase64URL, mat.keyId, mat.deviceId,
+  );
+  return true;
+};
+
+export const initSession = async (sessionInitUrl: string, apiVersion = 'v1'): Promise<void> => {
+  const deviceId = getOrCreateDeviceId();
+  const { privateKey, publicKeyBase64URL } = await generateECDHKeyPair();
+
+  const res = await fetch(sessionInitUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'include',
+    body: JSON.stringify({ clientPublicKey: publicKeyBase64URL }),
+  });
+  if (!res.ok) throw new Error(`ERR_SESSION_INIT_FAILED: HTTP ${res.status}`);
+  const { serverPublicKey, salt, keyId } = await res.json();
+
+  _sessionAESKey = await computeSessionAESKey(privateKey, serverPublicKey, salt, keyId, deviceId);
+
+  const mat: SessionMaterial = {
+    privateKeyJwk: await crypto.subtle.exportKey('jwk', privateKey),
+    serverPublicKeyBase64URL: serverPublicKey,
+    saltBase64URL: salt, keyId, deviceId, apiVersion,
+  };
+  _sessionMaterial = mat;
+  sessionStorage.setItem(STORAGE_KEY, JSON.stringify(mat));
+};
+
+export const clearSession = (): void => {
+  _sessionAESKey = null;
+  _sessionMaterial = null;
+  sessionStorage.removeItem(STORAGE_KEY);
+  sessionStorage.removeItem('device_id');
+};
+```
+
+### ECDH-Session Interceptor Pattern
+
+```typescript
+// Add to axiosClient.ts
+import { getSessionAESKey, getSessionMaterial } from '../security/ecdh-session/ecdhSessionService';
+import { buildAAD } from '../security/ecdh-session/aad';
+import { encryptAESGCM, decryptAESGCM } from '../security/ecdh-session/aesGcm';
+
+instance.interceptors.request.use(async (config) => {
+  if (!ENCRYPTION_ENABLED) return config;
+  if (!config.method || !ENCRYPT_METHODS.has(config.method.toLowerCase())) return config;
+  if (!config.data) return config;
+  const aesKey = getSessionAESKey();
+  const mat = getSessionMaterial();
+  const aad = buildAAD(mat.apiVersion, mat.deviceId, mat.keyId);
+  const plaintext = typeof config.data === 'string' ? config.data : JSON.stringify(config.data);
+  config.data = { encryptedRequest: await encryptAESGCM(plaintext, aesKey, aad), keyId: mat.keyId };
+  config.headers['X-Device-ID'] = mat.deviceId;
+  config.headers['X-Timestamp'] = new Date().toISOString();
+  return config;
+});
+
+instance.interceptors.response.use(
+  async (response) => {
+    if (!ENCRYPTION_ENABLED || !response.data?.encryptedResponse) return response;
+    const aesKey = getSessionAESKey();
+    const mat = getSessionMaterial();
+    const aad = buildAAD(mat.apiVersion, mat.deviceId, mat.keyId);
+    try {
+      response.data = JSON.parse(await decryptAESGCM(response.data.encryptedResponse, aesKey, aad));
+    } catch (err: unknown) {
+      if (err instanceof DOMException) {
+        clearSession();
+        throw new Error('ERR_CRYPTO_TAG_MISMATCH: session invalid — re-init required');
+      }
+      throw err;
+    }
+    return response;
+  },
+  (error) => Promise.reject(error),
+);
+```
+
+### App Bootstrap (ECDH-Session)
+
+```typescript
+// In App.tsx or auth provider:
+import { restoreSession, initSession } from './core/security/ecdh-session/ecdhSessionService';
+
+async function bootstrapSecurity(): Promise<void> {
+  const restored = await restoreSession();
+  if (!restored) await initSession(import.meta.env.VITE_SESSION_INIT_URL);
+}
+```
+
+---
+
+## Key Differences from Approach 1 (React Basic Web Crypto)
+
+| Feature | Approach 1 | Approach 7 |
+|---|---|---|
+| Response decryption | No | Yes — per-request key map |
+| RSA key management | Manual/static | Auto fetch/cache/retry service |
+| Per-request key isolation | No | Yes — `CryptoKey` map per requestId |
+| Browser-safe storage | Not included | `sessionStorage` + HTTP-only cookie guidance |
+| ECDH-Session mode | No | Yes — ECDH P-256 + HKDF-SHA256 + AES-GCM with AAD |
+| HMAC signing | No | Yes — Web Crypto HMAC-SHA256 |
+| Framework detection | No | Yes — Vite/CRA/Next.js prefix |
+| `crypto.subtle` availability check | No | Yes — HTTPS gate at startup |
+
+---
+
+## Security Rules (Approach 7)
+
+- Use `crypto.getRandomValues` for all random material — never `Math.random()`.
+- Never reuse IV values.
+- `DOMException` from `crypto.subtle.decrypt` = auth tag failure — trigger secure logout, do not retry.
+- Never store AES keys, IVs, or derived ECDH session keys in any storage.
+- ECDH-Session: private key exported as JWK to `sessionStorage` only; derived AES key never stored.
+- Never fall back to `localStorage` for tokens or session material.
+- Enforce HTTPS — `crypto.subtle` is unavailable on plain HTTP origins.
+- `tsconfig.json` must include `"lib": ["DOM"]` for `crypto.subtle` typings.
+- No `crypto-js`, `node-forge`, or Buffer polyfill — use `Uint8Array` + `TextEncoder`/`TextDecoder` + `btoa`/`atob`.
+- CORS: ensure backend `Access-Control-Allow-Headers` includes `X-Request-ID`, `X-Nonce`, `X-Request-Signature`, `X-Device-ID`, `X-Timestamp`.
+
+---
+
+## Build Command
+
+```bash
+npm run build
+```