@redseat/api 0.0.12 → 0.0.14

package/encryption.md

@@ -1,533 +1,533 @@
-# Encryption Module Documentation
-
-## Overview
-
-The encryption module (`packages/api/src/encryption.ts`) provides cross-platform encryption and decryption functions for text and binary data. It uses the Web Crypto API (AES-CBC 256-bit encryption) and is compatible with Node.js, Web browsers, and React Native/Expo.
-
-## Key Concepts
-
-### Key Derivation (PBKDF2)
-
-Keys are derived from passphrases using **PBKDF2** (Password-Based Key Derivation Function 2) with:
-- **Hash algorithm**: SHA-1
-- **Iterations**: 1000
-- **Key length**: 256 bits (AES-256)
-- **Salt**: Different salts for text and file encryption
-  - Text encryption salt: `a1209660b32cca003630cb963f730b54`
-  - File encryption salt: `e5709660b22ab0803630cb963f703b83`
-
-**Important**: Text and file encryption use different keys derived from the same passphrase but with different salts. This means:
-- Text data (filenames, tags, folder names) uses the "text" key
-- Binary data (file contents, thumbnails) uses the "file" key
-- Both keys must be derived from the same passphrase to decrypt data encrypted with that passphrase
-
-### Encryption Algorithm
-
-- **Algorithm**: AES-CBC (Advanced Encryption Standard in Cipher Block Chaining mode)
-- **Key size**: 256 bits
-- **IV (Initialization Vector)**: 16 bytes, randomly generated for each encryption operation
-
-### Encoding Formats
-
-- **Base64**: Standard base64 encoding (uses `+` and `/` characters)
-- **Base64URL**: URL-safe base64 encoding (uses `-` and `_` instead of `+` and `/`, padding removed)
-- Text encryption uses Base64URL for the final output to ensure URL safety
-
-## Core Functions
-
-### `deriveKey(passPhrase: string, type: 'text' | 'file'): Promise<CryptoKey>`
-
-Derives a cryptographic key from a passphrase using PBKDF2.
-
-**Parameters:**
-- `passPhrase`: The password/passphrase to derive the key from
-- `type`: Either `'text'` for text encryption or `'file'` for file/binary encryption
-
-**Returns:** A `CryptoKey` object suitable for AES-CBC encryption/decryption
-
-**Example:**
-```typescript
-const textKey = await deriveKey('my-password', 'text');
-const fileKey = await deriveKey('my-password', 'file');
-```
-
-**Note:** The returned key is not extractable (cannot be exported) for security reasons.
-
----
-
-### `getRandomIV(): Uint8Array`
-
-Generates a random 16-byte Initialization Vector (IV) for encryption operations.
-
-**Returns:** A `Uint8Array` of 16 random bytes
-
-**Example:**
-```typescript
-const iv = getRandomIV();
-```
-
-**Important:** A new IV must be generated for each encryption operation. Never reuse IVs with the same key.
-
----
-
-## Text Encryption
-
-### `encryptText(key: CryptoKey, text: string): Promise<string>`
-
-Encrypts a text string using AES-CBC encryption.
-
-**Parameters:**
-- `key`: The CryptoKey to use for encryption (should be derived with `type: 'text'`)
-- `text`: The plaintext string to encrypt
-
-**Returns:** A string in the format: `${base64Url(IV)}.${base64Url(encryptedData)}`
-
-**Format:**
-- The IV and encrypted data are both base64url encoded
-- They are concatenated with a `.` (dot) separator
-- Example: `SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p`
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'text');
-const encrypted = await encryptText(key, 'Hello World');
-// Returns: "SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p"
-```
-
-**Use cases:**
-- Encrypting filenames
-- Encrypting tag names
-- Encrypting folder names
-- Any text metadata that needs to be encrypted
-
----
-
-### `decryptText(key: CryptoKey, encryptedText: string, iv?: ArrayBuffer | Uint8Array): Promise<string>`
-
-Decrypts a text string that was encrypted with `encryptText`.
-
-**Parameters:**
-- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
-- `encryptedText`: The encrypted string in format `${IV}.${encryptedData}` OR just the encrypted data if IV is provided separately
-- `iv`: (Optional) If provided, `encryptedText` should contain only the encrypted data (without the IV prefix)
-
-**Returns:** The decrypted plaintext string
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'text');
-const decrypted = await decryptText(key, 'SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p');
-// Returns: "Hello World"
-```
-
-**Error handling:**
-- Throws an error if the encrypted text format is invalid (not in `IV.encryptedData` format)
-- Throws an error if decryption fails (wrong key, corrupted data, etc.)
-
----
-
-## Binary Data Encryption
-
-### `encryptBuffer(key: CryptoKey, iv: ArrayBuffer | Uint8Array, buffer: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>`
-
-Encrypts binary data (ArrayBuffer or Uint8Array) using AES-CBC encryption.
-
-**Parameters:**
-- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
-- `iv`: The 16-byte Initialization Vector (use `getRandomIV()`)
-- `buffer`: The binary data to encrypt
-
-**Returns:** An ArrayBuffer containing the encrypted data
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const iv = getRandomIV();
-const data = new Uint8Array([1, 2, 3, 4, 5]);
-const encrypted = await encryptBuffer(key, iv, data);
-```
-
-**Use cases:**
-- Encrypting file contents
-- Encrypting thumbnails
-- Encrypting any binary data
-
----
-
-### `decryptBuffer(key: CryptoKey, iv: ArrayBuffer | Uint8Array, buffer: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>`
-
-Decrypts binary data that was encrypted with `encryptBuffer`.
-
-**Parameters:**
-- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
-- `iv`: The same IV that was used during encryption
-- `buffer`: The encrypted binary data
-
-**Returns:** An ArrayBuffer containing the decrypted data
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const iv = /* same IV used for encryption */;
-const decrypted = await decryptBuffer(key, iv, encryptedData);
-```
-
-**Important:** The IV must be exactly the same as the one used during encryption. Using a different IV will result in corrupted decrypted data (though it may not throw an error).
-
----
-
-## File Encryption (Structured Format)
-
-### File Format Structure
-
-Files encrypted with `encryptFile` follow a specific binary structure:
-
-```
-[16 bytes: IV]
-[4 bytes: Thumbnail size (big-endian)]
-[4 bytes: Info size (big-endian, currently always 0)]
-[32 bytes: Thumbnail MIME type (padded)]
-[256 bytes: File MIME type (padded)]
-[T bytes: Encrypted thumbnail data]
-[I bytes: Encrypted info data (currently always 0 bytes)]
-[F bytes: Encrypted file data]
-```
-
-**Byte offsets:**
-- `0-15`: IV (16 bytes)
-- `16-19`: Thumbnail size (4 bytes, big-endian)
-- `20-23`: Info size (4 bytes, big-endian)
-- `24-55`: Thumbnail MIME type (32 bytes, null-padded)
-- `56-311`: File MIME type (256 bytes, null-padded)
-- `312+`: Encrypted thumbnail (length = thumbnail size)
-- `312 + thumbnailSize +`: Encrypted file data
-
-**Endianness:** Sizes are stored in **big-endian** format. The decryption functions try big-endian first, then fall back to little-endian for backward compatibility.
-
----
-
-### `encryptFile(key: CryptoKey, options: EncryptFileOptions): Promise<EncryptedFile>`
-
-Encrypts a file with its thumbnail and metadata into a structured binary format.
-
-**Parameters:**
-- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
-- `options`: An object containing:
-  - `filename`: The original filename (will be encrypted separately)
-  - `buffer`: The file data to encrypt (ArrayBuffer or Uint8Array)
-  - `thumb`: The thumbnail data to encrypt (ArrayBuffer or Uint8Array, can be empty)
-  - `thumbMime`: MIME type of the thumbnail (e.g., `'image/jpeg'`)
-  - `mime`: MIME type of the file (e.g., `'image/png'`)
-
-**Returns:** An `EncryptedFile` object containing:
-- `filename`: Base64URL-encoded encrypted filename (encrypted with the same IV as the file)
-- `ivb64`: Base64-encoded IV (for storage in metadata)
-- `thumbsize`: Size of the encrypted thumbnail in bytes
-- `blob`: The complete encrypted file structure as an ArrayBuffer
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const fileData = await file.arrayBuffer();
-const thumbData = await thumbnail.arrayBuffer();
-
-const encrypted = await encryptFile(key, {
-    filename: 'photo.jpg',
-    buffer: fileData,
-    thumb: thumbData,
-    thumbMime: 'image/jpeg',
-    mime: 'image/jpeg'
-});
-
-// encrypted.filename: base64url encoded encrypted filename
-// encrypted.ivb64: base64 encoded IV (store this in metadata)
-// encrypted.thumbsize: size of encrypted thumbnail
-// encrypted.blob: complete encrypted file structure
-```
-
-**Important notes:**
-- The filename is encrypted separately using `encryptBuffer` with the same IV
-- The filename is returned as base64url-encoded (for URL safety)
-- The IV is returned as base64-encoded (for storage in database metadata)
-- All data (file, thumbnail, filename) uses the same IV
-
----
-
-### `decryptFile(key: CryptoKey, buffer: ArrayBuffer): Promise<ArrayBuffer>`
-
-Decrypts the file data from an encrypted file structure.
-
-**Parameters:**
-- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
-- `buffer`: The complete encrypted file structure (as returned by `encryptFile`)
-
-**Returns:** An ArrayBuffer containing the decrypted file data
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const encryptedBlob = /* encrypted file blob */;
-const decryptedFile = await decryptFile(key, encryptedBlob);
-```
-
-**How it works:**
-1. Extracts the IV from the first 16 bytes
-2. Reads the thumbnail size (tries big-endian first, falls back to little-endian)
-3. Reads the info size
-4. Calculates the offset to the encrypted file data
-5. Decrypts and returns the file data
-
----
-
-### `decryptFileThumb(key: CryptoKey, buffer: ArrayBuffer): Promise<ArrayBuffer>`
-
-Decrypts the thumbnail from an encrypted file structure.
-
-**Parameters:**
-- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
-- `buffer`: The complete encrypted file structure (as returned by `encryptFile`)
-
-**Returns:** An ArrayBuffer containing the decrypted thumbnail data, or an empty ArrayBuffer if no thumbnail exists
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const encryptedBlob = /* encrypted file blob */;
-const decryptedThumb = await decryptFileThumb(key, encryptedBlob);
-```
-
-**How it works:**
-1. Extracts the IV from the first 16 bytes
-2. Reads the thumbnail size (tries big-endian first, falls back to little-endian)
-3. If thumbnail size is 0, returns empty buffer
-4. Calculates the offset to the encrypted thumbnail (after IV, sizes, and MIME types)
-5. Decrypts and returns the thumbnail data
-
-**Note:** The server's `getThumb` API endpoint returns only the encrypted thumbnail portion (already sliced), not the full file structure. In that case, use `decryptBuffer` directly with the IV from the media metadata.
-
----
-
-### `encryptFilename(key: CryptoKey, filename: string, iv: ArrayBuffer | Uint8Array): Promise<string>`
-
-Encrypts a filename using the same IV as the file encryption.
-
-**Parameters:**
-- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
-- `filename`: The original filename to encrypt
-- `iv`: The same IV used for encrypting the file
-
-**Returns:** Base64URL-encoded encrypted filename
-
-**Example:**
-```typescript
-const key = await deriveKey('password', 'file');
-const iv = getRandomIV();
-const encryptedFilename = await encryptFilename(key, 'photo.jpg', iv);
-```
-
-**Note:** This function is used internally by `encryptFile`. For new uploads, filenames are encrypted using `encryptText` with the text key instead, which produces the format `${IV}.${encryptedData}`.
-
----
-
-## Cross-Platform Compatibility
-
-The encryption module is designed to work across multiple platforms:
-
-### Supported Platforms
-
-1. **Web Browsers**: Uses `window.crypto.subtle` or `globalThis.crypto.subtle`
-2. **Node.js**: Uses `crypto.webcrypto.subtle` (Node.js 15+)
-3. **React Native/Expo**: Uses `globalThis.crypto.subtle` or `crypto.subtle`
-
-### Platform Detection
-
-The `crypto.ts` module automatically detects the available crypto APIs:
-
-- **`getCryptoSubtle()`**: Returns the appropriate `SubtleCrypto` implementation
-- **`getCryptoRandomValues()`**: Returns the appropriate random number generator
-
-### Base64 Encoding
-
-Base64 encoding/decoding is handled cross-platform:
-- **Node.js**: Uses `Buffer` for efficient conversion
-- **Browsers/RN**: Uses `atob`/`btoa` or manual conversion
-
----
-
-## Usage Patterns
-
-### Complete File Upload Flow
-
-```typescript
-import { deriveKey, encryptFile, encryptText, getRandomIV } from '@redseat/api';
-
-// 1. Derive keys from passphrase
-const fileKey = await deriveKey('user-password', 'file');
-const textKey = await deriveKey('user-password', 'text');
-
-// 2. Encrypt the file
-const encrypted = await encryptFile(fileKey, {
-    filename: 'document.pdf',
-    buffer: fileArrayBuffer,
-    thumb: thumbnailArrayBuffer,
-    thumbMime: 'image/jpeg',
-    mime: 'application/pdf'
-});
-
-// 3. Encrypt the filename (for new uploads, use text encryption)
-const encryptedFilename = await encryptText(textKey, 'document.pdf');
-
-// 4. Store metadata
-const metadata = {
-    name: encryptedFilename,  // Text-encrypted filename
-    iv: encrypted.ivb64,      // Base64-encoded IV
-    thumbsize: encrypted.thumbsize
-};
-
-// 5. Upload encrypted.blob and metadata to server
-```
-
-### Decrypting Media
-
-```typescript
-import { deriveKey, decryptFile, decryptFileThumb, decryptText } from '@redseat/api';
-
-// 1. Derive keys
-const fileKey = await deriveKey('user-password', 'file');
-const textKey = await deriveKey('user-password', 'text');
-
-// 2. Decrypt filename
-const filename = await decryptText(textKey, media.name);
-
-// 3. Decrypt thumbnail (if server returns full blob)
-const thumb = await decryptFileThumb(fileKey, encryptedBlob);
-
-// OR if server returns only the thumb portion:
-import { uint8ArrayFromBase64, decryptBuffer } from '@redseat/api';
-const iv = uint8ArrayFromBase64(media.iv);
-const thumb = await decryptBuffer(fileKey, iv, thumbBlob);
-
-// 4. Decrypt file
-const fileData = await decryptFile(fileKey, encryptedBlob);
-```
-
----
-
-## Important Notes and Gotchas
-
-### Key Management
-
-1. **Never reuse keys across different passphrases**: Each passphrase generates unique keys
-2. **Store keys securely**: Keys are not extractable, so they must be re-derived from the passphrase each time
-3. **Text vs File keys**: Always use the correct key type:
-   - Text key for: filenames, tags, folder names, any text metadata
-   - File key for: file contents, thumbnails, any binary data
-
-### IV Handling
-
-1. **Never reuse IVs**: Always generate a new IV for each encryption operation
-2. **Store IVs securely**: The IV is not secret but must be stored to decrypt data
-3. **IV format**: 
-   - Stored in metadata as base64-encoded string
-   - Used in decryption as `Uint8Array` (convert using `uint8ArrayFromBase64`)
-
-### File Format Compatibility
-
-1. **Endianness**: The file format uses big-endian for size fields, but decryption functions support both for backward compatibility
-2. **Info size**: Currently always 0, but the format reserves space for future use
-3. **MIME types**: Padded to fixed lengths (32 bytes for thumb, 256 bytes for file)
-
-### Error Handling
-
-- **Invalid format**: Functions throw errors if data format is incorrect
-- **Wrong key**: Decryption with wrong key may not throw an error but will produce garbage data
-- **Missing key**: Always check if key is set before attempting decryption
-
-### Performance Considerations
-
-1. **Key derivation**: PBKDF2 with 1000 iterations is intentionally slow to prevent brute-force attacks
-2. **Large files**: Encryption/decryption of large files may take time - consider showing progress indicators
-3. **Memory**: Large files are loaded into memory - be mindful of memory constraints on mobile devices
-
----
-
-## Migration Notes
-
-### Filename Encryption Change
-
-**Old format (deprecated):**
-- Filenames were encrypted using `encryptBuffer` with the file key
-- Stored as base64url-encoded encrypted buffer
-
-**New format (current):**
-- Filenames are encrypted using `encryptText` with the text key
-- Stored in format: `${base64Url(IV)}.${base64Url(encryptedData)}`
-- This matches the format used for other text data (tags, folder names)
-
-**Backward compatibility:**
-- The `tryDecryptFilename` function in `LibraryStore` handles both formats
-- Old filenames can still be decrypted using the old method
-- New uploads use the new text encryption format
-
----
-
-## Testing
-
-The encryption module includes comprehensive tests in `packages/api/src/encryption.test.ts`:
-
-- Key derivation tests
-- Text encryption/decryption tests
-- Buffer encryption/decryption tests
-- File encryption/decryption tests
-- Thumbnail extraction tests
-- Cross-platform compatibility tests
-
-Run tests with:
-```bash
-cd packages/api
-npm test
-```
-
----
-
-## Related Files
-
-- **`packages/api/src/crypto.ts`**: Cross-platform crypto utilities
-- **`packages/api/src/library.ts`**: LibraryApi class that uses encryption functions
-- **`src/contexts/LibraryStore.ts`**: Frontend store that uses encryption for media management
-- **`src/lib/encryption.ts`**: Legacy encryption implementation (being phased out)
-
----
-
-## Security Considerations
-
-1. **Key derivation**: Uses PBKDF2 with SHA-1 (1000 iterations) - consider increasing iterations for higher security
-2. **Key storage**: Keys are never stored, only derived from passphrases
-3. **IV generation**: Uses cryptographically secure random number generation
-4. **Key extraction**: Keys are marked as non-extractable for security
-5. **Passphrase handling**: Never log or store passphrases in plaintext
-
----
-
-## Future Improvements
-
-Potential enhancements to consider:
-
-1. **Argon2 support**: Consider migrating from PBKDF2 to Argon2 for better security
-2. **AEAD modes**: Consider using AES-GCM for authenticated encryption
-3. **Key rotation**: Add support for key rotation without re-encrypting all data
-4. **Streaming encryption**: Support for encrypting/decrypting large files in chunks
-5. **Performance**: Optimize for large file encryption on mobile devices
-
----
-
-## Questions or Issues?
-
-If you encounter issues or have questions about the encryption module:
-
-1. Check the test files for usage examples
-2. Review the error messages - they often indicate the specific problem
-3. Verify that you're using the correct key type (text vs file)
-4. Ensure IVs match between encryption and decryption
-5. Check that data formats match expected structures
-
+# Encryption Module Documentation
+
+## Overview
+
+The encryption module (`packages/api/src/encryption.ts`) provides cross-platform encryption and decryption functions for text and binary data. It uses the Web Crypto API (AES-CBC 256-bit encryption) and is compatible with Node.js, Web browsers, and React Native/Expo.
+
+## Key Concepts
+
+### Key Derivation (PBKDF2)
+
+Keys are derived from passphrases using **PBKDF2** (Password-Based Key Derivation Function 2) with:
+- **Hash algorithm**: SHA-1
+- **Iterations**: 1000
+- **Key length**: 256 bits (AES-256)
+- **Salt**: Different salts for text and file encryption
+  - Text encryption salt: `a1209660b32cca003630cb963f730b54`
+  - File encryption salt: `e5709660b22ab0803630cb963f703b83`
+
+**Important**: Text and file encryption use different keys derived from the same passphrase but with different salts. This means:
+- Text data (filenames, tags, folder names) uses the "text" key
+- Binary data (file contents, thumbnails) uses the "file" key
+- Both keys must be derived from the same passphrase to decrypt data encrypted with that passphrase
+
+### Encryption Algorithm
+
+- **Algorithm**: AES-CBC (Advanced Encryption Standard in Cipher Block Chaining mode)
+- **Key size**: 256 bits
+- **IV (Initialization Vector)**: 16 bytes, randomly generated for each encryption operation
+
+### Encoding Formats
+
+- **Base64**: Standard base64 encoding (uses `+` and `/` characters)
+- **Base64URL**: URL-safe base64 encoding (uses `-` and `_` instead of `+` and `/`, padding removed)
+- Text encryption uses Base64URL for the final output to ensure URL safety
+
+## Core Functions
+
+### `deriveKey(passPhrase: string, type: 'text' | 'file'): Promise<CryptoKey>`
+
+Derives a cryptographic key from a passphrase using PBKDF2.
+
+**Parameters:**
+- `passPhrase`: The password/passphrase to derive the key from
+- `type`: Either `'text'` for text encryption or `'file'` for file/binary encryption
+
+**Returns:** A `CryptoKey` object suitable for AES-CBC encryption/decryption
+
+**Example:**
+```typescript
+const textKey = await deriveKey('my-password', 'text');
+const fileKey = await deriveKey('my-password', 'file');
+```
+
+**Note:** The returned key is not extractable (cannot be exported) for security reasons.
+
+---
+
+### `getRandomIV(): Uint8Array`
+
+Generates a random 16-byte Initialization Vector (IV) for encryption operations.
+
+**Returns:** A `Uint8Array` of 16 random bytes
+
+**Example:**
+```typescript
+const iv = getRandomIV();
+```
+
+**Important:** A new IV must be generated for each encryption operation. Never reuse IVs with the same key.
+
+---
+
+## Text Encryption
+
+### `encryptText(key: CryptoKey, text: string): Promise<string>`
+
+Encrypts a text string using AES-CBC encryption.
+
+**Parameters:**
+- `key`: The CryptoKey to use for encryption (should be derived with `type: 'text'`)
+- `text`: The plaintext string to encrypt
+
+**Returns:** A string in the format: `${base64Url(IV)}.${base64Url(encryptedData)}`
+
+**Format:**
+- The IV and encrypted data are both base64url encoded
+- They are concatenated with a `.` (dot) separator
+- Example: `SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p`
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'text');
+const encrypted = await encryptText(key, 'Hello World');
+// Returns: "SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p"
+```
+
+**Use cases:**
+- Encrypting filenames
+- Encrypting tag names
+- Encrypting folder names
+- Any text metadata that needs to be encrypted
+
+---
+
+### `decryptText(key: CryptoKey, encryptedText: string, iv?: ArrayBuffer | Uint8Array): Promise<string>`
+
+Decrypts a text string that was encrypted with `encryptText`.
+
+**Parameters:**
+- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
+- `encryptedText`: The encrypted string in format `${IV}.${encryptedData}` OR just the encrypted data if IV is provided separately
+- `iv`: (Optional) If provided, `encryptedText` should contain only the encrypted data (without the IV prefix)
+
+**Returns:** The decrypted plaintext string
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'text');
+const decrypted = await decryptText(key, 'SGVsbG8gV29ybGQ.5Xq3K8mN2pQ9rT1vW4xY7zA0bC3dE6fG8hI1jK2lM3nO4p');
+// Returns: "Hello World"
+```
+
+**Error handling:**
+- Throws an error if the encrypted text format is invalid (not in `IV.encryptedData` format)
+- Throws an error if decryption fails (wrong key, corrupted data, etc.)
+
+---
+
+## Binary Data Encryption
+
+### `encryptBuffer(key: CryptoKey, iv: ArrayBuffer | Uint8Array, buffer: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>`
+
+Encrypts binary data (ArrayBuffer or Uint8Array) using AES-CBC encryption.
+
+**Parameters:**
+- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
+- `iv`: The 16-byte Initialization Vector (use `getRandomIV()`)
+- `buffer`: The binary data to encrypt
+
+**Returns:** An ArrayBuffer containing the encrypted data
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const iv = getRandomIV();
+const data = new Uint8Array([1, 2, 3, 4, 5]);
+const encrypted = await encryptBuffer(key, iv, data);
+```
+
+**Use cases:**
+- Encrypting file contents
+- Encrypting thumbnails
+- Encrypting any binary data
+
+---
+
+### `decryptBuffer(key: CryptoKey, iv: ArrayBuffer | Uint8Array, buffer: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>`
+
+Decrypts binary data that was encrypted with `encryptBuffer`.
+
+**Parameters:**
+- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
+- `iv`: The same IV that was used during encryption
+- `buffer`: The encrypted binary data
+
+**Returns:** An ArrayBuffer containing the decrypted data
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const iv = /* same IV used for encryption */;
+const decrypted = await decryptBuffer(key, iv, encryptedData);
+```
+
+**Important:** The IV must be exactly the same as the one used during encryption. Using a different IV will result in corrupted decrypted data (though it may not throw an error).
+
+---
+
+## File Encryption (Structured Format)
+
+### File Format Structure
+
+Files encrypted with `encryptFile` follow a specific binary structure:
+
+```
+[16 bytes: IV]
+[4 bytes: Thumbnail size (big-endian)]
+[4 bytes: Info size (big-endian, currently always 0)]
+[32 bytes: Thumbnail MIME type (padded)]
+[256 bytes: File MIME type (padded)]
+[T bytes: Encrypted thumbnail data]
+[I bytes: Encrypted info data (currently always 0 bytes)]
+[F bytes: Encrypted file data]
+```
+
+**Byte offsets:**
+- `0-15`: IV (16 bytes)
+- `16-19`: Thumbnail size (4 bytes, big-endian)
+- `20-23`: Info size (4 bytes, big-endian)
+- `24-55`: Thumbnail MIME type (32 bytes, null-padded)
+- `56-311`: File MIME type (256 bytes, null-padded)
+- `312+`: Encrypted thumbnail (length = thumbnail size)
+- `312 + thumbnailSize +`: Encrypted file data
+
+**Endianness:** Sizes are stored in **big-endian** format. The decryption functions try big-endian first, then fall back to little-endian for backward compatibility.
+
+---
+
+### `encryptFile(key: CryptoKey, options: EncryptFileOptions): Promise<EncryptedFile>`
+
+Encrypts a file with its thumbnail and metadata into a structured binary format.
+
+**Parameters:**
+- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
+- `options`: An object containing:
+  - `filename`: The original filename (will be encrypted separately)
+  - `buffer`: The file data to encrypt (ArrayBuffer or Uint8Array)
+  - `thumb`: The thumbnail data to encrypt (ArrayBuffer or Uint8Array, can be empty)
+  - `thumbMime`: MIME type of the thumbnail (e.g., `'image/jpeg'`)
+  - `mime`: MIME type of the file (e.g., `'image/png'`)
+
+**Returns:** An `EncryptedFile` object containing:
+- `filename`: Base64URL-encoded encrypted filename (encrypted with the same IV as the file)
+- `ivb64`: Base64-encoded IV (for storage in metadata)
+- `thumbsize`: Size of the encrypted thumbnail in bytes
+- `blob`: The complete encrypted file structure as an ArrayBuffer
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const fileData = await file.arrayBuffer();
+const thumbData = await thumbnail.arrayBuffer();
+
+const encrypted = await encryptFile(key, {
+    filename: 'photo.jpg',
+    buffer: fileData,
+    thumb: thumbData,
+    thumbMime: 'image/jpeg',
+    mime: 'image/jpeg'
+});
+
+// encrypted.filename: base64url encoded encrypted filename
+// encrypted.ivb64: base64 encoded IV (store this in metadata)
+// encrypted.thumbsize: size of encrypted thumbnail
+// encrypted.blob: complete encrypted file structure
+```
+
+**Important notes:**
+- The filename is encrypted separately using `encryptBuffer` with the same IV
+- The filename is returned as base64url-encoded (for URL safety)
+- The IV is returned as base64-encoded (for storage in database metadata)
+- All data (file, thumbnail, filename) uses the same IV
+
+---
+
+### `decryptFile(key: CryptoKey, buffer: ArrayBuffer): Promise<ArrayBuffer>`
+
+Decrypts the file data from an encrypted file structure.
+
+**Parameters:**
+- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
+- `buffer`: The complete encrypted file structure (as returned by `encryptFile`)
+
+**Returns:** An ArrayBuffer containing the decrypted file data
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const encryptedBlob = /* encrypted file blob */;
+const decryptedFile = await decryptFile(key, encryptedBlob);
+```
+
+**How it works:**
+1. Extracts the IV from the first 16 bytes
+2. Reads the thumbnail size (tries big-endian first, falls back to little-endian)
+3. Reads the info size
+4. Calculates the offset to the encrypted file data
+5. Decrypts and returns the file data
+
+---
+
+### `decryptFileThumb(key: CryptoKey, buffer: ArrayBuffer): Promise<ArrayBuffer>`
+
+Decrypts the thumbnail from an encrypted file structure.
+
+**Parameters:**
+- `key`: The CryptoKey to use for decryption (must match the key used for encryption)
+- `buffer`: The complete encrypted file structure (as returned by `encryptFile`)
+
+**Returns:** An ArrayBuffer containing the decrypted thumbnail data, or an empty ArrayBuffer if no thumbnail exists
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const encryptedBlob = /* encrypted file blob */;
+const decryptedThumb = await decryptFileThumb(key, encryptedBlob);
+```
+
+**How it works:**
+1. Extracts the IV from the first 16 bytes
+2. Reads the thumbnail size (tries big-endian first, falls back to little-endian)
+3. If thumbnail size is 0, returns empty buffer
+4. Calculates the offset to the encrypted thumbnail (after IV, sizes, and MIME types)
+5. Decrypts and returns the thumbnail data
+
+**Note:** The server's `getThumb` API endpoint returns only the encrypted thumbnail portion (already sliced), not the full file structure. In that case, use `decryptBuffer` directly with the IV from the media metadata.
+
+---
+
+### `encryptFilename(key: CryptoKey, filename: string, iv: ArrayBuffer | Uint8Array): Promise<string>`
+
+Encrypts a filename using the same IV as the file encryption.
+
+**Parameters:**
+- `key`: The CryptoKey to use for encryption (should be derived with `type: 'file'`)
+- `filename`: The original filename to encrypt
+- `iv`: The same IV used for encrypting the file
+
+**Returns:** Base64URL-encoded encrypted filename
+
+**Example:**
+```typescript
+const key = await deriveKey('password', 'file');
+const iv = getRandomIV();
+const encryptedFilename = await encryptFilename(key, 'photo.jpg', iv);
+```
+
+**Note:** This function is used internally by `encryptFile`. For new uploads, filenames are encrypted using `encryptText` with the text key instead, which produces the format `${IV}.${encryptedData}`.
+
+---
+
+## Cross-Platform Compatibility
+
+The encryption module is designed to work across multiple platforms:
+
+### Supported Platforms
+
+1. **Web Browsers**: Uses `window.crypto.subtle` or `globalThis.crypto.subtle`
+2. **Node.js**: Uses `crypto.webcrypto.subtle` (Node.js 15+)
+3. **React Native/Expo**: Uses `globalThis.crypto.subtle` or `crypto.subtle`
+
+### Platform Detection
+
+The `crypto.ts` module automatically detects the available crypto APIs:
+
+- **`getCryptoSubtle()`**: Returns the appropriate `SubtleCrypto` implementation
+- **`getCryptoRandomValues()`**: Returns the appropriate random number generator
+
+### Base64 Encoding
+
+Base64 encoding/decoding is handled cross-platform:
+- **Node.js**: Uses `Buffer` for efficient conversion
+- **Browsers/RN**: Uses `atob`/`btoa` or manual conversion
+
+---
+
+## Usage Patterns
+
+### Complete File Upload Flow
+
+```typescript
+import { deriveKey, encryptFile, encryptText, getRandomIV } from '@redseat/api';
+
+// 1. Derive keys from passphrase
+const fileKey = await deriveKey('user-password', 'file');
+const textKey = await deriveKey('user-password', 'text');
+
+// 2. Encrypt the file
+const encrypted = await encryptFile(fileKey, {
+    filename: 'document.pdf',
+    buffer: fileArrayBuffer,
+    thumb: thumbnailArrayBuffer,
+    thumbMime: 'image/jpeg',
+    mime: 'application/pdf'
+});
+
+// 3. Encrypt the filename (for new uploads, use text encryption)
+const encryptedFilename = await encryptText(textKey, 'document.pdf');
+
+// 4. Store metadata
+const metadata = {
+    name: encryptedFilename,  // Text-encrypted filename
+    iv: encrypted.ivb64,      // Base64-encoded IV
+    thumbsize: encrypted.thumbsize
+};
+
+// 5. Upload encrypted.blob and metadata to server
+```
+
+### Decrypting Media
+
+```typescript
+import { deriveKey, decryptFile, decryptFileThumb, decryptText } from '@redseat/api';
+
+// 1. Derive keys
+const fileKey = await deriveKey('user-password', 'file');
+const textKey = await deriveKey('user-password', 'text');
+
+// 2. Decrypt filename
+const filename = await decryptText(textKey, media.name);
+
+// 3. Decrypt thumbnail (if server returns full blob)
+const thumb = await decryptFileThumb(fileKey, encryptedBlob);
+
+// OR if server returns only the thumb portion:
+import { uint8ArrayFromBase64, decryptBuffer } from '@redseat/api';
+const iv = uint8ArrayFromBase64(media.iv);
+const thumb = await decryptBuffer(fileKey, iv, thumbBlob);
+
+// 4. Decrypt file
+const fileData = await decryptFile(fileKey, encryptedBlob);
+```
+
+---
+
+## Important Notes and Gotchas
+
+### Key Management
+
+1. **Never reuse keys across different passphrases**: Each passphrase generates unique keys
+2. **Store keys securely**: Keys are not extractable, so they must be re-derived from the passphrase each time
+3. **Text vs File keys**: Always use the correct key type:
+   - Text key for: filenames, tags, folder names, any text metadata
+   - File key for: file contents, thumbnails, any binary data
+
+### IV Handling
+
+1. **Never reuse IVs**: Always generate a new IV for each encryption operation
+2. **Store IVs securely**: The IV is not secret but must be stored to decrypt data
+3. **IV format**: 
+   - Stored in metadata as base64-encoded string
+   - Used in decryption as `Uint8Array` (convert using `uint8ArrayFromBase64`)
+
+### File Format Compatibility
+
+1. **Endianness**: The file format uses big-endian for size fields, but decryption functions support both for backward compatibility
+2. **Info size**: Currently always 0, but the format reserves space for future use
+3. **MIME types**: Padded to fixed lengths (32 bytes for thumb, 256 bytes for file)
+
+### Error Handling
+
+- **Invalid format**: Functions throw errors if data format is incorrect
+- **Wrong key**: Decryption with wrong key may not throw an error but will produce garbage data
+- **Missing key**: Always check if key is set before attempting decryption
+
+### Performance Considerations
+
+1. **Key derivation**: PBKDF2 with 1000 iterations is intentionally slow to prevent brute-force attacks
+2. **Large files**: Encryption/decryption of large files may take time - consider showing progress indicators
+3. **Memory**: Large files are loaded into memory - be mindful of memory constraints on mobile devices
+
+---
+
+## Migration Notes
+
+### Filename Encryption Change
+
+**Old format (deprecated):**
+- Filenames were encrypted using `encryptBuffer` with the file key
+- Stored as base64url-encoded encrypted buffer
+
+**New format (current):**
+- Filenames are encrypted using `encryptText` with the text key
+- Stored in format: `${base64Url(IV)}.${base64Url(encryptedData)}`
+- This matches the format used for other text data (tags, folder names)
+
+**Backward compatibility:**
+- The `tryDecryptFilename` function in `LibraryStore` handles both formats
+- Old filenames can still be decrypted using the old method
+- New uploads use the new text encryption format
+
+---
+
+## Testing
+
+The encryption module includes comprehensive tests in `packages/api/src/encryption.test.ts`:
+
+- Key derivation tests
+- Text encryption/decryption tests
+- Buffer encryption/decryption tests
+- File encryption/decryption tests
+- Thumbnail extraction tests
+- Cross-platform compatibility tests
+
+Run tests with:
+```bash
+cd packages/api
+npm test
+```
+
+---
+
+## Related Files
+
+- **`packages/api/src/crypto.ts`**: Cross-platform crypto utilities
+- **`packages/api/src/library.ts`**: LibraryApi class that uses encryption functions
+- **`src/contexts/LibraryStore.ts`**: Frontend store that uses encryption for media management
+- **`src/lib/encryption.ts`**: Legacy encryption implementation (being phased out)
+
+---
+
+## Security Considerations
+
+1. **Key derivation**: Uses PBKDF2 with SHA-1 (1000 iterations) - consider increasing iterations for higher security
+2. **Key storage**: Keys are never stored, only derived from passphrases
+3. **IV generation**: Uses cryptographically secure random number generation
+4. **Key extraction**: Keys are marked as non-extractable for security
+5. **Passphrase handling**: Never log or store passphrases in plaintext
+
+---
+
+## Future Improvements
+
+Potential enhancements to consider:
+
+1. **Argon2 support**: Consider migrating from PBKDF2 to Argon2 for better security
+2. **AEAD modes**: Consider using AES-GCM for authenticated encryption
+3. **Key rotation**: Add support for key rotation without re-encrypting all data
+4. **Streaming encryption**: Support for encrypting/decrypting large files in chunks
+5. **Performance**: Optimize for large file encryption on mobile devices
+
+---
+
+## Questions or Issues?
+
+If you encounter issues or have questions about the encryption module:
+
+1. Check the test files for usage examples
+2. Review the error messages - they often indicate the specific problem
+3. Verify that you're using the correct key type (text vs file)
+4. Ensure IVs match between encryption and decryption
+5. Check that data formats match expected structures
+