@time-file/browser-file-crypto 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -78,6 +78,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 +264,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 +321,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.
  *
@@ -365,27 +469,78 @@ export declare function downloadKeyFile(keyData: string, fileName: string, exten
  */
 export declare function encryptFile(file: File | Blob | ArrayBuffer, options: EncryptOptions): 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 +641,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 +659,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 +711,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 +736,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 +912,72 @@ 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.
+ *
+ * @since 1.1.0
+ */
+export declare type StreamProgressPhase = 'deriving_key' | 'processing' | 'complete';
+
 export { }