@omnituum/pqc-shared 0.2.6

package/dist/fs/index.d.ts

@@ -0,0 +1,400 @@
+import { A as Argon2idParams, f as OQEHeader, H as HybridKeyMaterial, P as PasswordKeyMaterial, g as OQEMetadata, h as AlgorithmSuiteId, O as OQEEncryptResult, c as OQEDecryptResult } from '../decrypt-eSHlbh1j.js';
+export { w as ALGORITHM_SUITES, i as DEFAULT_ARGON2ID_PARAMS, D as DecryptOptions, E as EncryptOptions, F as FileInput, p as HybridDecryptOptions, n as HybridEncryptOptions, M as MIN_ARGON2ID_PARAMS, t as OQEError, r as OQEErrorCode, m as OQEMode, v as OQE_FORMAT_VERSION, x as OQE_HEADER_SIZE, u as OQE_MAGIC, q as PasswordDecryptOptions, o as PasswordEncryptOptions, s as ProgressCallback, d as decryptFile, k as decryptFileForSelf, b as decryptFileWithPassword, e as encryptFile, j as encryptFileForSelf, a as encryptFileWithPassword, l as inspectOQEFile, y as toUint8Array } from '../decrypt-eSHlbh1j.js';
+
+/**
+ * Omnituum FS - Argon2id Key Derivation
+ *
+ * Memory-hard password hashing using Argon2id (winner of PHC).
+ * Uses hash-wasm for browser-compatible WASM implementation.
+ *
+ * Security: OWASP 2024 recommended parameters.
+ */
+
+/**
+ * Derive an encryption key from a password using Argon2id.
+ *
+ * @param password - User password
+ * @param salt - 32-byte random salt (generate with generateArgon2Salt())
+ * @param params - Argon2id parameters (uses OWASP defaults if not specified)
+ * @returns 32-byte derived key suitable for AES-256
+ */
+declare function deriveKeyFromPassword(password: string, salt: Uint8Array, params?: Argon2idParams): Promise<Uint8Array>;
+/**
+ * Generate a random salt for Argon2id.
+ *
+ * @param length - Salt length in bytes (default: 32)
+ * @returns Random salt
+ */
+declare function generateArgon2Salt(length?: number): Uint8Array;
+/**
+ * Verify a password against a stored hash.
+ * Useful for vault unlocking or file password verification.
+ *
+ * @param password - Password to verify
+ * @param salt - Original salt used
+ * @param expectedKey - Expected derived key
+ * @param params - Argon2id parameters
+ * @returns true if password is correct
+ */
+declare function verifyPassword(password: string, salt: Uint8Array, expectedKey: Uint8Array, params?: Argon2idParams): Promise<boolean>;
+/**
+ * Estimate Argon2id parameters based on available memory and target time.
+ * Useful for adapting to low-memory environments.
+ *
+ * @param targetTimeMs - Target key derivation time in milliseconds
+ * @param availableMemoryMB - Available memory in megabytes
+ * @returns Estimated Argon2id parameters
+ */
+declare function estimateArgon2Params(targetTimeMs?: number, availableMemoryMB?: number): Argon2idParams;
+/**
+ * Benchmark Argon2id on current device.
+ * Returns the time in milliseconds for one derivation.
+ *
+ * @param params - Parameters to benchmark
+ * @returns Time in milliseconds
+ */
+declare function benchmarkArgon2(params?: Argon2idParams): Promise<number>;
+/**
+ * Check if Argon2id is available in current environment.
+ * Caches result after first check.
+ */
+declare function isArgon2Available(): Promise<boolean>;
+
+/**
+ * Omnituum FS - AES-256-GCM Encryption
+ *
+ * File encryption using AES-256-GCM via Web Crypto API.
+ * Provides authenticated encryption with associated data (AEAD).
+ */
+/** AES-256 key size in bytes */
+declare const AES_KEY_SIZE = 32;
+/** AES-GCM IV size in bytes (96 bits recommended by NIST) */
+declare const AES_GCM_IV_SIZE = 12;
+/** AES-GCM auth tag size in bytes (128 bits) */
+declare const AES_GCM_TAG_SIZE = 16;
+/**
+ * Import a raw 256-bit key for AES-GCM operations.
+ *
+ * @param keyBytes - 32-byte raw key material
+ * @returns CryptoKey suitable for AES-GCM encryption/decryption
+ */
+declare function importAesKey(keyBytes: Uint8Array): Promise<CryptoKey>;
+/**
+ * Generate a random 256-bit AES key.
+ *
+ * @returns CryptoKey for AES-GCM
+ */
+declare function generateAesKey(): Promise<CryptoKey>;
+/**
+ * Export a CryptoKey to raw bytes.
+ *
+ * @param key - CryptoKey to export
+ * @returns 32-byte raw key
+ */
+declare function exportAesKey(key: CryptoKey): Promise<Uint8Array>;
+/**
+ * Encrypt data using AES-256-GCM.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key (CryptoKey or 32-byte Uint8Array)
+ * @param iv - Optional 12-byte IV (generated if not provided)
+ * @param additionalData - Optional additional authenticated data (AAD)
+ * @returns Object containing IV and ciphertext (with auth tag appended)
+ */
+declare function aesEncrypt(plaintext: Uint8Array, key: CryptoKey | Uint8Array, iv?: Uint8Array, additionalData?: Uint8Array): Promise<{
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+}>;
+/**
+ * Encrypt data and return combined IV + ciphertext.
+ * Convenience method for simple encryption.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key
+ * @param additionalData - Optional AAD
+ * @returns Combined bytes: [IV (12 bytes)] [ciphertext + tag]
+ */
+declare function aesEncryptCombined(plaintext: Uint8Array, key: CryptoKey | Uint8Array, additionalData?: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt data using AES-256-GCM.
+ *
+ * @param ciphertext - Encrypted data (with auth tag appended)
+ * @param key - AES-256 key (CryptoKey or 32-byte Uint8Array)
+ * @param iv - 12-byte IV used for encryption
+ * @param additionalData - Optional additional authenticated data (must match encryption)
+ * @returns Decrypted plaintext
+ * @throws Error if authentication fails (wrong key or tampered data)
+ */
+declare function aesDecrypt(ciphertext: Uint8Array, key: CryptoKey | Uint8Array, iv: Uint8Array, additionalData?: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt combined IV + ciphertext.
+ * Convenience method for simple decryption.
+ *
+ * @param combined - Combined bytes: [IV (12 bytes)] [ciphertext + tag]
+ * @param key - AES-256 key
+ * @param additionalData - Optional AAD
+ * @returns Decrypted plaintext
+ */
+declare function aesDecryptCombined(combined: Uint8Array, key: CryptoKey | Uint8Array, additionalData?: Uint8Array): Promise<Uint8Array>;
+/** Chunk size for streaming operations (1 MB) */
+declare const STREAM_CHUNK_SIZE: number;
+/**
+ * Encrypt large data in chunks.
+ * Each chunk is encrypted with a unique IV derived from base IV + counter.
+ *
+ * Note: For files < 100MB, use regular aesEncrypt for simplicity.
+ * This is primarily for very large files where memory is a concern.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key
+ * @param onProgress - Optional progress callback
+ * @returns Encrypted data with format: [chunk count (4 bytes)] [IV] [chunks...]
+ */
+declare function aesEncryptStreaming(plaintext: Uint8Array, key: CryptoKey | Uint8Array, onProgress?: (percent: number) => void): Promise<Uint8Array>;
+/**
+ * Decrypt large data encrypted with aesEncryptStreaming.
+ *
+ * @param encrypted - Encrypted data from aesEncryptStreaming
+ * @param key - AES-256 key
+ * @param onProgress - Optional progress callback
+ * @returns Decrypted plaintext
+ */
+declare function aesDecryptStreaming(encrypted: Uint8Array, key: CryptoKey | Uint8Array, onProgress?: (percent: number) => void): Promise<Uint8Array>;
+
+/**
+ * Omnituum FS - OQE Binary Format
+ *
+ * Reader/writer for the .oqe (Omnituum Quantum Encrypted) file format.
+ * Implements a documented, stable binary format for encrypted files.
+ */
+
+/**
+ * Write an OQE file header.
+ *
+ * @param header - Header data
+ * @returns 30-byte header buffer
+ */
+declare function writeOQEHeader(header: OQEHeader): Uint8Array;
+/**
+ * Parse an OQE file header.
+ *
+ * @param data - File data (at least 30 bytes)
+ * @returns Parsed header
+ * @throws OQEError if header is invalid
+ */
+declare function parseOQEHeader(data: Uint8Array): OQEHeader;
+/**
+ * Serialize hybrid mode key material.
+ *
+ * Format:
+ * - X25519 ephemeral PK (32 bytes)
+ * - X25519 nonce (24 bytes)
+ * - X25519 wrapped key length (2 bytes)
+ * - X25519 wrapped key (variable)
+ * - Kyber ciphertext length (2 bytes)
+ * - Kyber ciphertext (variable, ~1088 bytes)
+ * - Kyber nonce (24 bytes)
+ * - Kyber wrapped key length (2 bytes)
+ * - Kyber wrapped key (variable)
+ */
+declare function serializeHybridKeyMaterial(km: HybridKeyMaterial): Uint8Array;
+/**
+ * Parse hybrid mode key material.
+ */
+declare function parseHybridKeyMaterial(data: Uint8Array): HybridKeyMaterial;
+/**
+ * Serialize password mode key material.
+ *
+ * Format:
+ * - Salt (32 bytes)
+ * - Memory cost (4 bytes, KiB)
+ * - Time cost (4 bytes)
+ * - Parallelism (4 bytes)
+ */
+declare function serializePasswordKeyMaterial(km: PasswordKeyMaterial): Uint8Array;
+/**
+ * Parse password mode key material.
+ */
+declare function parsePasswordKeyMaterial(data: Uint8Array): PasswordKeyMaterial;
+/**
+ * Serialize metadata to JSON bytes.
+ */
+declare function serializeMetadata(metadata: OQEMetadata): Uint8Array;
+/**
+ * Parse metadata from JSON bytes.
+ */
+declare function parseMetadata(data: Uint8Array): OQEMetadata;
+interface OQEFileComponents {
+    header: OQEHeader;
+    keyMaterial: Uint8Array;
+    encryptedMetadata: Uint8Array;
+    encryptedContent: Uint8Array;
+}
+/**
+ * Assemble a complete OQE file from components.
+ */
+declare function assembleOQEFile(components: OQEFileComponents): Uint8Array;
+/**
+ * Parse a complete OQE file into components.
+ */
+declare function parseOQEFile(data: Uint8Array): OQEFileComponents;
+/** OQE file extension */
+declare const OQE_EXTENSION = ".oqe";
+/**
+ * Add .oqe extension to a filename.
+ */
+declare function addOQEExtension(filename: string): string;
+/**
+ * Remove .oqe extension from a filename.
+ */
+declare function removeOQEExtension(filename: string): string;
+/**
+ * Check if a file is an OQE file (by extension or magic bytes).
+ */
+declare function isOQEFile(filenameOrData: string | Uint8Array): boolean;
+/** OQE MIME type */
+declare const OQE_MIME_TYPE = "application/x-omnituum-encrypted";
+/**
+ * Get a display-friendly algorithm name from suite ID.
+ */
+declare function getAlgorithmName(suiteId: AlgorithmSuiteId): string;
+
+/**
+ * Omnituum FS - Browser File Utilities
+ *
+ * Utilities for handling files in the browser environment:
+ * - Drag and drop support
+ * - File download/upload
+ * - Blob/URL handling
+ */
+
+/**
+ * Download encrypted file to user's device.
+ *
+ * @param result - Encryption result from encryptFile()
+ */
+declare function downloadEncryptedFile(result: OQEEncryptResult): void;
+/**
+ * Download decrypted file to user's device.
+ *
+ * @param result - Decryption result from decryptFile()
+ */
+declare function downloadDecryptedFile(result: OQEDecryptResult): void;
+/**
+ * Download a Blob as a file.
+ */
+declare function downloadBlob(blob: Blob, filename: string): void;
+/**
+ * Download bytes as a file.
+ */
+declare function downloadBytes(data: Uint8Array, filename: string, mimeType?: string): void;
+/**
+ * Read a File object as Uint8Array.
+ */
+declare function readFile(file: File): Promise<Uint8Array>;
+/**
+ * Read a File object as text.
+ */
+declare function readFileAsText(file: File): Promise<string>;
+/**
+ * Read a File object as Data URL.
+ */
+declare function readFileAsDataURL(file: File): Promise<string>;
+interface DropZoneOptions {
+    /** Element to attach drop zone to */
+    element: HTMLElement;
+    /** Called when valid files are dropped */
+    onDrop: (files: File[]) => void;
+    /** Called when drag enters */
+    onDragEnter?: () => void;
+    /** Called when drag leaves */
+    onDragLeave?: () => void;
+    /** Filter for accepted file types (e.g., ['image/*', '.pdf']) */
+    accept?: string[];
+    /** Allow multiple files */
+    multiple?: boolean;
+}
+/**
+ * Create a drop zone for file drag and drop.
+ * Returns a cleanup function to remove listeners.
+ */
+declare function createDropZone(options: DropZoneOptions): () => void;
+interface FileInputOptions {
+    /** Filter for accepted file types */
+    accept?: string[];
+    /** Allow multiple files */
+    multiple?: boolean;
+}
+/**
+ * Open file picker dialog and return selected files.
+ */
+declare function openFilePicker(options?: FileInputOptions): Promise<File[]>;
+/**
+ * Open file picker for OQE files specifically.
+ */
+declare function openOQEFilePicker(multiple?: boolean): Promise<File[]>;
+/**
+ * Open file picker for any file to encrypt.
+ */
+declare function openFileToEncrypt(multiple?: boolean): Promise<File[]>;
+/**
+ * Create a Blob from encryption result.
+ */
+declare function encryptResultToBlob(result: OQEEncryptResult): Blob;
+/**
+ * Create a Blob from decryption result.
+ */
+declare function decryptResultToBlob(result: OQEDecryptResult): Blob;
+/**
+ * Create an object URL for a Blob.
+ * Remember to call URL.revokeObjectURL() when done.
+ */
+declare function createObjectURL(blob: Blob): string;
+/**
+ * Create a Data URL from bytes.
+ */
+declare function bytesToDataURL(data: Uint8Array, mimeType: string): Promise<string>;
+interface FileInfo {
+    /** Filename */
+    name: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    type: string;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** Is this an OQE file? */
+    isOQE: boolean;
+    /** Human-readable size */
+    sizeFormatted: string;
+}
+/**
+ * Get information about a file.
+ */
+declare function getFileInfo(file: File): FileInfo;
+/**
+ * Format file size for display.
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * Copy text to clipboard.
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/**
+ * Check if running in a browser environment.
+ */
+declare function isBrowser(): boolean;
+/**
+ * Check if Web Crypto API is available.
+ */
+declare function isWebCryptoAvailable(): boolean;
+/**
+ * Check if File API is available.
+ */
+declare function isFileAPIAvailable(): boolean;
+/**
+ * Check if drag and drop is supported.
+ */
+declare function isDragDropSupported(): boolean;
+
+export { AES_GCM_IV_SIZE, AES_GCM_TAG_SIZE, AES_KEY_SIZE, AlgorithmSuiteId, Argon2idParams, HybridKeyMaterial, OQEDecryptResult, OQEEncryptResult, OQEHeader, OQEMetadata, OQE_EXTENSION, OQE_MIME_TYPE, PasswordKeyMaterial, STREAM_CHUNK_SIZE, addOQEExtension, aesDecrypt, aesDecryptCombined, aesDecryptStreaming, aesEncrypt, aesEncryptCombined, aesEncryptStreaming, assembleOQEFile, benchmarkArgon2, bytesToDataURL, copyToClipboard, createDropZone, createObjectURL, decryptResultToBlob, deriveKeyFromPassword, downloadBlob, downloadBytes, downloadDecryptedFile, downloadEncryptedFile, encryptResultToBlob, estimateArgon2Params, exportAesKey, formatFileSize, generateAesKey, generateArgon2Salt, getAlgorithmName, getFileInfo, importAesKey, isArgon2Available, isBrowser, isDragDropSupported, isFileAPIAvailable, isOQEFile, isWebCryptoAvailable, openFilePicker, openFileToEncrypt, openOQEFilePicker, parseHybridKeyMaterial, parseMetadata, parseOQEFile, parseOQEHeader, parsePasswordKeyMaterial, readFile, readFileAsDataURL, readFileAsText, removeOQEExtension, serializeHybridKeyMaterial, serializeMetadata, serializePasswordKeyMaterial, verifyPassword, writeOQEHeader };