@time-file/browser-file-crypto 1.0.3 → 1.1.1

package/dist/index.d.ts

@@ -43,6 +43,35 @@ export declare const ALGORITHM: "AES-GCM";
  */
 export declare const AUTH_TAG_LENGTH = 16;
 
+/**
+ * Auto encryption options for hybrid mode.
+ *
+ * @description
+ * Extended options that enable automatic switching between
+ * non-streaming and streaming encryption based on file size.
+ *
+ * @since 1.1.0
+ */
+export declare interface AutoEncryptOptions extends EncryptOptions {
+    /**
+     * Enable automatic streaming for large files.
+     * When true, files larger than streamingThreshold will use streaming encryption.
+     * @default false
+     */
+    autoStreaming?: boolean;
+    /**
+     * File size threshold in bytes for automatic streaming mode.
+     * Files larger than this size will use streaming encryption.
+     * @default 104857600 (100MB)
+     */
+    streamingThreshold?: number;
+    /**
+     * Chunk size for streaming encryption (only used when streaming is active).
+     * @default 65536 (64KB)
+     */
+    chunkSize?: number;
+}
+
 /**
  * Computes SHA-256 hash of a keyfile's key data.
  *
@@ -78,6 +107,73 @@ export declare const AUTH_TAG_LENGTH = 16;
  */
 export declare function computeKeyFileHash(keyData: string): Promise<string>;
 
+/**
+ * Creates a streaming decryption TransformStream.
+ *
+ * @description
+ * Creates a TransformStream that decrypts streaming-encrypted data.
+ * The stream automatically parses the header and decrypts each chunk
+ * using the appropriate key derivation method.
+ *
+ * @param options - Streaming decryption options
+ * @returns A TransformStream that decrypts data
+ *
+ * @throws {CryptoError} When password is required but not provided (PASSWORD_REQUIRED)
+ * @throws {CryptoError} When keyfile is required but not provided (KEYFILE_REQUIRED)
+ * @throws {CryptoError} When decryption fails (DECRYPTION_FAILED)
+ * @throws {CryptoError} When format is unsupported (UNSUPPORTED_FORMAT)
+ *
+ * @example
+ * ```typescript
+ * const stream = createDecryptStream({
+ *   password: 'my-secret',
+ *   onProgress: ({ processedBytes }) => console.log(`${processedBytes} bytes processed`)
+ * });
+ *
+ * await encryptedStream.pipeThrough(stream).pipeTo(outputStream);
+ * ```
+ *
+ * @since 1.1.0
+ */
+export declare function createDecryptStream(options: StreamDecryptOptions): TransformStream<Uint8Array, Uint8Array>;
+
+/**
+ * Creates a streaming encryption TransformStream.
+ *
+ * @description
+ * Creates a TransformStream that encrypts data in chunks using AES-256-GCM.
+ * Each chunk is independently encrypted with a unique IV derived from the
+ * base IV and chunk index. This allows memory-efficient encryption of
+ * arbitrarily large files.
+ *
+ * @param options - Streaming encryption options
+ * @returns Promise resolving to an object containing the TransformStream and header
+ *
+ * @throws {CryptoError} When neither password nor keyData is provided (PASSWORD_REQUIRED)
+ * @throws {CryptoError} When encryption fails (ENCRYPTION_FAILED)
+ *
+ * @example
+ * ```typescript
+ * const { stream, header } = await createEncryptStream({
+ *   password: 'my-secret',
+ *   chunkSize: 1024 * 1024, // 1MB chunks
+ *   onProgress: ({ processedBytes }) => console.log(`${processedBytes} bytes processed`)
+ * });
+ *
+ * // Write header first, then pipe data through the stream
+ * const writer = writableStream.getWriter();
+ * await writer.write(header);
+ * writer.releaseLock();
+ * await readableStream.pipeThrough(stream).pipeTo(writableStream);
+ * ```
+ *
+ * @since 1.1.0
+ */
+export declare function createEncryptStream(options: StreamEncryptOptions): Promise<{
+    stream: TransformStream<Uint8Array, Uint8Array>;
+    header: Uint8Array;
+}>;
+
 /**
  * Custom error class for crypto operations.
  *
@@ -197,6 +293,37 @@ export declare type CryptoErrorCode = 'INVALID_INPUT' | 'PASSWORD_REQUIRED' | 'K
  */
 export declare function decryptFile(encrypted: Blob | ArrayBuffer, options: DecryptOptions): Promise<Blob>;
 
+/**
+ * Decrypts a streaming-encrypted file.
+ *
+ * @description
+ * Convenience function that decrypts a streaming-encrypted File, Blob,
+ * or ReadableStream and returns a ReadableStream of the decrypted data.
+ *
+ * @param encrypted - The encrypted data (File, Blob, or ReadableStream)
+ * @param options - Streaming decryption options
+ * @returns A ReadableStream of decrypted data
+ *
+ * @throws {CryptoError} When password is required but not provided (PASSWORD_REQUIRED)
+ * @throws {CryptoError} When keyfile is required but not provided (KEYFILE_REQUIRED)
+ * @throws {CryptoError} When decryption fails (DECRYPTION_FAILED)
+ *
+ * @example
+ * ```typescript
+ * const decryptedStream = decryptFileStream(encryptedBlob, {
+ *   password: 'my-secret',
+ *   onProgress: ({ processedBytes }) => console.log(`${processedBytes} bytes decrypted`)
+ * });
+ *
+ * // Convert to Blob
+ * const response = new Response(decryptedStream);
+ * const decryptedBlob = await response.blob();
+ * ```
+ *
+ * @since 1.1.0
+ */
+export declare function decryptFileStream(encrypted: File | Blob | ReadableStream<Uint8Array>, options: StreamDecryptOptions): ReadableStream<Uint8Array>;
+
 /**
  * Options for file decryption.
  *
@@ -223,6 +350,12 @@ export declare interface DecryptOptions {
     onProgress?: ProgressCallback;
 }
 
+/**
+ * Default chunk size for streaming encryption (64KB).
+ * @since 1.1.0
+ */
+export declare const DEFAULT_CHUNK_SIZE: number;
+
 /**
  * Downloads an encrypted file from URL, decrypts it, and saves to disk.
  *
@@ -267,6 +400,48 @@ export declare interface DecryptOptions {
  */
 export declare function downloadAndDecrypt(url: string, options: DownloadDecryptOptions): Promise<void>;
 
+/**
+ * Downloads a streaming-encrypted file from URL, decrypts it, and saves to disk.
+ *
+ * @description
+ * Memory-efficient version of downloadAndDecrypt for streaming-encrypted files.
+ * Uses streaming decryption to process data in chunks, suitable for large files.
+ *
+ * Phases:
+ * 1. `downloading` (0-50%): Fetching file from URL
+ * 2. `deriving_key` (50-55%): Key derivation (password mode only)
+ * 3. `decrypting` (55-95%): Streaming AES-GCM decryption
+ * 4. `complete` (100%): File saved
+ *
+ * Note: This function uses browser APIs (fetch, URL.createObjectURL, document.createElement)
+ * and will not work in Node.js environments.
+ *
+ * @param url - URL of the streaming-encrypted file to download
+ * @param options - Options including password/keyData and fileName
+ * @returns Promise that resolves when file is saved
+ *
+ * @throws {CryptoError} When download fails (DOWNLOAD_FAILED)
+ * @throws {CryptoError} When decryption fails (see decryptFileStream errors)
+ *
+ * @example
+ * ```typescript
+ * await downloadAndDecryptStream('https://example.com/large-file.enc', {
+ *   password: 'my-secret',
+ *   fileName: 'large-video.mp4',
+ *   onProgress: ({ phase, processedBytes, totalBytes }) => {
+ *     if (totalBytes) {
+ *       console.log(`${phase}: ${Math.round((processedBytes / totalBytes) * 100)}%`);
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link downloadAndDecrypt} for non-streaming files
+ * @see {@link decryptFileStream} for decryption only
+ * @since 1.1.0
+ */
+export declare function downloadAndDecryptStream(url: string, options: DownloadDecryptStreamOptions): Promise<void>;
+
 /**
  * Options for download and decrypt operation.
  *
@@ -287,6 +462,16 @@ export declare interface DownloadDecryptOptions extends DecryptOptions {
     fileName: string;
 }
 
+/**
+ * Options for streaming download and decrypt operation.
+ *
+ * @since 1.1.0
+ */
+export declare interface DownloadDecryptStreamOptions extends StreamDecryptOptions {
+    /** File name to use when saving the decrypted file */
+    fileName: string;
+}
+
 /**
  * Downloads a keyfile as a JSON file with customizable extension.
  *
@@ -365,27 +550,121 @@ export declare function downloadKeyFile(keyData: string, fileName: string, exten
  */
 export declare function encryptFile(file: File | Blob | ArrayBuffer, options: EncryptOptions): Promise<Blob>;
 
+/**
+ * Encrypts a file with automatic streaming mode for large files.
+ *
+ * @description
+ * Hybrid encryption function that automatically chooses between
+ * non-streaming and streaming encryption based on file size.
+ *
+ * - Files smaller than threshold: Uses standard encryptFile (faster for small files)
+ * - Files larger than threshold: Uses encryptFileStream (memory-efficient for large files)
+ *
+ * Default threshold is 100MB, configurable via options.
+ *
+ * @param file - The file to encrypt (File or Blob)
+ * @param options - Auto encryption options including threshold settings
+ * @returns Promise resolving to encrypted Blob
+ *
+ * @throws {CryptoError} When neither password nor keyData is provided (PASSWORD_REQUIRED)
+ * @throws {CryptoError} When encryption fails (ENCRYPTION_FAILED)
+ *
+ * @example
+ * ```typescript
+ * // Auto mode with default 100MB threshold
+ * const encrypted = await encryptFileAuto(file, {
+ *   password: 'my-secret',
+ *   autoStreaming: true,
+ *   onProgress: ({ phase, progress }) => console.log(`${phase}: ${progress}%`)
+ * });
+ *
+ * // Custom threshold (50MB)
+ * const encrypted = await encryptFileAuto(file, {
+ *   password: 'my-secret',
+ *   autoStreaming: true,
+ *   streamingThreshold: 50 * 1024 * 1024,
+ *   chunkSize: 1024 * 1024  // 1MB chunks for streaming
+ * });
+ * ```
+ *
+ * @see {@link encryptFile} for non-streaming encryption
+ * @see {@link encryptFileStream} for streaming encryption
+ * @since 1.1.0
+ */
+export declare function encryptFileAuto(file: File | Blob, options: AutoEncryptOptions): Promise<Blob>;
+
+/**
+ * Encrypts a file using streaming encryption.
+ *
+ * @description
+ * Convenience function that encrypts a File or Blob using streaming
+ * encryption and returns a ReadableStream of the encrypted data.
+ * The stream includes the encryption header followed by encrypted chunks.
+ *
+ * @param file - The file to encrypt
+ * @param options - Streaming encryption options
+ * @returns Promise resolving to a ReadableStream of encrypted data
+ *
+ * @throws {CryptoError} When neither password nor keyData is provided (PASSWORD_REQUIRED)
+ * @throws {CryptoError} When encryption fails (ENCRYPTION_FAILED)
+ *
+ * @example
+ * ```typescript
+ * const encryptedStream = await encryptFileStream(largeFile, {
+ *   password: 'my-secret',
+ *   chunkSize: 1024 * 1024,  // 1MB chunks
+ *   onProgress: ({ processedBytes, totalBytes }) => {
+ *     const percent = Math.round((processedBytes / totalBytes!) * 100);
+ *     console.log(`${percent}%`);
+ *   }
+ * });
+ *
+ * // Convert to Blob
+ * const response = new Response(encryptedStream);
+ * const encryptedBlob = await response.blob();
+ * ```
+ *
+ * @since 1.1.0
+ */
+export declare function encryptFileStream(file: File | Blob, options: StreamEncryptOptions): Promise<ReadableStream<Uint8Array>>;
+
 /**
  * Encryption marker byte for keyfile-based encryption.
  * Used to identify the encryption method when decrypting.
  */
 export declare const ENCRYPTION_MARKER_KEYFILE = 2;
 
+/**
+ * Encryption marker byte for keyfile-based streaming encryption.
+ * Used to identify streaming encryption with keyfile.
+ * @since 1.1.0
+ */
+export declare const ENCRYPTION_MARKER_KEYFILE_STREAM = 18;
+
 /**
  * Encryption marker byte for password-based encryption.
  * Used to identify the encryption method when decrypting.
  */
 export declare const ENCRYPTION_MARKER_PASSWORD = 1;
 
+/**
+ * Encryption marker byte for password-based streaming encryption.
+ * Used to identify streaming encryption with password.
+ * @since 1.1.0
+ */
+export declare const ENCRYPTION_MARKER_PASSWORD_STREAM = 17;
+
 /**
  * Encryption type detected from encrypted data.
  *
  * @description
  * - `password`: File was encrypted with a password (marker byte 0x01)
  * - `keyfile`: File was encrypted with a keyfile (marker byte 0x02)
+ * - `password-stream`: File was encrypted with password streaming (marker byte 0x11)
+ * - `keyfile-stream`: File was encrypted with keyfile streaming (marker byte 0x12)
  * - `unknown`: Unrecognized format or not encrypted with this library
  */
-export declare type EncryptionType = 'password' | 'keyfile' | 'unknown';
+export declare type EncryptionType = 'password' | 'keyfile' | 'password-stream' | 'keyfile-stream' | 'unknown';
 
 /**
  * Options for file encryption.
@@ -486,10 +765,13 @@ export declare function generateRandomPassword(length?: number): string;
  *
  * @description
  * Reads the first byte (marker) of the encrypted data to determine
- * whether it was encrypted with a password or keyfile.
+ * whether it was encrypted with a password or keyfile, and whether
+ * it uses streaming or non-streaming encryption.
  *
- * - Marker 0x01: Password-based encryption
- * - Marker 0x02: Keyfile-based encryption
+ * - Marker 0x01: Password-based encryption (non-streaming)
+ * - Marker 0x02: Keyfile-based encryption (non-streaming)
+ * - Marker 0x11: Password-based streaming encryption
+ * - Marker 0x12: Keyfile-based streaming encryption
  * - Other: Unknown format
  *
  * @param data - The encrypted data (Blob or ArrayBuffer)
@@ -501,10 +783,16 @@ export declare function generateRandomPassword(length?: number): string;
  *
  * switch (type) {
  *   case 'password':
- *     // Show password input
+ *     // Use decryptFile with password
  *     break;
  *   case 'keyfile':
- *     // Show keyfile picker
+ *     // Use decryptFile with keyData
+ *     break;
+ *   case 'password-stream':
+ *     // Use decryptFileStream with password
+ *     break;
+ *   case 'keyfile-stream':
+ *     // Use decryptFileStream with keyData
  *     break;
  *   case 'unknown':
  *     // Show error: not encrypted with this library
@@ -547,7 +835,7 @@ export declare function isCryptoError(error: unknown): error is CryptoError;
  * @description
  * Performs a quick check to determine if the data was likely encrypted
  * with browser-file-crypto. This checks:
- * 1. The marker byte is valid (0x01 or 0x02)
+ * 1. The marker byte is valid (0x01, 0x02, 0x11, or 0x12)
  * 2. The data meets minimum size requirements
  *
  * Note: This is not a cryptographic verification. It only checks
@@ -572,6 +860,31 @@ export declare function isCryptoError(error: unknown): error is CryptoError;
  */
 export declare function isEncryptedFile(data: Blob | ArrayBuffer): Promise<boolean>;
 
+/**
+ * Checks if the encryption type is a streaming format.
+ *
+ * @description
+ * Helper function to determine if the encryption type uses
+ * streaming encryption, which requires different decryption methods.
+ *
+ * @param type - The encryption type
+ * @returns true if the type is a streaming format
+ *
+ * @example
+ * ```typescript
+ * const type = await getEncryptionType(encryptedBlob);
+ *
+ * if (isStreamingEncryption(type)) {
+ *   const decrypted = decryptFileStream(encryptedBlob, { password });
+ * } else {
+ *   const decrypted = await decryptFile(encryptedBlob, { password });
+ * }
+ * ```
+ *
+ * @since 1.1.0
+ */
+export declare function isStreamingEncryption(type: EncryptionType): boolean;
+
 /**
  * Initialization vector length in bytes for AES-GCM.
  * 12 bytes (96 bits) is the recommended IV size for AES-GCM per NIST SP 800-38D.
@@ -723,4 +1036,82 @@ export declare type ProgressPhase = 'deriving_key' | 'encrypting' | 'decrypting'
  */
 export declare const SALT_LENGTH = 16;
 
+/**
+ * Streaming format version.
+ * @since 1.1.0
+ */
+export declare const STREAM_FORMAT_VERSION = 1;
+
+/**
+ * Options for streaming file decryption.
+ *
+ * @since 1.1.0
+ */
+export declare interface StreamDecryptOptions {
+    /** Password for decryption (required for password-encrypted files) */
+    password?: string;
+    /** Base64-encoded key data (required for keyfile-encrypted files) */
+    keyData?: string;
+    /** Progress callback for UI updates */
+    onProgress?: StreamProgressCallback;
+}
+
+/**
+ * Options for streaming file encryption.
+ *
+ * @since 1.1.0
+ */
+export declare interface StreamEncryptOptions {
+    /** Password for encryption (required if keyData not provided) */
+    password?: string;
+    /** Base64-encoded key data from keyfile (required if password not provided) */
+    keyData?: string;
+    /** Chunk size in bytes (default: 65536 = 64KB) */
+    chunkSize?: number;
+    /** Progress callback for UI updates */
+    onProgress?: StreamProgressCallback;
+}
+
+/**
+ * Progress information for streaming encryption/decryption operations.
+ *
+ * @since 1.1.0
+ */
+export declare interface StreamProgress {
+    /** Current phase of the operation */
+    phase: StreamProgressPhase;
+    /** Number of bytes processed so far */
+    processedBytes: number;
+    /** Total bytes to process (undefined if unknown, e.g., for streams) */
+    totalBytes?: number;
+    /** Number of chunks processed so far */
+    processedChunks: number;
+    /** Progress percentage (0-100), only available when totalBytes is known */
+    progress?: number;
+}
+
+/**
+ * Callback function for streaming progress updates.
+ *
+ * @since 1.1.0
+ */
+export declare type StreamProgressCallback = (progress: StreamProgress) => void;
+
+/**
+ * Progress phase during streaming encryption/decryption operations.
+ *
+ * @description
+ * - `deriving_key`: PBKDF2 key derivation in progress (password mode)
+ * - `encrypting`: AES-GCM streaming encryption in progress
+ * - `decrypting`: AES-GCM streaming decryption in progress
+ * - `downloading`: File download in progress (downloadAndDecryptStream)
+ * - `complete`: Operation finished successfully
+ *
+ * Note: For backward compatibility, these phases are aligned with
+ * the non-streaming Progress phases.
+ *
+ * @since 1.1.0
+ */
+export declare type StreamProgressPhase = 'deriving_key' | 'encrypting' | 'decrypting' | 'downloading' | 'complete';
+
 export { }