wolfronix-sdk 1.3.1 → 2.3.0

package/dist/index.d.ts

@@ -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 };