wolfronix-sdk 2.4.2 → 2.4.4

package/dist/index.d.mts

@@ -3,7 +3,7 @@
  * Zero-knowledge encryption made simple
  *
  * @package @wolfronix/sdk
- * @version 2.4.2
+ * @version 2.4.4
  */
 interface WolfronixConfig {
     /** Wolfronix server base URL */
@@ -25,6 +25,14 @@ interface AuthResponse {
     token: string;
     message: string;
 }
+interface RecoverySetup {
+    recoveryPhrase: string;
+    recoveryWords: string[];
+}
+interface RegisterOptions {
+    enableRecovery?: boolean;
+    recoveryPhrase?: string;
+}
 interface EncryptResponse {
     status: string;
     file_id: string;
@@ -39,6 +47,36 @@ interface EncryptResponse {
     /** Any extra fields from the server response */
     [key: string]: unknown;
 }
+interface ChunkedEncryptResult {
+    upload_id: string;
+    filename: string;
+    total_chunks: number;
+    chunk_size_bytes: number;
+    uploaded_chunks: number;
+    chunk_file_ids: string[];
+    complete: boolean;
+}
+interface ResumableUploadState {
+    upload_id: string;
+    filename: string;
+    file_size: number;
+    chunk_size_bytes: number;
+    total_chunks: number;
+    uploaded_chunks: number[];
+    chunk_file_ids: string[];
+    created_at: number;
+    updated_at: number;
+}
+interface ResumableEncryptOptions {
+    filename?: string;
+    chunkSizeBytes?: number;
+    existingState?: ResumableUploadState;
+    onProgress?: (uploadedChunks: number, totalChunks: number) => void;
+}
+interface ChunkedDecryptManifest {
+    filename: string;
+    chunk_file_ids: string[];
+}
 interface FileInfo {
     file_id: string;
     original_name: string;
@@ -71,6 +109,50 @@ interface EncryptMessagePacket {
     iv: string;
     msg: string;
 }
+interface GroupEncryptPacket {
+    v: 1;
+    type: 'group_sender_key';
+    sender_id: string;
+    group_id: string;
+    timestamp: number;
+    ciphertext: string;
+    iv: string;
+    recipient_keys: Record<string, string>;
+}
+interface PfsPreKeyBundle {
+    protocol: 'wfx-dr-v1';
+    user_id?: string;
+    ratchet_pub_jwk: JsonWebKey;
+    created_at: number;
+}
+interface PfsMessagePacket {
+    v: 1;
+    type: 'pfs_ratchet';
+    session_id: string;
+    n: number;
+    pn: number;
+    ratchet_pub_jwk: JsonWebKey;
+    iv: string;
+    ciphertext: string;
+    timestamp: number;
+}
+interface PfsSessionState {
+    protocol: 'wfx-dr-v1';
+    session_id: string;
+    role: 'initiator' | 'responder';
+    root_key: string;
+    send_chain_key: string;
+    recv_chain_key: string;
+    send_count: number;
+    recv_count: number;
+    prev_send_count: number;
+    my_ratchet_private_jwk: JsonWebKey;
+    my_ratchet_public_jwk: JsonWebKey;
+    their_ratchet_public_jwk: JsonWebKey;
+    skipped_keys: Record<string, string>;
+    created_at: number;
+    updated_at: number;
+}
 interface ServerEncryptResult {
     /** Base64-encoded ciphertext */
     encrypted_message: string;
@@ -211,6 +293,9 @@ declare class Wolfronix {
     private publicKey;
     private privateKey;
     private publicKeyPEM;
+    private pfsIdentityPrivateJwk;
+    private pfsIdentityPublicJwk;
+    private pfsSessions;
     /** Expose private key status for testing */
     hasPrivateKey(): boolean;
     /**
@@ -229,6 +314,11 @@ declare class Wolfronix {
     private request;
     private sleep;
     private ensureAuthenticated;
+    private toBlob;
+    private ensurePfsIdentity;
+    private getPfsSession;
+    private ratchetForSend;
+    private ratchetForReceive;
     /**
      * Register a new user
      *
@@ -237,7 +327,7 @@ declare class Wolfronix {
      * const { user_id, token } = await wfx.register('user@example.com', 'password123');
      * ```
      */
-    register(email: string, password: string): Promise<AuthResponse>;
+    register(email: string, password: string, options?: RegisterOptions): Promise<AuthResponse & Partial<RecoverySetup>>;
     /**
      * Login with existing credentials
      *
@@ -247,6 +337,20 @@ declare class Wolfronix {
      * ```
      */
     login(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Recover account keys using a 24-word recovery phrase and set a new password.
+     * Returns a fresh local auth session if recovery succeeds.
+     */
+    recoverAccount(email: string, recoveryPhrase: string, newPassword: string): Promise<AuthResponse>;
+    /**
+     * Rotates long-term RSA identity keys and re-wraps with password (+ optional recovery phrase).
+     * Use this periodically to reduce long-term key exposure.
+     */
+    rotateIdentityKeys(password: string, recoveryPhrase?: string): Promise<{
+        success: boolean;
+        message: string;
+        recoveryPhrase?: string;
+    }>;
     /**
      * Set authentication token directly (useful for server-side apps)
      *
@@ -283,6 +387,15 @@ declare class Wolfronix {
      * ```
      */
     encrypt(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<EncryptResponse>;
+    /**
+     * Resumable large-file encryption upload.
+     * Splits a file into chunks (default 10MB) and uploads each chunk independently.
+     * If upload fails mid-way, pass the returned state as `existingState` to resume.
+     */
+    encryptResumable(file: File | Blob | ArrayBuffer | Uint8Array, options?: ResumableEncryptOptions): Promise<{
+        result: ChunkedEncryptResult;
+        state: ResumableUploadState;
+    }>;
     /**
      * Decrypt and retrieve a file using zero-knowledge flow.
      *
@@ -309,6 +422,15 @@ declare class Wolfronix {
      * Decrypt and return as ArrayBuffer (zero-knowledge flow)
      */
     decryptToBuffer(fileId: string, role?: string): Promise<ArrayBuffer>;
+    /**
+     * Decrypts and reassembles a chunked upload produced by `encryptResumable`.
+     */
+    decryptChunkedToBuffer(manifest: ChunkedDecryptManifest, role?: string): Promise<ArrayBuffer>;
+    /**
+     * Decrypts and reassembles a chunked upload into a Blob.
+     * This is a browser-friendly alias over `decryptChunkedToBuffer`.
+     */
+    decryptChunkedManifest(manifest: ChunkedDecryptManifest, role?: string): Promise<Blob>;
     /**
      * Fetch the encrypted key_part_a for a file (for client-side decryption)
      *
@@ -355,6 +477,42 @@ declare class Wolfronix {
      * @param packetJson The secure JSON string packet
      */
     decryptMessage(packetJson: string): Promise<string>;
+    /**
+     * Create/share a pre-key bundle for Double Ratchet PFS session setup.
+     * Exchange this bundle out-of-band with the peer.
+     */
+    createPfsPreKeyBundle(): Promise<PfsPreKeyBundle>;
+    /**
+     * Initialize a local PFS ratchet session from peer bundle.
+     * Both sides must call this with opposite `asInitiator` values.
+     */
+    initPfsSession(sessionId: string, peerBundle: PfsPreKeyBundle, asInitiator: boolean): Promise<PfsSessionState>;
+    /**
+     * Export session state for persistence (e.g., localStorage/DB).
+     */
+    exportPfsSession(sessionId: string): PfsSessionState;
+    /**
+     * Import session state from storage.
+     */
+    importPfsSession(session: PfsSessionState): void;
+    /**
+     * Encrypt a message using Double Ratchet session state.
+     */
+    pfsEncryptMessage(sessionId: string, plaintext: string): Promise<PfsMessagePacket>;
+    /**
+     * Decrypt a Double Ratchet packet for a session.
+     * Handles basic out-of-order delivery through skipped message keys.
+     */
+    pfsDecryptMessage(sessionId: string, packet: PfsMessagePacket | string): Promise<string>;
+    /**
+     * Group message encryption using sender-key fanout:
+     * message encrypted once with AES key, AES key wrapped for each group member with their RSA public key.
+     */
+    encryptGroupMessage(text: string, groupId: string, recipientIds: string[]): Promise<string>;
+    /**
+     * Decrypt a packet produced by `encryptGroupMessage`.
+     */
+    decryptGroupMessage(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 —
@@ -615,4 +773,4 @@ declare class WolfronixAdmin {
     healthCheck(): Promise<boolean>;
 }
 
-export { type AuthResponse, AuthenticationError, type DBType, type DeactivateClientResponse, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type EnterpriseClient, type FileInfo, FileNotFoundError, type KeyPartResponse, type ListClientsResponse, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type RegisterClientRequest, type RegisterClientResponse, type ServerBatchEncryptResult, type ServerDecryptParams, type ServerEncryptResult, type StreamChunk, type StreamSession, type UpdateClientRequest, type UpdateClientResponse, ValidationError, Wolfronix, WolfronixAdmin, type WolfronixAdminConfig, type WolfronixConfig, WolfronixError, WolfronixStream, createClient, Wolfronix as default };
+export { type AuthResponse, AuthenticationError, type ChunkedDecryptManifest, type ChunkedEncryptResult, type DBType, type DeactivateClientResponse, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type EnterpriseClient, type FileInfo, FileNotFoundError, type GroupEncryptPacket, type KeyPartResponse, type ListClientsResponse, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type PfsMessagePacket, type PfsPreKeyBundle, type PfsSessionState, type RecoverySetup, type RegisterClientRequest, type RegisterClientResponse, type RegisterOptions, type ResumableEncryptOptions, type ResumableUploadState, type ServerBatchEncryptResult, type ServerDecryptParams, type ServerEncryptResult, type StreamChunk, type StreamSession, type UpdateClientRequest, type UpdateClientResponse, ValidationError, Wolfronix, WolfronixAdmin, type WolfronixAdminConfig, type WolfronixConfig, WolfronixError, WolfronixStream, createClient, Wolfronix as default };

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * Zero-knowledge encryption made simple
  *
  * @package @wolfronix/sdk
- * @version 2.4.2
+ * @version 2.4.4
  */
 interface WolfronixConfig {
     /** Wolfronix server base URL */
@@ -25,6 +25,14 @@ interface AuthResponse {
     token: string;
     message: string;
 }
+interface RecoverySetup {
+    recoveryPhrase: string;
+    recoveryWords: string[];
+}
+interface RegisterOptions {
+    enableRecovery?: boolean;
+    recoveryPhrase?: string;
+}
 interface EncryptResponse {
     status: string;
     file_id: string;
@@ -39,6 +47,36 @@ interface EncryptResponse {
     /** Any extra fields from the server response */
     [key: string]: unknown;
 }
+interface ChunkedEncryptResult {
+    upload_id: string;
+    filename: string;
+    total_chunks: number;
+    chunk_size_bytes: number;
+    uploaded_chunks: number;
+    chunk_file_ids: string[];
+    complete: boolean;
+}
+interface ResumableUploadState {
+    upload_id: string;
+    filename: string;
+    file_size: number;
+    chunk_size_bytes: number;
+    total_chunks: number;
+    uploaded_chunks: number[];
+    chunk_file_ids: string[];
+    created_at: number;
+    updated_at: number;
+}
+interface ResumableEncryptOptions {
+    filename?: string;
+    chunkSizeBytes?: number;
+    existingState?: ResumableUploadState;
+    onProgress?: (uploadedChunks: number, totalChunks: number) => void;
+}
+interface ChunkedDecryptManifest {
+    filename: string;
+    chunk_file_ids: string[];
+}
 interface FileInfo {
     file_id: string;
     original_name: string;
@@ -71,6 +109,50 @@ interface EncryptMessagePacket {
     iv: string;
     msg: string;
 }
+interface GroupEncryptPacket {
+    v: 1;
+    type: 'group_sender_key';
+    sender_id: string;
+    group_id: string;
+    timestamp: number;
+    ciphertext: string;
+    iv: string;
+    recipient_keys: Record<string, string>;
+}
+interface PfsPreKeyBundle {
+    protocol: 'wfx-dr-v1';
+    user_id?: string;
+    ratchet_pub_jwk: JsonWebKey;
+    created_at: number;
+}
+interface PfsMessagePacket {
+    v: 1;
+    type: 'pfs_ratchet';
+    session_id: string;
+    n: number;
+    pn: number;
+    ratchet_pub_jwk: JsonWebKey;
+    iv: string;
+    ciphertext: string;
+    timestamp: number;
+}
+interface PfsSessionState {
+    protocol: 'wfx-dr-v1';
+    session_id: string;
+    role: 'initiator' | 'responder';
+    root_key: string;
+    send_chain_key: string;
+    recv_chain_key: string;
+    send_count: number;
+    recv_count: number;
+    prev_send_count: number;
+    my_ratchet_private_jwk: JsonWebKey;
+    my_ratchet_public_jwk: JsonWebKey;
+    their_ratchet_public_jwk: JsonWebKey;
+    skipped_keys: Record<string, string>;
+    created_at: number;
+    updated_at: number;
+}
 interface ServerEncryptResult {
     /** Base64-encoded ciphertext */
     encrypted_message: string;
@@ -211,6 +293,9 @@ declare class Wolfronix {
     private publicKey;
     private privateKey;
     private publicKeyPEM;
+    private pfsIdentityPrivateJwk;
+    private pfsIdentityPublicJwk;
+    private pfsSessions;
     /** Expose private key status for testing */
     hasPrivateKey(): boolean;
     /**
@@ -229,6 +314,11 @@ declare class Wolfronix {
     private request;
     private sleep;
     private ensureAuthenticated;
+    private toBlob;
+    private ensurePfsIdentity;
+    private getPfsSession;
+    private ratchetForSend;
+    private ratchetForReceive;
     /**
      * Register a new user
      *
@@ -237,7 +327,7 @@ declare class Wolfronix {
      * const { user_id, token } = await wfx.register('user@example.com', 'password123');
      * ```
      */
-    register(email: string, password: string): Promise<AuthResponse>;
+    register(email: string, password: string, options?: RegisterOptions): Promise<AuthResponse & Partial<RecoverySetup>>;
     /**
      * Login with existing credentials
      *
@@ -247,6 +337,20 @@ declare class Wolfronix {
      * ```
      */
     login(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Recover account keys using a 24-word recovery phrase and set a new password.
+     * Returns a fresh local auth session if recovery succeeds.
+     */
+    recoverAccount(email: string, recoveryPhrase: string, newPassword: string): Promise<AuthResponse>;
+    /**
+     * Rotates long-term RSA identity keys and re-wraps with password (+ optional recovery phrase).
+     * Use this periodically to reduce long-term key exposure.
+     */
+    rotateIdentityKeys(password: string, recoveryPhrase?: string): Promise<{
+        success: boolean;
+        message: string;
+        recoveryPhrase?: string;
+    }>;
     /**
      * Set authentication token directly (useful for server-side apps)
      *
@@ -283,6 +387,15 @@ declare class Wolfronix {
      * ```
      */
     encrypt(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<EncryptResponse>;
+    /**
+     * Resumable large-file encryption upload.
+     * Splits a file into chunks (default 10MB) and uploads each chunk independently.
+     * If upload fails mid-way, pass the returned state as `existingState` to resume.
+     */
+    encryptResumable(file: File | Blob | ArrayBuffer | Uint8Array, options?: ResumableEncryptOptions): Promise<{
+        result: ChunkedEncryptResult;
+        state: ResumableUploadState;
+    }>;
     /**
      * Decrypt and retrieve a file using zero-knowledge flow.
      *
@@ -309,6 +422,15 @@ declare class Wolfronix {
      * Decrypt and return as ArrayBuffer (zero-knowledge flow)
      */
     decryptToBuffer(fileId: string, role?: string): Promise<ArrayBuffer>;
+    /**
+     * Decrypts and reassembles a chunked upload produced by `encryptResumable`.
+     */
+    decryptChunkedToBuffer(manifest: ChunkedDecryptManifest, role?: string): Promise<ArrayBuffer>;
+    /**
+     * Decrypts and reassembles a chunked upload into a Blob.
+     * This is a browser-friendly alias over `decryptChunkedToBuffer`.
+     */
+    decryptChunkedManifest(manifest: ChunkedDecryptManifest, role?: string): Promise<Blob>;
     /**
      * Fetch the encrypted key_part_a for a file (for client-side decryption)
      *
@@ -355,6 +477,42 @@ declare class Wolfronix {
      * @param packetJson The secure JSON string packet
      */
     decryptMessage(packetJson: string): Promise<string>;
+    /**
+     * Create/share a pre-key bundle for Double Ratchet PFS session setup.
+     * Exchange this bundle out-of-band with the peer.
+     */
+    createPfsPreKeyBundle(): Promise<PfsPreKeyBundle>;
+    /**
+     * Initialize a local PFS ratchet session from peer bundle.
+     * Both sides must call this with opposite `asInitiator` values.
+     */
+    initPfsSession(sessionId: string, peerBundle: PfsPreKeyBundle, asInitiator: boolean): Promise<PfsSessionState>;
+    /**
+     * Export session state for persistence (e.g., localStorage/DB).
+     */
+    exportPfsSession(sessionId: string): PfsSessionState;
+    /**
+     * Import session state from storage.
+     */
+    importPfsSession(session: PfsSessionState): void;
+    /**
+     * Encrypt a message using Double Ratchet session state.
+     */
+    pfsEncryptMessage(sessionId: string, plaintext: string): Promise<PfsMessagePacket>;
+    /**
+     * Decrypt a Double Ratchet packet for a session.
+     * Handles basic out-of-order delivery through skipped message keys.
+     */
+    pfsDecryptMessage(sessionId: string, packet: PfsMessagePacket | string): Promise<string>;
+    /**
+     * Group message encryption using sender-key fanout:
+     * message encrypted once with AES key, AES key wrapped for each group member with their RSA public key.
+     */
+    encryptGroupMessage(text: string, groupId: string, recipientIds: string[]): Promise<string>;
+    /**
+     * Decrypt a packet produced by `encryptGroupMessage`.
+     */
+    decryptGroupMessage(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 —
@@ -615,4 +773,4 @@ declare class WolfronixAdmin {
     healthCheck(): Promise<boolean>;
 }
 
-export { type AuthResponse, AuthenticationError, type DBType, type DeactivateClientResponse, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type EnterpriseClient, type FileInfo, FileNotFoundError, type KeyPartResponse, type ListClientsResponse, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type RegisterClientRequest, type RegisterClientResponse, type ServerBatchEncryptResult, type ServerDecryptParams, type ServerEncryptResult, type StreamChunk, type StreamSession, type UpdateClientRequest, type UpdateClientResponse, ValidationError, Wolfronix, WolfronixAdmin, type WolfronixAdminConfig, type WolfronixConfig, WolfronixError, WolfronixStream, createClient, Wolfronix as default };
+export { type AuthResponse, AuthenticationError, type ChunkedDecryptManifest, type ChunkedEncryptResult, type DBType, type DeactivateClientResponse, type DeleteResponse, type EncryptMessagePacket, type EncryptResponse, type EnterpriseClient, type FileInfo, FileNotFoundError, type GroupEncryptPacket, type KeyPartResponse, type ListClientsResponse, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type PfsMessagePacket, type PfsPreKeyBundle, type PfsSessionState, type RecoverySetup, type RegisterClientRequest, type RegisterClientResponse, type RegisterOptions, type ResumableEncryptOptions, type ResumableUploadState, type ServerBatchEncryptResult, type ServerDecryptParams, type ServerEncryptResult, type StreamChunk, type StreamSession, type UpdateClientRequest, type UpdateClientResponse, ValidationError, Wolfronix, WolfronixAdmin, type WolfronixAdminConfig, type WolfronixConfig, WolfronixError, WolfronixStream, createClient, Wolfronix as default };