wolfronix-sdk 1.3.1 → 2.3.0

package/README.md

@@ -11,7 +11,7 @@ Official JavaScript/TypeScript SDK for Wolfronix - Zero-knowledge encryption mad
 - 🏢 **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 16+ and modern browsers
+- 🌐 **Universal** - Works in Node.js 18+ and modern browsers
 - 🔄 **Auto Retry** - Built-in retry logic with exponential backoff
 
 ## Backend Integration (Enterprise Mode)
@@ -43,7 +43,8 @@ import Wolfronix from 'wolfronix-sdk';
 // Initialize client
 const wfx = new Wolfronix({
   baseUrl: 'https://your-wolfronix-server:5002',
-  clientId: 'your-enterprise-client-id'
+  clientId: 'your-enterprise-client-id',
+  wolfronixKey: 'your-api-key'
 });
 
 // Register (First time only) - Generates keys client-side
@@ -105,6 +106,7 @@ import * as fs from 'fs';
 const wfx = new Wolfronix({
   baseUrl: 'https://wolfronix-server:5002',
   clientId: 'your-client-id',
+  wolfronixKey: 'your-api-key',
   insecure: true // For self-signed certs in development
 });
 
@@ -126,12 +128,6 @@ async function main() {
   fs.writeFileSync('decrypted.pdf', Buffer.from(decrypted));
 }
 
-main();
-// Decrypt and save
-  const decrypted = await wfx.decryptToBuffer(file_id);
-  fs.writeFileSync('decrypted.pdf', Buffer.from(decrypted));
-}
-
 main();
 ```
 
@@ -182,9 +178,10 @@ new Wolfronix(config: WolfronixConfig | string)
 |--------|------|---------|-------------|
 | `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 |
+| `insecure` | boolean | `false` | Skip SSL verification (Node.js: uses undici Agent, or set `NODE_TLS_REJECT_UNAUTHORIZED=0`) |
 
 ### Authentication
 
@@ -202,8 +199,9 @@ new Wolfronix(config: WolfronixConfig | string)
 | Method | Description |
 |--------|-------------|
 | `encrypt(file, filename?)` | Encrypt and store file |
-| `decrypt(fileId)` | Decrypt file (returns Blob) |
-| `decryptToBuffer(fileId)` | Decrypt file (returns ArrayBuffer) |
+| `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 |
 
@@ -211,7 +209,7 @@ new Wolfronix(config: WolfronixConfig | string)
 
 | Method | Description |
 |--------|-------------|
-| `getPublicKey(userId)` | Fetch a user's RSA public key |
+| `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 |
 
@@ -222,6 +220,42 @@ new Wolfronix(config: WolfronixConfig | string)
 | `getMetrics()` | Get encryption/decryption stats |
 | `healthCheck()` | Check server availability |
 
+## Security Architecture (v2.0)
+
+### Zero-Knowledge Decryption Flow
+
+In v2.0, the private key **never leaves the client**. The decrypt flow works as follows:
+
+```
+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>               │
+  │<──────────────────────────────────────│
+```
+
+### 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
+
 ## Error Handling
 
 The SDK provides specific error types for different scenarios:
@@ -278,7 +312,8 @@ import Wolfronix, {
 // All methods are fully typed
 const config: WolfronixConfig = {
   baseUrl: 'https://server:5002',
-  clientId: 'my-client'
+  clientId: 'my-client',
+  wolfronixKey: 'my-api-key'
 };
 
 const wfx = new Wolfronix(config);
@@ -292,12 +327,12 @@ const response: EncryptResponse = await wfx.encrypt(file);
 import { useState, useCallback, useMemo } from 'react';
 import Wolfronix, { FileInfo as WolfronixFile } from 'wolfronix-sdk';
 
-export function useWolfronix(baseUrl: string, clientId?: string) {
+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[]>([]);
 
-  const client = useMemo(() => new Wolfronix({ baseUrl, clientId }), [baseUrl, clientId]);
+  const client = useMemo(() => new Wolfronix({ baseUrl, clientId, wolfronixKey }), [baseUrl, clientId, wolfronixKey]);
 
   const login = useCallback(async (email: string, password: string) => {
     setIsLoading(true);
@@ -395,7 +430,7 @@ Wolfronix can be integrated into **any application** that handles sensitive data
 
 ## Requirements
 
-- Node.js 16+ (for Node.js usage)
+- Node.js 18+ (for Node.js usage)
 - Modern browser with Web Crypto API support
 
 ## License

package/dist/index.d.mts

@@ -3,13 +3,15 @@
  * Zero-knowledge encryption made simple
  *
  * @package @wolfronix/sdk
- * @version 1.3.0
+ * @version 2.3.0
  */
 interface WolfronixConfig {
     /** Wolfronix server base URL */
     baseUrl: string;
     /** Your enterprise client ID (optional for self-hosted) */
     clientId?: string;
+    /** API key for authentication (X-Wolfronix-Key header) */
+    wolfronixKey?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
     /** Retry failed requests (default: 3) */
@@ -44,6 +46,11 @@ interface DeleteResponse {
     success: boolean;
     message: string;
 }
+interface KeyPartResponse {
+    file_id: string;
+    key_part_a: string;
+    message: string;
+}
 interface MetricsResponse {
     success: boolean;
     total_encryptions: number;
@@ -56,6 +63,51 @@ interface EncryptMessagePacket {
     iv: string;
     msg: string;
 }
+interface ServerEncryptResult {
+    /** Base64-encoded ciphertext */
+    encrypted_message: string;
+    /** Base64-encoded nonce */
+    nonce: string;
+    /** Base64-encoded client key half (Layer 4) or full key (Layer 3) */
+    key_part_a: string;
+    /** Tag for server's key_part_b lookup (Layer 4 only, empty for Layer 3) */
+    message_tag: string;
+    /** Unix timestamp */
+    timestamp: number;
+}
+interface ServerDecryptParams {
+    /** Base64-encoded ciphertext (from ServerEncryptResult) */
+    encryptedMessage: string;
+    /** Base64-encoded nonce */
+    nonce: string;
+    /** Base64-encoded key_part_a */
+    keyPartA: string;
+    /** Message tag for Layer 4 (omit for Layer 3) */
+    messageTag?: string;
+}
+interface ServerBatchEncryptResult {
+    results: Array<{
+        id: string;
+        encrypted_message: string;
+        nonce: string;
+        seq: number;
+    }>;
+    /** Shared key_part_a for the batch */
+    key_part_a: string;
+    /** Shared batch tag for key_part_b lookup (Layer 4) */
+    batch_tag: string;
+    timestamp: number;
+}
+interface StreamSession {
+    /** Client's key half (encrypt direction only) */
+    keyPartA?: string;
+    /** Stream tag for the session */
+    streamTag?: string;
+}
+interface StreamChunk {
+    data: string;
+    seq: number;
+}
 declare class WolfronixError extends Error {
     readonly code: string;
     readonly statusCode?: number;
@@ -85,6 +137,8 @@ declare class Wolfronix {
     private publicKey;
     private privateKey;
     private publicKeyPEM;
+    /** Expose private key status for testing */
+    hasPrivateKey(): boolean;
     /**
      * Create a new Wolfronix client
      *
@@ -156,7 +210,14 @@ declare class Wolfronix {
      */
     encrypt(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<EncryptResponse>;
     /**
-     * Decrypt and retrieve a file
+     * Decrypt and retrieve a file using zero-knowledge flow.
+     *
+     * Flow:
+     * 1. GET /api/v1/files/{id}/key → encrypted key_part_a
+     * 2. Decrypt key_part_a client-side with private key (RSA-OAEP)
+     * 3. POST /api/v1/files/{id}/decrypt with { decrypted_key_a } in body
+     *
+     * The private key NEVER leaves the client.
      *
      * @example
      * ```typescript
@@ -169,11 +230,18 @@ declare class Wolfronix {
      * fs.writeFileSync('decrypted.pdf', buffer);
      * ```
      */
-    decrypt(fileId: string): Promise<Blob>;
+    decrypt(fileId: string, role?: string): Promise<Blob>;
     /**
-     * Decrypt and return as ArrayBuffer
+     * Decrypt and return as ArrayBuffer (zero-knowledge flow)
      */
-    decryptToBuffer(fileId: string): Promise<ArrayBuffer>;
+    decryptToBuffer(fileId: string, role?: string): Promise<ArrayBuffer>;
+    /**
+     * Fetch the encrypted key_part_a for a file (for client-side decryption)
+     *
+     * @param fileId The file ID to get the key for
+     * @returns KeyPartResponse containing the RSA-OAEP encrypted key_part_a
+     */
+    getFileKey(fileId: string): Promise<KeyPartResponse>;
     /**
      * List all encrypted files for current user
      *
@@ -196,8 +264,9 @@ declare class Wolfronix {
     /**
      * Get another user's public key (for E2E encryption)
      * @param userId The ID of the recipient
+     * @param clientId Optional: override the configured clientId
      */
-    getPublicKey(userId: string): Promise<string>;
+    getPublicKey(userId: string, clientId?: string): Promise<string>;
     /**
      * Encrypt a short text message for a recipient (Hybrid Encryption: RSA + AES)
      * Returns a secure JSON string (packet) to send via chat
@@ -212,6 +281,105 @@ declare class Wolfronix {
      * @param packetJson The secure JSON string packet
      */
     decryptMessage(packetJson: string): Promise<string>;
+    /**
+     * Encrypt a text message via the Wolfronix server (dual-key split).
+     * The server generates an AES key, encrypts the message, and splits the key —
+     * you get key_part_a, the server holds key_part_b.
+     *
+     * Use this for server-managed message encryption (e.g., stored encrypted messages).
+     * For true E2E (where the server never sees plaintext), use encryptMessage() instead.
+     *
+     * @param message The plaintext message to encrypt
+     * @param options.layer 3 = AES only (full key returned), 4 = dual-key split (default)
+     *
+     * @example
+     * ```typescript
+     * const result = await wfx.serverEncrypt('Hello, World!');
+     * // Store result.encrypted_message, result.nonce, result.key_part_a, result.message_tag
+     * ```
+     */
+    serverEncrypt(message: string, options?: {
+        layer?: number;
+    }): Promise<ServerEncryptResult>;
+    /**
+     * Decrypt a message previously encrypted via serverEncrypt().
+     *
+     * @param params The encrypted message data (from serverEncrypt result)
+     * @returns The decrypted plaintext message
+     *
+     * @example
+     * ```typescript
+     * const text = await wfx.serverDecrypt({
+     *   encryptedMessage: result.encrypted_message,
+     *   nonce: result.nonce,
+     *   keyPartA: result.key_part_a,
+     *   messageTag: result.message_tag,
+     * });
+     * ```
+     */
+    serverDecrypt(params: ServerDecryptParams): Promise<string>;
+    /**
+     * Encrypt multiple messages in a single round-trip (batch).
+     * All messages share one AES key (different nonce per message).
+     * Efficient for chat history encryption or bulk operations.
+     *
+     * @param messages Array of { id, message } objects (max 100)
+     * @param options.layer 3 or 4 (default: 4)
+     *
+     * @example
+     * ```typescript
+     * const result = await wfx.serverEncryptBatch([
+     *   { id: 'msg1', message: 'Hello' },
+     *   { id: 'msg2', message: 'World' },
+     * ]);
+     * // result.results[0].encrypted_message, result.key_part_a, result.batch_tag
+     * ```
+     */
+    serverEncryptBatch(messages: Array<{
+        id: string;
+        message: string;
+    }>, options?: {
+        layer?: number;
+    }): Promise<ServerBatchEncryptResult>;
+    /**
+     * Decrypt a single message from a batch result.
+     * Uses the shared key_part_a and batch_tag from the batch result.
+     *
+     * @param batchResult The batch encrypt result
+     * @param index The index of the message to decrypt
+     */
+    serverDecryptBatchItem(batchResult: ServerBatchEncryptResult, index: number): Promise<string>;
+    /**
+     * Create a streaming encryption/decryption session over WebSocket.
+     * Data flows in real-time: send chunks, receive encrypted/decrypted chunks back.
+     *
+     * @param direction 'encrypt' for plaintext→ciphertext, 'decrypt' for reverse
+     * @param streamKey Required for decrypt — the key_part_a and stream_tag from the encrypt session
+     *
+     * @example
+     * ```typescript
+     * // Encrypt stream
+     * const stream = await wfx.createStream('encrypt');
+     * stream.onData((chunk, seq) => console.log('Encrypted chunk', seq));
+     * stream.send('Hello chunk 1');
+     * stream.send('Hello chunk 2');
+     * const summary = await stream.end();
+     * // Save stream.keyPartA and stream.streamTag for decryption
+     *
+     * // Decrypt stream
+     * const dStream = await wfx.createStream('decrypt', {
+     *   keyPartA: stream.keyPartA!,
+     *   streamTag: stream.streamTag!,
+     * });
+     * dStream.onData((chunk, seq) => console.log('Decrypted:', chunk));
+     * dStream.send(encryptedChunk1);
+     * await dStream.end();
+     * ```
+     */
+    createStream(direction: 'encrypt' | 'decrypt', streamKey?: {
+        keyPartA: string;
+        streamTag: string;
+    }): Promise<WolfronixStream>;
     /**
      * Get encryption/decryption metrics
      *
@@ -227,6 +395,77 @@ declare class Wolfronix {
      */
     healthCheck(): Promise<boolean>;
 }
+type StreamDataCallback = (data: string, seq: number) => void;
+type StreamErrorCallback = (error: Error) => void;
+/**
+ * Real-time streaming encryption/decryption over WebSocket.
+ * Each chunk is individually encrypted with AES-256-GCM using counter-based nonces.
+ *
+ * @example
+ * ```typescript
+ * const stream = await wfx.createStream('encrypt');
+ * stream.onData((chunk, seq) => sendToRecipient(chunk));
+ * stream.onError((err) => console.error(err));
+ * await stream.send('audio chunk data...');
+ * const summary = await stream.end();
+ * ```
+ */
+declare class WolfronixStream {
+    private readonly config;
+    private readonly userId;
+    private ws;
+    private dataCallbacks;
+    private errorCallbacks;
+    private pendingChunks;
+    private seqCounter;
+    /** Client's key half (available after encrypt stream init) */
+    keyPartA: string | null;
+    /** Stream tag (available after encrypt stream init) */
+    streamTag: string | null;
+    /** @internal */
+    constructor(config: Required<WolfronixConfig>, userId: string);
+    /** @internal Connect and initialize the stream session */
+    connect(direction: 'encrypt' | 'decrypt', streamKey?: {
+        keyPartA: string;
+        streamTag: string;
+    }): Promise<void>;
+    /**
+     * Send a data chunk for encryption/decryption.
+     * Returns a promise that resolves with the processed (encrypted/decrypted) chunk.
+     *
+     * @param data String or base64-encoded binary data
+     * @returns The processed chunk (base64-encoded)
+     */
+    send(data: string): Promise<string>;
+    /**
+     * Send raw binary data for encryption/decryption.
+     *
+     * @param buffer ArrayBuffer or Uint8Array
+     * @returns The processed chunk (base64-encoded)
+     */
+    sendBinary(buffer: ArrayBuffer | Uint8Array): Promise<string>;
+    /**
+     * Register a callback for incoming data chunks.
+     *
+     * @param callback Called with (base64Data, sequenceNumber) for each chunk
+     */
+    onData(callback: StreamDataCallback): void;
+    /**
+     * Register a callback for stream errors.
+     */
+    onError(callback: StreamErrorCallback): void;
+    /**
+     * End the stream session. Returns the total number of chunks processed.
+     */
+    end(): Promise<{
+        chunksProcessed: number;
+    }>;
+    /**
+     * Close the stream immediately without sending an end message.
+     */
+    close(): void;
+    private isBase64;
+}
 /**
  * Create a new Wolfronix client
  *
@@ -242,4 +481,4 @@ declare class Wolfronix {
  */
 declare function createClient(config: WolfronixConfig | string): Wolfronix;
 
-export { type AuthResponse, AuthenticationError, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type FileInfo, FileNotFoundError, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, ValidationError, Wolfronix, type WolfronixConfig, WolfronixError, createClient, Wolfronix as default };
+export { type AuthResponse, AuthenticationError, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type FileInfo, FileNotFoundError, type KeyPartResponse, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type ServerBatchEncryptResult, type ServerDecryptParams, type ServerEncryptResult, type StreamChunk, type StreamSession, ValidationError, Wolfronix, type WolfronixConfig, WolfronixError, WolfronixStream, createClient, Wolfronix as default };