wolfronix-sdk 2.4.1 → 2.4.2

package/README.md

@@ -1,117 +1,296 @@
 # wolfronix-sdk
 
-Official JavaScript/TypeScript SDK for Wolfronix - Zero-knowledge encryption made simple.
+Official JavaScript/TypeScript SDK for **Wolfronix** — Zero-knowledge encryption made simple.
 
 [![npm version](https://badge.fury.io/js/wolfronix-sdk.svg)](https://www.npmjs.com/package/wolfronix-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- 🔐 **Zero-Knowledge Encryption** - Keys generated client-side, never leave your device
-- 🏢 **Enterprise Ready** - Seamless integration with your existing storage
-- 🚀 **Simple API** - Encrypt files in 2 lines of code
-- 📦 **TypeScript Native** - Full type definitions included
-- 🌐 **Universal** - Works in Node.js 18+ and modern browsers
-- 🔄 **Auto Retry** - Built-in retry logic with exponential backoff
+- 🔐 **Zero-Knowledge Encryption** — Keys generated client-side, never leave your device
+- 🏢 **Enterprise Ready** — Seamless integration with your existing storage (Supabase, MongoDB, MySQL, Firebase, PostgreSQL)
+- 🚀 **Simple API** — Encrypt files in 2 lines of code
+- 📦 **TypeScript Native** — Full type definitions included
+- 🌐 **Universal** — Works in Node.js 18+ and modern browsers
+- 🔄 **Auto Retry** — Built-in retry logic with exponential backoff
+- 💬 **E2E Chat** — Hybrid RSA+AES message encryption out of the box
+- 📡 **Real-Time Streaming** — WebSocket-based streaming encryption/decryption
 
-## Backend Integration (Enterprise Mode)
+---
 
-To use this SDK, your backend API must implement 3 storage endpoints that Wolfronix will call:
+## Installation
 
-1.  **POST** `/wolfronix/files/upload` - Store encrypted file + metadata
-2.  **GET** `/wolfronix/files/{id}` - Retrieve metadata
-3.  **GET** `/wolfronix/files/{id}/data` - Retrieve encrypted file blob
+### npm / yarn / pnpm
 
-Wolfronix handles all encryption/decryption keys and logic; you only handle the encrypted blobs.
+```bash
+npm install wolfronix-sdk
+```
 
+### Browser (Script Tag)
 
-## Installation
+For plain HTML/JS apps, use the pre-built browser bundle:
 
-```bash
-npm install wolfronix-sdk
-# or
-yarn add wolfronix-sdk
-# or
-pnpm add wolfronix-sdk
+```html
+<script src="https://unpkg.com/wolfronix-sdk/dist/index.global.js"></script>
+<script>
+  // All exports are available on the global `Wolfronix` object
+  const wfx = new Wolfronix.default({
+    baseUrl: 'https://your-server:9443',
+    clientId: 'your-client-id',
+    wolfronixKey: 'your-api-key'
+  });
+</script>
 ```
 
+Or host the bundle yourself — copy `node_modules/wolfronix-sdk/dist/index.global.js` to your project.
+
+---
+
 ## Quick Start
 
-```typescript
+### 1. Connect to Wolfronix Server
+
+```javascript
 import Wolfronix from 'wolfronix-sdk';
 
-// Initialize client
 const wfx = new Wolfronix({
-  baseUrl: 'https://your-wolfronix-server:5002',
-  clientId: 'your-enterprise-client-id',
-  wolfronixKey: 'your-api-key'
+  baseUrl: 'https://your-wolfronix-server:9443',
+  clientId: 'your-client-id',        // From enterprise registration
+  wolfronixKey: 'your-api-key',       // From enterprise registration
 });
+```
 
-// Register (First time only) - Generates keys client-side
-await wfx.register('user@example.com', 'password123');
+### 2. Register a User (First Time Only)
+
+```javascript
+await wfx.register('user@example.com', 'securePassword');
+// Generates RSA key pair client-side, wraps private key with password,
+// sends only the ENCRYPTED key to the server (zero-knowledge)
+```
 
-// Login (Subsequent visits)
-await wfx.login('user@example.com', 'password123');
+### 3. Login (Subsequent Visits)
 
-// Encrypt a file
-const result = await wfx.encrypt(file);
+```javascript
+await wfx.login('user@example.com', 'securePassword');
+// Fetches encrypted private key from server, decrypts it locally
+```
+
+### 4. Encrypt a File
+
+```javascript
+const result = await wfx.encrypt(file); // File or Blob
 console.log('Encrypted! File ID:', result.file_id);
+console.log('Time:', result.enc_time_ms, 'ms');
+```
 
-// Decrypt a file
-const decrypted = await wfx.decrypt(result.file_id);
+### 5. Decrypt a File
+
+```javascript
+const blob = await wfx.decrypt(result.file_id);
+// blob is a standard Blob — display, download, or process it
 ```
 
-## Usage Examples
+### 6. List & Delete Files
+
+```javascript
+const { files } = await wfx.listFiles();
+await wfx.deleteFile(files[0].file_id);
+```
+
+---
+
+## Step-by-Step Integration Guide
+
+### Plain HTML/JS Web App
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Secure App</title>
+  <script src="https://unpkg.com/wolfronix-sdk/dist/index.global.js"></script>
+</head>
+<body>
+  <input type="email" id="email" placeholder="Email">
+  <input type="password" id="password" placeholder="Password">
+  <button onclick="doLogin()">Login</button>
+  <button onclick="doRegister()">Register</button>
+
+  <hr>
+
+  <input type="file" id="fileInput">
+  <button onclick="doEncrypt()">Encrypt & Upload</button>
+  <button onclick="doList()">List Files</button>
+
+  <div id="output"></div>
+
+  <script>
+    const wfx = new Wolfronix.default({
+      baseUrl: 'https://your-server:9443',
+      clientId: 'your-client-id',
+      wolfronixKey: 'your-api-key'
+    });
+
+    async function doRegister() {
+      const email = document.getElementById('email').value;
+      const pass = document.getElementById('password').value;
+      await wfx.register(email, pass);
+      alert('Registered! Keys generated.');
+    }
+
+    async function doLogin() {
+      const email = document.getElementById('email').value;
+      const pass = document.getElementById('password').value;
+      await wfx.login(email, pass);
+      alert('Logged in! User: ' + wfx.getUserId());
+    }
+
+    async function doEncrypt() {
+      const file = document.getElementById('fileInput').files[0];
+      const result = await wfx.encrypt(file);
+      document.getElementById('output').textContent =
+        'Encrypted! ID: ' + result.file_id + ' (' + result.enc_time_ms + 'ms)';
+    }
+
+    async function doList() {
+      const { files } = await wfx.listFiles();
+      document.getElementById('output').textContent =
+        files.map(f => f.original_name + ' (ID: ' + f.file_id + ')').join('\n');
+    }
+  </script>
+</body>
+</html>
+```
 
-### Browser (React, Vue, Angular, etc.)
+### React / Next.js
 
 ```typescript
 import Wolfronix from 'wolfronix-sdk';
 
-const wfx = new Wolfronix('https://wolfronix-server:5002');
+// Create a singleton instance (e.g., in a context or module)
+const wfx = new Wolfronix({
+  baseUrl: process.env.NEXT_PUBLIC_WOLFRONIX_URL!,
+  clientId: process.env.NEXT_PUBLIC_WOLFRONIX_CLIENT_ID!,
+  wolfronixKey: process.env.NEXT_PUBLIC_WOLFRONIX_KEY!,
+});
 
-// With file input
-const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
-  const file = event.target.files?.[0];
-  if (!file) return;
+export default function FileVault() {
+  const [files, setFiles] = useState([]);
 
-  try {
-    const { file_id } = await wfx.encrypt(file);
-    console.log('File encrypted with your private key:', file_id);
-  } catch (error) {
-    console.error('Encryption failed:', error);
-  }
-};
-
-// Download decrypted file
-const handleDownload = async (fileId: string, filename: string) => {
-  const blob = await wfx.decrypt(fileId);
-  
-  // Create download link
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = filename;
-  a.click();
-  URL.revokeObjectURL(url);
-};
+  const handleLogin = async (email: string, password: string) => {
+    await wfx.login(email, password);
+    const { files } = await wfx.listFiles();
+    setFiles(files);
+  };
+
+  const handleUpload = async (file: File) => {
+    const result = await wfx.encrypt(file);
+    console.log('Encrypted:', result.file_id);
+    // Refresh file list
+    const { files } = await wfx.listFiles();
+    setFiles(files);
+  };
+
+  const handleDownload = async (fileId: string, filename: string) => {
+    const blob = await wfx.decrypt(fileId);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={(e) => handleUpload(e.target.files![0])} />
+      {files.map(f => (
+        <div key={f.file_id}>
+          {f.original_name}
+          <button onClick={() => handleDownload(f.file_id, f.original_name)}>
+            Download
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
 ```
 
-### Node.js
+### React Hook
+
+```typescript
+// hooks/useWolfronix.ts
+import { useState, useCallback, useMemo } from 'react';
+import Wolfronix, { FileInfo } from 'wolfronix-sdk';
+
+export function useWolfronix(baseUrl: string, clientId?: string, wolfronixKey?: string) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [files, setFiles] = useState<FileInfo[]>([]);
+
+  const client = useMemo(
+    () => new Wolfronix({ baseUrl, clientId, wolfronixKey }),
+    [baseUrl, clientId, wolfronixKey]
+  );
+
+  const login = useCallback(async (email: string, password: string) => {
+    setIsLoading(true);
+    try {
+      return await client.login(email, password);
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  const encrypt = useCallback(async (file: File) => {
+    setIsLoading(true);
+    try {
+      const result = await client.encrypt(file);
+      const { files } = await client.listFiles();
+      setFiles(files);
+      return result;
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  const decrypt = useCallback(async (fileId: string) => {
+    setIsLoading(true);
+    try {
+      return await client.decrypt(fileId);
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  return { client, isLoading, error, files, login, encrypt, decrypt };
+}
+```
+
+### Node.js (Server-Side)
 
 ```typescript
 import Wolfronix from 'wolfronix-sdk';
 import * as fs from 'fs';
 
 const wfx = new Wolfronix({
-  baseUrl: 'https://wolfronix-server:5002',
+  baseUrl: 'https://wolfronix-server:9443',
   clientId: 'your-client-id',
   wolfronixKey: 'your-api-key',
-  insecure: true // For self-signed certs in development
+  insecure: true  // For self-signed certs in development
 });
 
 async function main() {
-  // Login
   await wfx.login('user@example.com', 'password123');
 
   // Encrypt a file
@@ -131,291 +310,364 @@ async function main() {
 main();
 ```
 
-### 💬 E2E Encrypted Chat Integration
+---
 
-Turn any chat app into a secure, end-to-end encrypted messenger in minutes.
+## API Reference
+
+### Constructor
+
+```typescript
+new Wolfronix(config: WolfronixConfig | string)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | **required** | Wolfronix server URL |
+| `clientId` | `string` | `''` | Enterprise client ID |
+| `wolfronixKey` | `string` | `''` | API key (sent as `X-Wolfronix-Key` header) |
+| `timeout` | `number` | `30000` | Request timeout in ms (file uploads bypass this) |
+| `retries` | `number` | `3` | Max retry attempts with exponential backoff |
+| `insecure` | `boolean` | `false` | Skip SSL verification (Node.js only) |
+
+You can also pass just a URL string: `new Wolfronix('https://server:9443')`
+
+---
+
+### Authentication
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `register(email, password)` | `Promise<AuthResponse>` | Generate RSA keys + register (first time) |
+| `login(email, password)` | `Promise<AuthResponse>` | Fetch & unwrap keys (subsequent logins) |
+| `setToken(token, userId?)` | `void` | Set auth token directly (for custom auth) |
+| `logout()` | `void` | Clear keys and session from memory |
+| `isAuthenticated()` | `boolean` | Check if user is logged in |
+| `getUserId()` | `string \| null` | Get current user ID |
+| `hasPrivateKey()` | `boolean` | Check if RSA private key is loaded in memory |
+
+---
+
+### File Operations
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `encrypt(file, filename?)` | `Promise<EncryptResponse>` | Encrypt and store a file |
+| `decrypt(fileId, role?)` | `Promise<Blob>` | Decrypt file → Blob (for browser display/download) |
+| `decryptToBuffer(fileId, role?)` | `Promise<ArrayBuffer>` | Decrypt file → ArrayBuffer (for Node.js) |
+| `getFileKey(fileId)` | `Promise<KeyPartResponse>` | Get encrypted key_part_a (advanced use) |
+| `listFiles()` | `Promise<ListFilesResponse>` | List user's encrypted files |
+| `deleteFile(fileId)` | `Promise<DeleteResponse>` | Delete an encrypted file |
+
+**`EncryptResponse` fields:**
+```typescript
+{
+  status: string;
+  file_id: string;
+  file_size: number;
+  enc_time_ms: number;
+  // Detailed timing breakdown:
+  upload_ms?: number;    // Network upload time
+  read_ms?: number;      // Server file read time
+  encrypt_ms?: number;   // AES-256-GCM encryption time
+  store_ms?: number;     // Storage write time
+}
+```
+
+---
+
+### E2E Chat Encryption
+
+Turn any chat app into a secure, end-to-end encrypted messenger.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getPublicKey(userId, clientId?)` | `Promise<CryptoKey>` | Fetch a user's RSA public key |
+| `encryptMessage(text, recipientId)` | `Promise<string>` | Encrypt text for a recipient (returns JSON packet) |
+| `decryptMessage(packetString)` | `Promise<string>` | Decrypt a received message packet |
 
 **Sender (Alice):**
 ```typescript
-// 1. Get Bob's Public Key & Encrypt Message
-const securePacket = await wfx.encryptMessage("Secret details at 5 PM", "bob_user_id");
+const securePacket = await wfx.encryptMessage("Secret meeting at 5 PM", "bob_user_id");
 
-// 2. Send 'securePacket' string via your normal chat API (Socket.io, Firebase, etc.)
-chatSocket.emit('message', {
-  to: 'bob',
-  text: securePacket // Valid JSON string
-});
+// Send via your regular chat backend (Socket.io, Firebase, etc.)
+chatSocket.emit('message', { to: 'bob', text: securePacket });
 ```
 
 **Recipient (Bob):**
 ```typescript
-// 1. Receive message from chat server
 chatSocket.on('message', async (msg) => {
-  try {
-    // 2. Decrypt locally with Bob's Private Key
-    const plainText = await wfx.decryptMessage(msg.text);
-    console.log("Decrypted:", plainText);
-  } catch (err) {
-    console.error("Could not decrypt message");
-  }
+  const plainText = await wfx.decryptMessage(msg.text);
+  console.log("Decrypted:", plainText);
 });
 ```
 
-**Features:**
-- **Hybrid Encryption:** Uses AES-256 for messages + RSA-2048 for key exchange (Fast & Secure).
-- **Zero-Knowledge:** Your chat server only sees encrypted packets.
-- **Universal:** Works with any backend (Socket.io, Firebase, PostgreSQL, etc).
+---
 
-## API Reference
+### Server-Side Message Encryption
 
-### Constructor
+For messages that need **server-managed** encryption (Layer 3/4 dual-key split):
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `serverEncrypt(message, options?)` | `Promise<ServerEncryptResult>` | Encrypt a message server-side |
+| `serverDecrypt(params)` | `Promise<string>` | Decrypt a server-encrypted message |
+| `serverEncryptBatch(messages, options?)` | `Promise<ServerBatchEncryptResult>` | Batch encrypt multiple messages |
+| `serverDecryptBatchItem(item)` | `Promise<string>` | Decrypt a single batch item |
 
 ```typescript
-new Wolfronix(config: WolfronixConfig | string)
+// Encrypt
+const encrypted = await wfx.serverEncrypt("Confidential data", { layer: 4 });
+
+// Decrypt
+const original = await wfx.serverDecrypt({
+  encryptedMessage: encrypted.encrypted_message,
+  nonce: encrypted.nonce,
+  keyPartA: encrypted.key_part_a,
+  messageTag: encrypted.message_tag
+});
+
+// Batch encrypt
+const batch = await wfx.serverEncryptBatch([
+  { id: 'msg1', message: 'Hello' },
+  { id: 'msg2', message: 'World' }
+], { layer: 4 });
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `baseUrl` | string | required | Wolfronix server URL |
-| `clientId` | string | `''` | Enterprise client ID |
-| `wolfronixKey` | string | `''` | API key for X-Wolfronix-Key auth |
-| `timeout` | number | `30000` | Request timeout (ms) |
-| `retries` | number | `3` | Max retry attempts |
-| `insecure` | boolean | `false` | Skip SSL verification (Node.js: uses undici Agent, or set `NODE_TLS_REJECT_UNAUTHORIZED=0`) |
+---
 
-### Authentication
+### Real-Time Streaming Encryption
 
-| Method | Description |
-|--------|-------------|
-| `register(email, password)` | Register new user |
-| `login(email, password)` | Login existing user |
-| `setToken(token, userId?)` | Set auth token directly |
-| `logout()` | Clear authentication |
-| `isAuthenticated()` | Check auth status |
-| `getUserId()` | Get current user ID |
+For encrypting/decrypting live data streams (audio, video, real-time feeds) via WebSocket:
 
-### File Operations
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createStream(direction, streamKey?)` | `Promise<WolfronixStream>` | Open a streaming encryption session |
 
-| Method | Description |
-|--------|-------------|
-| `encrypt(file, filename?)` | Encrypt and store file |
-| `decrypt(fileId, role?)` | Decrypt file (zero-knowledge, returns Blob) |
-| `decryptToBuffer(fileId, role?)` | Decrypt file (zero-knowledge, returns ArrayBuffer) |
-| `getFileKey(fileId)` | Get encrypted key_part_a for client-side decryption |
-| `listFiles()` | List user's encrypted files |
-| `deleteFile(fileId)` | Delete encrypted file |
+```typescript
+// Encrypt stream
+const stream = await wfx.createStream('encrypt');
+stream.onData((chunk, seq) => sendToRecipient(chunk));
+stream.onError((err) => console.error(err));
 
-### E2E Chat Encryption
+const processed = await stream.send('data to encrypt');       // Text
+const processed2 = await stream.sendBinary(audioChunk);       // Binary
 
-| Method | Description |
-|--------|-------------|
-| `getPublicKey(userId, clientId?)` | Fetch a user's RSA public key |
-| `encryptMessage(text, recipientId)` | Encrypt text for a recipient (returns packet string) |
-| `decryptMessage(packetString)` | Decrypt a received message packet |
+// Save these for the recipient to decrypt:
+console.log('Key:', stream.keyPartA, 'Tag:', stream.streamTag);
 
-### Utility
+const summary = await stream.end();
+console.log('Chunks processed:', summary.chunksProcessed);
 
-| Method | Description |
-|--------|-------------|
-| `getMetrics()` | Get encryption/decryption stats |
-| `healthCheck()` | Check server availability |
+// Decrypt stream (recipient)
+const decStream = await wfx.createStream('decrypt', {
+  keyPartA: senderKeyPartA,
+  streamTag: senderStreamTag
+});
+decStream.onData((chunk, seq) => playAudio(chunk));
+```
 
-## Security Architecture (v2.0)
+---
 
-### Zero-Knowledge Decryption Flow
+### Admin API (Enterprise Client Management)
 
-In v2.0, the private key **never leaves the client**. The decrypt flow works as follows:
+For managing enterprise clients programmatically:
 
+```typescript
+import { WolfronixAdmin } from 'wolfronix-sdk';
+
+const admin = new WolfronixAdmin({
+  baseUrl: 'https://your-server:9443',
+  adminKey: 'your-admin-api-key'
+});
 ```
-Client                              Wolfronix Server
-  │                                       │
-  │  GET /files/{id}/key                  │
-  │──────────────────────────────────────>│
-  │  { key_part_a: "<RSA-OAEP encrypted>"}│
-  │<──────────────────────────────────────│
-  │                                       │
-  │  [Decrypt key_part_a locally          │
-  │   with private key (RSA-OAEP)]        │
-  │                                       │
-  │  POST /files/{id}/decrypt             │
-  │  { decrypted_key_a: "<base64>" }      │
-  │──────────────────────────────────────>│
-  │                                       │
-  │  [Server combines key_a + key_b,      │
-  │   decrypts with AES-256-GCM]         │
-  │                                       │
-  │  <decrypted file bytes>               │
-  │<──────────────────────────────────────│
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `registerClient(params)` | `Promise<RegisterClientResponse>` | Register a new enterprise client |
+| `listClients()` | `Promise<ListClientsResponse>` | List all registered clients |
+| `getClient(clientId)` | `Promise<EnterpriseClient>` | Get details for a specific client |
+| `updateClient(clientId, params)` | `Promise<UpdateClientResponse>` | Update client configuration |
+| `deactivateClient(clientId)` | `Promise<DeactivateClientResponse>` | Deactivate (revoke) a client |
+| `healthCheck()` | `Promise<boolean>` | Check server health |
+
+```typescript
+// Register a new client with Supabase connector
+const result = await admin.registerClient({
+  client_id: 'acme_corp',
+  client_name: 'Acme Corporation',
+  db_type: 'supabase',           // or: mongodb, mysql, firebase, postgresql, custom_api
+  db_config: JSON.stringify({
+    supabase_url: 'https://xxx.supabase.co',
+    supabase_service_key: 'eyJ...'
+  })
+});
+
+console.log('Wolfronix Key:', result.wolfronix_key); // Give this to the client
 ```
 
-### Key Security Properties
-- **AES-256-GCM** authenticated encryption (tamper-proof, replaces AES-CTR)
-- **RSA-OAEP** with SHA-256 for key transport (replaces PKCS1v15)
-- **API key authentication** via `X-Wolfronix-Key` header on all endpoints
-- **Configurable CORS** origins (no more wildcard `*`)
-- **Dual-key split**: AES key split in half, each half encrypted with different RSA key
-- **Zero-knowledge key wrapping**: Private keys wrapped with PBKDF2-derived keys, server never sees raw private keys
+---
+
+### Utility Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getMetrics()` | `Promise<MetricsResponse>` | Get encryption/decryption stats |
+| `healthCheck()` | `Promise<boolean>` | Check if server is reachable |
+
+---
 
 ## Error Handling
 
-The SDK provides specific error types for different scenarios:
+The SDK provides typed error classes for different failure scenarios:
 
 ```typescript
-import Wolfronix, { 
-  WolfronixError,
-  AuthenticationError,
-  FileNotFoundError,
-  PermissionDeniedError,
-  NetworkError,
-  ValidationError
+import Wolfronix, {
+  WolfronixError,        // Base error class
+  AuthenticationError,   // Invalid credentials or expired session
+  FileNotFoundError,     // File doesn't exist
+  PermissionDeniedError, // Not authorized for this file
+  NetworkError,          // Server unreachable
+  ValidationError        // Invalid input parameters
 } from 'wolfronix-sdk';
 
 try {
   await wfx.encrypt(file);
 } catch (error) {
   if (error instanceof AuthenticationError) {
-    // Token expired, redirect to login
-    router.push('/login');
+    // Redirect to login
   } else if (error instanceof FileNotFoundError) {
-    // File doesn't exist
-    showToast('File not found');
-  } else if (error instanceof PermissionDeniedError) {
-    // Not your file
-    showToast('Access denied');
+    // File was deleted
   } else if (error instanceof NetworkError) {
-    // Server unreachable
-    showToast('Connection failed. Retrying...');
+    // Server down — SDK already retried 3 times
   } else if (error instanceof ValidationError) {
-    // Invalid input
-    showToast(error.message);
-  } else {
-    // Unknown error
-    console.error('Unexpected error:', error);
+    // Bad input (e.g., missing file, empty message)
   }
 }
 ```
 
-## TypeScript Support
+All errors include:
+- `error.message` — Human-readable description
+- `error.code` — Machine-readable error code
+- `error.statusCode` — HTTP status code (if applicable)
+- `error.details` — Server error details (if available)
 
-The SDK is written in TypeScript and includes full type definitions:
+---
 
-```typescript
-import Wolfronix, {
-  WolfronixConfig,
-  AuthResponse,
-  EncryptResponse,
-  FileInfo,
-  ListFilesResponse,
-  MetricsResponse
-} from 'wolfronix-sdk';
+## Security Architecture
 
-// All methods are fully typed
-const config: WolfronixConfig = {
-  baseUrl: 'https://server:5002',
-  clientId: 'my-client',
-  wolfronixKey: 'my-api-key'
-};
+### How It Works
 
-const wfx = new Wolfronix(config);
-const response: EncryptResponse = await wfx.encrypt(file);
+```
+                    Your App                          Wolfronix Engine
+                ┌──────────────┐              ┌────────────────────────┐
+  User ──────▶  │  SDK (Browser)│ ──────────▶  │  AES-256-GCM Encrypt  │
+  Password      │              │   HTTPS       │  RSA Dual-Key Split   │
+                │  RSA Keys    │              │  RBAC Masking          │
+                │  (client-    │  ◀──────────  │                        │
+                │   side only) │   Encrypted   │  Stores NOTHING       │
+                └──────────────┘   Blob Only   │  decryptable alone    │
+                                               └────────────────────────┘
+                                                          │
+                                                          ▼
+                                               ┌────────────────────────┐
+                                               │  Your Database          │
+                                               │  (Supabase, MongoDB,   │
+                                               │   PostgreSQL, etc.)    │
+                                               │  Stores encrypted      │
+                                               │  blobs only            │
+                                               └────────────────────────┘
 ```
 
-## React Hook Example
-
-```typescript
-// useWolfronix.ts
-import { useState, useCallback, useMemo } from 'react';
-import Wolfronix, { FileInfo as WolfronixFile } from 'wolfronix-sdk';
-
-export function useWolfronix(baseUrl: string, clientId?: string, wolfronixKey?: string) {
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [files, setFiles] = useState<WolfronixFile[]>([]);
+### Key Security Properties
 
-  const client = useMemo(() => new Wolfronix({ baseUrl, clientId, wolfronixKey }), [baseUrl, clientId, wolfronixKey]);
+| Property | Implementation |
+|----------|---------------|
+| **Encryption** | AES-256-GCM (authenticated, tamper-proof) |
+| **Key Transport** | RSA-OAEP with SHA-256 |
+| **Key Wrapping** | PBKDF2 (100,000 iterations) + AES-GCM |
+| **Dual-Key Split** | AES key split in half; each half encrypted with different RSA key |
+| **Zero-Knowledge** | Private keys wrapped client-side; server never sees raw keys |
+| **Auth** | API key (`X-Wolfronix-Key`) + zero-knowledge login |
 
-  const login = useCallback(async (email: string, password: string) => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      return await client.login(email, password);
-    } catch (e) {
-      setError(e as Error);
-      throw e;
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client]);
+### Zero-Knowledge Decryption Flow
 
-  const encrypt = useCallback(async (file: File) => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      const result = await client.encrypt(file);
-      await refreshFiles();
-      return result;
-    } catch (e) {
-      setError(e as Error);
-      throw e;
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client]);
+```
+Client                              Wolfronix Server
+  │                                       │
+  │  GET /files/{id}/key                  │
+  │──────────────────────────────────────►│
+  │  { key_part_a: "<RSA-OAEP encrypted>"}│
+  │◄──────────────────────────────────────│
+  │                                       │
+  │  [Decrypt key_part_a locally          │
+  │   with private key (RSA-OAEP)]        │
+  │                                       │
+  │  POST /files/{id}/decrypt             │
+  │  { decrypted_key_a: "<base64>" }      │
+  │──────────────────────────────────────►│
+  │                                       │
+  │  [Server combines key_a + key_b,      │
+  │   decrypts with AES-256-GCM]          │
+  │                                       │
+  │  <decrypted file bytes>               │
+  │◄──────────────────────────────────────│
+```
 
-  const decrypt = useCallback(async (fileId: string) => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      return await client.decrypt(fileId);
-    } catch (e) {
-      setError(e as Error);
-      throw e;
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client]);
+---
 
-  const refreshFiles = useCallback(async () => {
-    const { files } = await client.listFiles();
-    setFiles(files);
-  }, [client]);
+## TypeScript Types
 
-  return {
-    client,
-    isLoading,
-    error,
-    files,
-    login,
-    encrypt,
-    decrypt,
-    refreshFiles
-  };
-}
+All interfaces are exported for full type safety:
 
-// Usage in component
-function FileManager() {
-  const { files, encrypt, decrypt, isLoading } = useWolfronix(
-    'https://wolfronix:5002',
-    'my-client-id'
-  );
+```typescript
+import Wolfronix, {
+  // Config
+  WolfronixConfig,
+  WolfronixAdminConfig,
 
-  return (
-    <div>
-      <input type="file" onChange={(e) => encrypt(e.target.files![0])} />
-      {isLoading && <Spinner />}
-      {files.map(f => (
-        <div key={f.file_id} onClick={() => decrypt(f.file_id)}>
-          {f.original_name}
-        </div>
-      ))}
-    </div>
-  );
-}
+  // Responses
+  AuthResponse,
+  EncryptResponse,
+  FileInfo,
+  ListFilesResponse,
+  DeleteResponse,
+  KeyPartResponse,
+  MetricsResponse,
+
+  // Message Encryption
+  EncryptMessagePacket,
+  ServerEncryptResult,
+  ServerDecryptParams,
+  ServerBatchEncryptResult,
+
+  // Streaming
+  WolfronixStream,
+  StreamSession,
+  StreamChunk,
+
+  // Enterprise Admin
+  WolfronixAdmin,
+  RegisterClientRequest,
+  RegisterClientResponse,
+  EnterpriseClient,
+  ListClientsResponse,
+  UpdateClientRequest,
+  UpdateClientResponse,
+  DeactivateClientResponse,
+
+  // Error Classes
+  WolfronixError,
+  AuthenticationError,
+  FileNotFoundError,
+  PermissionDeniedError,
+  NetworkError,
+  ValidationError
+} from 'wolfronix-sdk';
 ```
 
-## Real-World Use Cases
+---
 
-Wolfronix can be integrated into **any application** that handles sensitive data:
+## Real-World Use Cases
 
 | Industry | Application | How Wolfronix Helps |
 |----------|------------|---------------------|
@@ -424,22 +676,51 @@ Wolfronix can be integrated into **any application** that handles sensitive data
 | ⚖️ **Legal** | Contracts, case files | Zero-knowledge confidential storage |
 | ☁️ **Cloud Storage** | Drive/Dropbox alternatives | Encrypted file vault with user-owned keys |
 | 🏢 **Enterprise** | HR records, internal docs | Per-employee encryption isolation |
+| 💬 **Messaging** | Chat attachments | Encrypted file sharing + E2E messages |
 | 🎓 **Education** | Exam papers, student data | Tamper-proof academic records |
-| 💬 **Messaging** | File attachments | Encrypted file sharing in chat apps |
-| 🛒 **E-commerce** | Order docs, payment receipts | PCI-compliant document storage |
+
+---
+
+## Backend Integration
+
+Your backend only needs to store/retrieve encrypted blobs. Wolfronix handles all crypto.
+
+### Supported Connectors (Managed)
+
+| Connector | `db_type` | What You Provide |
+|-----------|-----------|-----------------|
+| Supabase | `supabase` | `supabase_url`, `supabase_service_key` |
+| MongoDB | `mongodb` | `connection_string`, `database` |
+| MySQL | `mysql` | `host`, `port`, `user`, `password`, `database` |
+| Firebase | `firebase` | `project_id`, `service_account_key` |
+| PostgreSQL | `postgresql` | `host`, `port`, `user`, `password`, `database` |
+| Custom API | `custom_api` | Your own REST endpoint |
+
+### Custom API Mode
+
+If using `custom_api`, your backend must implement these endpoints:
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| `POST` | `/wolfronix/files/upload` | Store encrypted file + metadata |
+| `GET` | `/wolfronix/files/{id}` | Retrieve file metadata |
+| `GET` | `/wolfronix/files/{id}/data` | Retrieve encrypted blob |
+| `DELETE` | `/wolfronix/files/{id}` | Delete file |
+
+---
 
 ## Requirements
 
-- Node.js 18+ (for Node.js usage)
-- Modern browser with Web Crypto API support
+- **Node.js:** 18+ (for server-side usage)
+- **Browser:** Any modern browser with Web Crypto API (Chrome, Firefox, Safari, Edge)
+- **Wolfronix Engine:** v2.4.1+
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
+MIT License — see [LICENSE](./LICENSE) for details.
 
 ## Links
 
-- [Documentation](https://wolfronix.com/docs)
-- [API Reference](https://wolfronix.com/docs/api)
+- [npm Package](https://www.npmjs.com/package/wolfronix-sdk)
 - [GitHub](https://github.com/wolfronix/sdk-javascript)
 - [Report Issues](https://github.com/wolfronix/sdk-javascript/issues)

package/dist/index.d.mts

@@ -3,7 +3,7 @@
  * Zero-knowledge encryption made simple
  *
  * @package @wolfronix/sdk
- * @version 2.4.0
+ * @version 2.4.2
  */
 interface WolfronixConfig {
     /** Wolfronix server base URL */

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * Zero-knowledge encryption made simple
  *
  * @package @wolfronix/sdk
- * @version 2.4.0
+ * @version 2.4.2
  */
 interface WolfronixConfig {
     /** Wolfronix server base URL */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolfronix-sdk",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Official Wolfronix SDK for JavaScript/TypeScript - Zero-knowledge encryption made simple",
   "main": "dist/index.js",
   "module": "dist/index.mjs",