@zkim-platform/file-format 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1918 @@
+/**
+ * Singleton Pattern Base Classes for @zkim/file-format
+ * Lightweight singleton implementation without platform dependencies
+ */
+/**
+ * Base Singleton Class
+ * Use this for simple singletons that don't require initialization
+ */
+declare abstract class SingletonBase {
+    protected static instances: Map<new () => unknown, unknown>;
+    /**
+     * Protected constructor to prevent direct instantiation
+     */
+    protected constructor();
+    /**
+     * Get or create the singleton instance
+     */
+    static getInstance<T>(this: new () => T): T;
+    /**
+     * Clear all singleton instances (useful for testing)
+     */
+    static clearInstances(): void;
+    /**
+     * Check if an instance exists
+     */
+    static hasInstance<T>(this: new () => T): boolean;
+}
+/**
+ * Service Base Class
+ * Use this for services that require initialization and cleanup
+ */
+declare abstract class ServiceBase extends SingletonBase {
+    protected initialized: boolean;
+    protected initializing: boolean;
+    /**
+     * Public constructor for ServiceBase extensions
+     * Required because getServiceInstance() calls new this() internally
+     */
+    constructor();
+    /**
+     * Initialize the service
+     * Must be async and return Promise<void>
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Cleanup the service
+     * Must be async and return Promise<void>
+     */
+    abstract cleanup(): Promise<void>;
+    /**
+     * Check if the service is ready
+     */
+    isReady(): boolean;
+    /**
+     * Get service status
+     */
+    getStatus(): {
+        initialized: boolean;
+        [key: string]: unknown;
+    };
+    /**
+     * Ensure service is initialized before use
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Get or create and initialize the singleton instance
+     * This is the ONLY way to get ServiceBase instances
+     */
+    static getServiceInstance<T extends ServiceBase>(this: new () => T): Promise<T>;
+}
+
+/**
+ * Logger Interface and Console Implementation
+ * Lightweight logging adapter for @zkim/file-format package
+ */
+declare enum LogLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}
+interface ILogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, context?: Record<string, unknown>): void;
+}
+/**
+ * Console Logger Implementation
+ * Simple console-based logger for standalone package usage
+ */
+declare class ConsoleLogger implements ILogger {
+    private logLevel;
+    constructor(logLevel?: LogLevel);
+    setLogLevel(level: LogLevel): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, context?: Record<string, unknown>): void;
+    private shouldLog;
+    private formatMessage;
+}
+/**
+ * Default logger instance
+ */
+declare const defaultLogger: ILogger;
+
+/**
+ * ZKIM File Format Types - Single Source of Truth
+ *
+ * This file contains all ZKIM file format-related types including core file format,
+ * archive format, message format, and service configuration types.
+ */
+/**
+ * ZKIM File Header Interface
+ */
+interface ZkimFileHeader {
+    magic: "ZKIM";
+    version: number;
+    flags: number;
+    platformKeyId: string;
+    userId: string;
+    fileId: string;
+    createdAt: number;
+    chunkCount: number;
+    totalSize: number;
+    compressionType: number;
+    encryptionType: number;
+    hashType: number;
+    signatureType: number;
+}
+/**
+ * ZKIM File Chunk Interface
+ */
+interface ZkimFileChunk {
+    chunkIndex: number;
+    chunkSize: number;
+    compressedSize: number;
+    encryptedSize: number;
+    nonce: Uint8Array;
+    encryptedData: Uint8Array;
+    integrityHash: Uint8Array;
+    padding: Uint8Array;
+}
+/**
+ * Base File Metadata Interface
+ * Used as base for ZKIM file metadata
+ */
+interface FileMetadata {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    hash: string;
+    createdAt: number;
+    updatedAt: number;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    accessControl?: {
+        readAccess: string[];
+        writeAccess: string[];
+        deleteAccess: string[];
+    };
+    retentionPolicy?: {
+        expiresAt?: number;
+        maxAccessCount?: number;
+        autoDelete?: boolean;
+    };
+}
+/**
+ * ZKIM File Metadata Interface
+ * Extends base FileMetadata with ZKIM-specific fields
+ */
+interface ZkimFileMetadata extends Omit<FileMetadata, "id" | "name" | "size" | "hash" | "updatedAt"> {
+    fileName: string;
+    customFields?: Record<string, unknown>;
+    userId?: string;
+    createdAt: number;
+}
+/**
+ * ZKIM File Interface
+ */
+interface ZkimFile {
+    header: ZkimFileHeader;
+    chunks: ZkimFileChunk[];
+    metadata: ZkimFileMetadata;
+    platformSignature: Uint8Array;
+    userSignature: Uint8Array;
+    contentSignature: Uint8Array;
+}
+/**
+ * ZKIM File Result Interface
+ */
+interface ZkimFileResult {
+    success: boolean;
+    file: ZkimFile;
+    zkimFile: ZkimFile;
+    objectId: string;
+    size: number;
+    chunks: number;
+    processingTime: number;
+    compressionRatio: number;
+    encryptionOverhead: number;
+}
+/**
+ * ZKIM File Search Result Interface
+ */
+interface ZkimFileSearchResult {
+    fileId: string;
+    objectId: string;
+    relevance: number;
+    metadata: Partial<ZkimFileMetadata>;
+    accessLevel: "full" | "metadata" | "none";
+    lastAccessed: number;
+}
+/**
+ * ZKIM File Service Configuration Interface
+ */
+interface ZKIMFileServiceConfig {
+    enableCompression: boolean;
+    enableDeduplication: boolean;
+    chunkSize: number;
+    compressionLevel: number;
+    compressionAlgorithm: "brotli" | "gzip";
+    enableSearchableEncryption: boolean;
+    enableIntegrityValidation: boolean;
+    enableMetadataIndexing: boolean;
+    maxFileSize: number;
+    enableStreaming: boolean;
+}
+/**
+ * ZKIM Encryption Configuration Interface
+ */
+interface ZkimEncryptionConfig {
+    enableThreeLayerEncryption: boolean;
+    enableKeyRotation: boolean;
+    enablePerfectForwardSecrecy: boolean;
+    enableCompromiseDetection: boolean;
+    defaultAlgorithm: "xchacha20-poly1305" | "aes-256-gcm";
+    keySize: number;
+    nonceSize: number;
+    compressionEnabled: boolean;
+    compressionAlgorithm: "brotli" | "gzip";
+    compressionLevel: number;
+    algorithm?: string;
+    keyRotationInterval?: number;
+    maxKeyAge?: number;
+    enableKeyValidation?: boolean;
+    enablePerformanceOptimization?: boolean;
+}
+/**
+ * ZKIM Integrity Configuration Interface
+ */
+interface ZkimIntegrityConfig {
+    enableHeaderValidation: boolean;
+    enableChunkValidation: boolean;
+    enableSignatureValidation: boolean;
+    enableMetadataValidation: boolean;
+    enableTamperDetection: boolean;
+    validationThreshold: number;
+    enableAuditLogging: boolean;
+    enablePerformanceMetrics: boolean;
+    hashAlgorithm: "blake3" | "sha256" | "sha512";
+    signatureAlgorithm: "ed25519" | "ecdsa" | "rsa";
+}
+/**
+ * Compression Configuration Interface
+ */
+interface CompressionConfig {
+    algorithm: "lz4" | "zstd" | "brotli" | "gzip";
+    level: number;
+    enableDictionary: boolean;
+    enableStreaming: boolean;
+    maxDictionarySize: number;
+    enableAdaptiveCompression: boolean;
+}
+/**
+ * Compression Result Interface
+ */
+interface CompressionResult {
+    originalSize: number;
+    compressedSize: number;
+    compressedData: Uint8Array;
+    compressionRatio: number;
+    compressionTime: number;
+    decompressionTime: number;
+    algorithm: string;
+    level: number;
+}
+/**
+ * Integrity Validation Result Interface
+ */
+interface IntegrityValidationResult {
+    isValid: boolean;
+    validationLevel: "none" | "basic" | "full";
+    headerValid: boolean;
+    chunksValid: boolean;
+    signaturesValid: boolean;
+    metadataValid: boolean;
+    errors: string[];
+    warnings: string[];
+    validationTime: number;
+}
+/**
+ * Searchable Encryption Configuration Interface
+ */
+interface SearchableEncryptionConfig {
+    enableOPRF: boolean;
+    enableRateLimiting: boolean;
+    enableQueryBatching: boolean;
+    enableTrapdoorRotation: boolean;
+    epochDuration: number;
+    maxQueriesPerEpoch: number;
+    bucketSizes: number[];
+    minCoverage: number;
+    enablePrivacyEnhancement: boolean;
+    enableResultPadding: boolean;
+    enableQueryLogging: boolean;
+}
+/**
+ * Indexed File Interface
+ */
+interface IndexedFile {
+    fileId: string;
+    objectId: string;
+    userId: string;
+    metadata: ZkimFileMetadata;
+    trapdoors: string[];
+    indexedAt: number;
+    lastAccessed: number;
+    accessCount: number;
+    privacyLevel: "high" | "medium" | "low";
+}
+/**
+ * Query History Entry Interface
+ */
+interface QueryHistoryEntry {
+    queryId: string;
+    query: string;
+    userId: string;
+    timestamp: number;
+    resultsCount: number;
+    processingTime: number;
+    privacyLevel: "high" | "medium" | "low";
+    trapdoorId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Search Query Interface
+ */
+interface SearchQuery {
+    queryId: string;
+    query: string;
+    userId: string;
+    timestamp: number;
+    priority: "high" | "medium" | "low";
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Search Result Interface
+ */
+interface SearchResult {
+    queryId: string;
+    results: ZkimFileSearchResult[];
+    totalResults: number;
+    processingTime: number;
+    privacyLevel: "high" | "medium" | "low";
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Trapdoor Interface
+ */
+interface Trapdoor {
+    trapdoorId: string;
+    userId: string;
+    query: string;
+    epoch: number;
+    expiresAt: number;
+    usageCount: number;
+    maxUsage: number;
+    isRevoked: boolean;
+}
+/**
+ * Query Batch Configuration Interface
+ */
+interface QueryBatchConfig {
+    enableBatching: boolean;
+    batchSize: number;
+    batchTimeout: number;
+    maxConcurrentBatches: number;
+    enableLoadBalancing: boolean;
+    enableQueryOptimization: boolean;
+}
+/**
+ * Query Batch Interface
+ */
+interface QueryBatch {
+    batchId: string;
+    queries: SearchQuery[];
+    createdAt: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    results: SearchResult[];
+    processingTime: number;
+    errorCount: number;
+}
+/**
+ * Trapdoor Rotation Configuration Interface
+ */
+interface TrapdoorRotationConfig {
+    enableRotation: boolean;
+    rotationInterval: number;
+    gracePeriod: number;
+    enableRevocation: boolean;
+    maxActiveTrapdoors: number;
+    enableUsageTracking: boolean;
+}
+/**
+ * Trapdoor Rotation Event Interface
+ */
+interface TrapdoorRotationEvent {
+    eventId: string;
+    userId: string;
+    trapdoorId: string;
+    eventType: "created" | "rotated" | "revoked" | "expired";
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage Pattern Interface
+ */
+interface UsagePattern {
+    userId: string;
+    queryPatterns: string[];
+    usageFrequency: number;
+    lastUsed: number;
+    totalUsage: number;
+    anomalyScore: number;
+}
+/**
+ * Anomaly Detector Class
+ */
+declare class AnomalyDetector {
+    detectAnomaly(usagePattern: UsagePattern, currentUsage: number): {
+        isAnomaly: boolean;
+        score: number;
+        reason: string;
+    };
+}
+/**
+ * Cached Result Interface
+ */
+interface CachedResult {
+    result: SearchResult;
+    timestamp: number;
+    accessCount: number;
+}
+/**
+ * Query Batcher Performance Metrics Interface
+ */
+interface QueryBatcherPerformanceMetrics {
+    totalBatches: number;
+    totalQueries: number;
+    totalProcessingTime: number;
+    successfulQueries: number;
+    failedQueries: number;
+    averageProcessingTime: number;
+    successRate: number;
+    averageBatchTime: number;
+    averageQueryTime: number;
+    cacheHitRate: number;
+    loadBalancingEfficiency: number;
+    updateBatchMetrics(batchTime: number): void;
+    updateQueryMetrics(queryTime: number, success: boolean): void;
+    reset(): void;
+}
+/**
+ * Metadata With Access Level Interface
+ */
+interface MetadataWithAccessLevel {
+    fileName?: string;
+    accessLevel?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Storage Interface for @zkim/file-format
+ * Abstract storage backend for different storage implementations
+ */
+/**
+ * Storage backend interface
+ * Implement this interface to provide custom storage backends
+ */
+interface IStorageBackend {
+    /**
+     * Store data with the given key
+     */
+    set(key: string, value: Uint8Array): Promise<void>;
+    /**
+     * Retrieve data by key
+     */
+    get(key: string): Promise<Uint8Array | null>;
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete data by key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all data
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all keys
+     */
+    keys(): Promise<string[]>;
+}
+/**
+ * In-memory storage implementation
+ * Useful for testing or temporary storage
+ */
+declare class InMemoryStorage implements IStorageBackend {
+    private storage;
+    set(key: string, value: Uint8Array): Promise<void>;
+    get(key: string): Promise<Uint8Array | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+}
+/**
+ * LocalStorage-based storage implementation
+ * For browser environments
+ */
+declare class LocalStorageBackend implements IStorageBackend {
+    private prefix;
+    constructor(prefix?: string);
+    private getKey;
+    set(key: string, value: Uint8Array): Promise<void>;
+    get(key: string): Promise<Uint8Array | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+}
+
+/**
+ * ZKIM File Service - Core File Format Implementation
+ * Handles ZKIM file creation, management, and operations
+ *
+ * Service Flow:
+ * 1. Create ZKIM files with three-layer encryption (Platform/User/Content)
+ * 2. Manage file lifecycle and metadata
+ * 3. Provide searchable encryption capabilities
+ * 4. Ensure integrity validation and tamper detection
+ */
+
+declare class ZKIMFileService extends ServiceBase {
+    private readonly defaultConfig;
+    private config;
+    private storageService;
+    private logger;
+    constructor(config?: Partial<ZKIMFileServiceConfig>, logger?: ILogger, storageService?: IStorageBackend);
+    initialize(): Promise<void>;
+    /**
+     * Create a new ZKIM file with three-layer encryption
+     * @param skipCasStorage - If true, skip storing to CAS (prevents circular dependency when persisting to filesystem)
+     */
+    createZkimFile(data: Uint8Array | string, userId: string, platformKey: Uint8Array, userKey: Uint8Array, metadata?: Partial<ZkimFileMetadata>, skipCasStorage?: boolean): Promise<ZkimFileResult>;
+    /**
+     * Decrypt and retrieve a ZKIM file
+     */
+    decryptZkimFile(zkimFile: ZkimFile, userId: string, userKey: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Get a ZKIM file by object ID
+     */
+    getZkimFile(objectId: string): Promise<{
+        success: boolean;
+        data?: ZkimFile;
+        error?: string;
+    }>;
+    /**
+     * Search through encrypted files using searchable encryption
+     */
+    searchFiles(query: string, userId: string, limit?: number): Promise<SearchResult>;
+    /**
+     * Validate file integrity
+     */
+    validateFileIntegrity(zkimFile: ZkimFile): Promise<IntegrityValidationResult>;
+    /**
+     * Update file metadata
+     */
+    updateFileMetadata(zkimFile: ZkimFile, userId: string, updates: Partial<ZkimFileMetadata>): Promise<ZkimFile>;
+    /**
+     * Expand Ed25519 seed (32 bytes) to full private key (64 bytes)
+     * Ed25519 requires 64-byte private keys: seed (32) + public key (32)
+     */
+    private expandEd25519Key;
+    /**
+     * Derive a 64-byte Ed25519 signing key from a 32-byte encryption key
+     * Used as fallback when signing keys are not provided in metadata
+     */
+    private deriveSigningKeyFromEncryptionKey;
+    /**
+     * Decode base64 signing key with error handling
+     */
+    private decodeBase64SigningKey;
+    /**
+     * Validate Ed25519 private key length
+     */
+    private validateEd25519KeyLength;
+    /**
+     * Get or derive Ed25519 signing key from metadata or encryption key
+     * Handles base64 decoding, key expansion, and fallback derivation
+     */
+    private getOrDeriveSigningKey;
+    private generateFileId;
+    private createFileHeader;
+    private processData;
+    /**
+     * Map 3-layer encrypted content to ZKIM chunks
+     * This method chunks the contentEncrypted data (already encrypted by 3-layer encryption)
+     */
+    private mapEncryptedContentToChunks;
+    /**
+     * Generate cryptographically random nonce for chunk storage
+     *
+     * Security Critical: Nonces MUST be random and unique for each chunk.
+     * Deterministic nonce generation breaks XChaCha20-Poly1305 security guarantees.
+     *
+     * Note: Chunks are storage chunks of already-encrypted content data.
+     * These nonces are stored in wire format for metadata purposes.
+     * Even though chunks are not re-encrypted, we use random nonces for security best practices.
+     */
+    private generateChunkNonce;
+    private generateIntegrityHash;
+    private getUserKey;
+    private generatePadding;
+    private createFileMetadata;
+    private generateSignatures;
+    private signData;
+    private verifyUserAccess;
+    private decompressData;
+    private reconstructData;
+    private generateQueryId;
+    /**
+     * Cleanup method required by ServiceBase
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Download a ZKIM file by object ID
+     */
+    downloadFile(objectId: string, userId: string): Promise<{
+        success: boolean;
+        data?: Uint8Array;
+        error?: string;
+    }>;
+}
+
+/**
+ * Encryption Service Interface
+ * Abstract interface for encryption operations used by wire format utilities
+ */
+interface IEncryptionService {
+    /**
+     * Decrypt user layer encryption
+     * Returns file metadata and content key
+     */
+    decryptUserLayer(userEncrypted: Uint8Array, userKey: Uint8Array, nonce: Uint8Array): Promise<{
+        fileId: string;
+        contentKey: Uint8Array;
+        metadata: Record<string, unknown>;
+    }>;
+    /**
+     * Decrypt platform layer encryption (optional)
+     * Returns search metadata
+     */
+    decryptPlatformLayer(platformEncrypted: Uint8Array, platformKey: Uint8Array, nonce: Uint8Array): Promise<Record<string, unknown>>;
+}
+
+/**
+ * ZKIM Encryption Service - Three-Layer Encryption Implementation
+ * Handles encryption/decryption for Platform, User, and Content layers
+ *
+ * Service Flow:
+ * 1. Platform layer encryption (search-only, never decrypts)
+ * 2. User layer encryption (full decryption authority)
+ * 3. Content layer encryption (per-file random keys)
+ * 4. Key management and rotation
+ */
+
+declare class ZkimEncryption extends ServiceBase implements IEncryptionService {
+    private static readonly THREE_LAYER_COUNT;
+    private static readonly COMPRESSION_LEVEL_DEFAULT;
+    private readonly defaultConfig;
+    private config;
+    private keyStore;
+    private sessionKeys;
+    private logger;
+    constructor(config?: Partial<ZkimEncryptionConfig>, logger?: ILogger);
+    initialize(): Promise<void>;
+    /**
+     * Encrypt data with three-layer encryption
+     *
+     * Three-Layer Encryption Architecture:
+     * 1. Platform Layer: Search-only encryption (never decrypts user data)
+     *    - Uses platform key for searchable encryption
+     *    - Enables privacy-preserving search without data access
+     *    - Encrypts searchable metadata and indexes
+     *
+     * 2. User Layer: Full decryption authority
+     *    - Uses user-specific key for complete data access
+     *    - Enables user to decrypt all their content
+     *    - Provides user-level access control
+     *
+     * 3. Content Layer: Per-file random keys
+     *    - Uses unique random key for each file
+     *    - Provides perfect forward secrecy
+     *    - Prevents cross-file key compromise
+     *
+     * Security Properties:
+     * - Authenticated encryption with associated data (AEAD)
+     * - 256-bit security level with XChaCha20-Poly1305
+     * - Nonce reuse protection with unique nonces per layer
+     * - Integrity validation with authentication tags
+     * - Perfect forward secrecy with per-file keys
+     *
+     * @param data - Plaintext data to encrypt
+     * @param platformKey - 32-byte platform encryption key
+     * @param userKey - 32-byte user-specific encryption key
+     * @param fileId - Unique file identifier for key derivation
+     * @param metadata - Optional metadata for encryption context
+     * @returns Object containing encrypted data for each layer, content key, and nonces
+     */
+    encryptData(data: Uint8Array, platformKey: Uint8Array, userKey: Uint8Array, fileId: string, metadata?: Record<string, unknown>): Promise<{
+        platformEncrypted: Uint8Array;
+        userEncrypted: Uint8Array;
+        contentEncrypted: Uint8Array;
+        contentKey: Uint8Array;
+        nonces: Uint8Array[];
+    }>;
+    /**
+     * Decrypt chunk data
+     */
+    decryptChunk(chunk: ZkimFileChunk, userKey: Uint8Array, fileId: string, chunkIndex: number): Promise<Uint8Array>;
+    /**
+     * Decrypt user layer to get content key
+     */
+    decryptUserLayer(userEncrypted: Uint8Array, userKey: Uint8Array, nonce: Uint8Array): Promise<{
+        fileId: string;
+        contentKey: Uint8Array;
+        metadata: Record<string, unknown>;
+    }>;
+    /**
+     * Decrypt platform layer (search-only metadata)
+     */
+    decryptPlatformLayer(platformEncrypted: Uint8Array, platformKey: Uint8Array, nonce: Uint8Array): Promise<Record<string, unknown>>;
+    /**
+     * Simple decrypt method for general use
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, nonce: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Compress data using configured algorithm
+     */
+    compressData(data: Uint8Array, config?: Partial<CompressionConfig>): Promise<CompressionResult>;
+    /**
+     * Decompress data using configured algorithm
+     */
+    decompressData(data: Uint8Array, originalSize: number, config?: Partial<CompressionConfig>): Promise<Uint8Array>;
+    /**
+     * Generate session key for secure communication
+     */
+    generateSessionKey(peerId: string, ephemeralKey: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Rotate keys for enhanced security
+     */
+    rotateKeys(fileId: string): Promise<Uint8Array>;
+    /**
+     * Check for compromised keys
+     */
+    checkKeyCompromise(fileId: string): Promise<boolean>;
+    protected ensureInitialized(): Promise<void>;
+    private initializeKeyManagement;
+    /**
+     * Extract searchable text from content data
+     * Tokenizes content into searchable words for privacy-preserving search
+     */
+    private extractSearchableText;
+    /**
+     * Generate cryptographically secure random nonces for encryption
+     *
+     * Security Critical: Nonces MUST be random and unique for each encryption operation.
+     * This method uses sodium.randombytes_buf() for cryptographically random nonce generation.
+     * Deterministic nonce generation (e.g., hash-based) breaks XChaCha20-Poly1305 security guarantees.
+     *
+     * Nonce Requirements:
+     * - Must be unique for each encryption operation
+     * - Must be cryptographically random (not deterministic)
+     * - Must be 24 bytes for XChaCha20-Poly1305
+     * - Never reuse nonces with the same key
+     *
+     * Implementation: Uses sodium.randombytes_buf() for true cryptographic randomness.
+     * The fileId parameter is used ONLY for logging/tracking, NOT for nonce generation.
+     *
+     * @param fileId - File identifier (used for logging only, NOT for nonce generation)
+     * @param count - Number of nonces to generate (typically 3 for three-layer encryption)
+     * @returns Array of cryptographically random nonces generated via sodium.randombytes_buf()
+     */
+    private generateNonces;
+    /**
+     * Core encryption method using XChaCha20-Poly1305 AEAD
+     *
+     * Cryptographic Implementation:
+     * - Uses XChaCha20-Poly1305 for authenticated encryption with associated data
+     * - Provides 256-bit security level with 24-byte nonce and 32-byte key
+     * - Implements AEAD (Authenticated Encryption with Associated Data)
+     * - Returns separate encrypted data and authentication tag
+     *
+     * Security Properties:
+     * - Authenticated encryption prevents tampering
+     * - Nonce reuse protection (each encryption uses unique nonce)
+     * - Integrity validation through authentication tag
+     * - Constant-time operations to prevent timing attacks
+     * - Forward secrecy with unique keys per operation
+     *
+     * Performance Characteristics:
+     * - Fast encryption/decryption for large data
+     * - Minimal memory overhead
+     * - Optimized for streaming operations
+     * - Hardware acceleration support where available
+     *
+     * @param data - Plaintext data to encrypt
+     * @param key - 32-byte encryption key (must be cryptographically random)
+     * @param nonce - 24-byte nonce (must be unique for each encryption)
+     * @param layer - Layer identifier for logging (platform/user/content)
+     * @returns EncryptionResult with encrypted data, tag, and metadata
+     */
+    private encryptLayer;
+    private decryptLayer;
+    /**
+     * Create no compression result for disabled compression
+     */
+    private createNoCompressionResult;
+    /**
+     * Compress data using Brotli algorithm
+     * Uses browser's native CompressionStream API (backendless-compatible)
+     */
+    private compressBrotli;
+    /**
+     * Decompress data using Brotli algorithm
+     * Uses browser's native DecompressionStream API (backendless-compatible)
+     */
+    private decompressBrotli;
+    /**
+     * Compress data using GZIP algorithm
+     * Delegates to compression-utils for mockability in tests
+     */
+    private compressGZIP;
+    /**
+     * Decompress data using GZIP algorithm
+     * Delegates to compression-utils for mockability in tests
+     */
+    private decompressGZIP;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * ZKIM Integrity Service - File Validation and Tamper Detection
+ * Handles integrity validation using BLAKE3 + Ed25519 signatures
+ *
+ * Service Flow:
+ * 1. Validate file header integrity
+ * 2. Verify chunk integrity with BLAKE3 hashes
+ * 3. Validate signatures (Platform, User, Content)
+ * 4. Detect tampering and provide detailed validation results
+ */
+
+declare class ZkimIntegrity extends ServiceBase {
+    private readonly defaultConfig;
+    private config;
+    private isInitialized;
+    private validationCache;
+    private auditLog;
+    private logger;
+    constructor(config?: Partial<ZkimIntegrityConfig>, logger?: ILogger);
+    initialize(): Promise<void>;
+    /**
+     * Validate complete ZKIM file integrity
+     *
+     * @param zkimFile - The ZKIM file to validate
+     * @param platformKey - Optional platform encryption key (required for signature verification)
+     * @param userKey - Optional user encryption key (required for signature verification)
+     */
+    validateFile(zkimFile: ZkimFile, platformKey?: Uint8Array, userKey?: Uint8Array): Promise<IntegrityValidationResult>;
+    /**
+     * Validate specific file header
+     */
+    validateHeader(header: ZkimFileHeader): Promise<boolean>;
+    /**
+     * Validate file chunks integrity
+     */
+    validateChunks(chunks: ZkimFileChunk[], header: ZkimFileHeader): Promise<boolean>;
+    /**
+     * Validate file signatures
+     *
+     * @param zkimFile - The ZKIM file to validate
+     * @param platformKey - Optional platform encryption key (used to derive public key for verification)
+     * @param userKey - Optional user encryption key (used to derive public key for verification)
+     * @returns true if signatures are valid or if keys are not provided (signature verification skipped)
+     */
+    validateSignatures(zkimFile: ZkimFile, platformKey?: Uint8Array, userKey?: Uint8Array): Promise<boolean>;
+    /**
+     * Validate file metadata
+     */
+    validateMetadata(metadata: ZkimFileMetadata): Promise<boolean>;
+    /**
+     * Detect tampering in file
+     */
+    detectTampering(zkimFile: ZkimFile): Promise<{
+        isTampered: boolean;
+        tamperType: string[];
+        evidence: string[];
+    }>;
+    private initializeValidationSystems;
+    private isCacheValid;
+    private calculateValidationScore;
+    private determineValidationLevel;
+    private isValidAlgorithmId;
+    private verifySignature;
+    private logAuditEntry;
+    /**
+     * Get audit log entries
+     */
+    getAuditLog(limit?: number): Array<{
+        timestamp: number;
+        fileId: string;
+        operation: string;
+        result: boolean;
+        details: string;
+    }>;
+    /**
+     * Clear validation cache
+     */
+    clearCache(): void;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * ZKIM Searchable Encryption Service - OPRF-based Privacy-Preserving Search
+ * Implements searchable encryption using OPRF on ristretto255 curve
+ *
+ * Service Flow:
+ * 1. Index files with OPRF-based searchable encryption
+ * 2. Process search queries with privacy enhancement
+ * 3. Return results with rate limiting and padding
+ * 4. Manage trapdoor rotation and revocation
+ */
+
+declare class SearchableEncryption extends ServiceBase {
+    private readonly defaultConfig;
+    static search(query: SearchQuery, limit?: number): Promise<SearchResult>;
+    private config;
+    private isInitialized;
+    private fileIndex;
+    private trapdoors;
+    private queryHistory;
+    private currentEpoch;
+    private epochStartTime;
+    private oprfSecretKey;
+    private zkimFileService;
+    private saveIndexTimer;
+    private epochTimer;
+    private logger;
+    private createIndexedFile;
+    private createQueryHistoryEntry;
+    constructor(config?: Partial<SearchableEncryptionConfig>, logger?: ILogger);
+    initialize(): Promise<void>;
+    /**
+     * Index a file for searchable encryption
+     */
+    indexFile(zkimFile: ZkimFile, userId: string): Promise<void>;
+    /**
+     * Search through encrypted files
+     */
+    search(query: SearchQuery, limit?: number): Promise<SearchResult>;
+    /**
+     * Update file index when metadata changes
+     */
+    updateFileIndex(zkimFile: ZkimFile, userId: string): Promise<void>;
+    /**
+     * Remove file from search index
+     */
+    removeFileFromIndex(fileId: string): Promise<void>;
+    /**
+     * Rotate trapdoors for enhanced privacy
+     */
+    rotateTrapdoors(): Promise<void>;
+    /**
+     * Generate OPRF token for a word (public API for indexing)
+     * Used by message indexing service to generate privacy-preserving tokens
+     */
+    generateOPRFToken(word: string): Promise<string>;
+    /**
+     * Get search statistics
+     */
+    getSearchStats(): Promise<{
+        totalIndexedFiles: number;
+        totalTrapdoors: number;
+        activeTrapdoors: number;
+        queriesThisEpoch: number;
+        averageQueryTime: number;
+        privacyLevels: Record<string, number>;
+    }>;
+    protected ensureInitialized(): Promise<void>;
+    private initializeOPRF;
+    private startEpochManagement;
+    private advanceEpoch;
+    private generateObjectId;
+    private generateSearchTokens;
+    /**
+     * Generate OPRF token using Ristretto255 curve
+     * OPRF evaluation: F(k, x) = H(x) * k
+     * 1. Hash input to uniform distribution (BLAKE3)
+     * 2. Map hash to Ristretto255 point (hash as scalar × base point)
+     * 3. Multiply by secret key scalar
+     * 4. Return base64-encoded result
+     */
+    private generateToken;
+    /**
+     * Convert bytes to scalar for Ristretto255
+     * Clamps bytes to valid scalar range (mod curve order)
+     */
+    private bytesToScalar;
+    /**
+     * Generate OPRF trapdoor for search query
+     * Same OPRF evaluation as generateToken, returns raw bytes instead of base64
+     */
+    private generateOPRFTrapdoor;
+    private determineAccessLevel;
+    private checkRateLimit;
+    private generateTrapdoor;
+    private generateTrapdoorId;
+    private performOPRFSearch;
+    /**
+     * Match OPRF trapdoor against indexed trapdoors using constant-time comparison
+     * Prevents timing attacks by using sodium.memcmp for all comparisons
+     */
+    private matchesOPRFQuery;
+    private calculateRelevance;
+    private applyPrivacyEnhancement;
+    private addResultPadding;
+    private selectTargetBucket;
+    private generatePaddingResults;
+    private generateRandomFloat;
+    private shuffleArray;
+    private determinePrivacyLevel;
+    private rotateTrapdoor;
+    private cleanupExpiredTrapdoors;
+    private logQueryHistory;
+    private calculatePrivacyLevels;
+    cleanup(): Promise<void>;
+    /**
+     * Load file index from persistence (browser: localStorage, Node.js: in-memory only)
+     */
+    private loadFileIndex;
+    /**
+     * Save file index to persistence (browser: localStorage as ZKIM file, Node.js: in-memory only)
+     */
+    private saveFileIndex;
+    private startAutoSave;
+}
+
+/**
+ * Error Types and Classes for @zkim/file-format
+ * Lightweight error handling without platform dependencies
+ */
+interface ErrorContext {
+    message: string;
+    type: string;
+    source: string;
+    operation: string;
+    timestamp: number;
+    severity: "low" | "medium" | "high" | "critical";
+    metadata?: Record<string, unknown>;
+    service?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: unknown;
+}
+interface ServiceResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    errorCode?: string;
+    context?: ErrorContext;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base Service Error Class
+ */
+declare class ServiceError extends Error {
+    readonly code?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * ZKIM File Format Specific Errors
+ */
+declare class ZKIMFileError extends ServiceError {
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+declare class ZKIMEncryptionError extends ServiceError {
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+declare class ZKIMIntegrityError extends ServiceError {
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+declare class ZKIMStorageError extends ServiceError {
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+
+/**
+ * ZKIM Trapdoor Rotator Service - Privacy Enhancement and Key Rotation
+ * Handles trapdoor rotation, revocation, and usage tracking for enhanced privacy
+ *
+ * Service Flow:
+ * 1. Manage trapdoor lifecycle and rotation schedules
+ * 2. Implement automatic revocation and expiration
+ * 3. Track usage patterns and detect anomalies
+ * 4. Provide privacy metrics and audit logging
+ */
+
+interface TrapdoorRotatorServiceConfig extends TrapdoorRotationConfig {
+    enableAnomalyDetection: boolean;
+    enableAuditLogging: boolean;
+    rotationThreshold: number;
+    revocationThreshold: number;
+}
+declare class TrapdoorRotator extends ServiceBase {
+    private readonly defaultConfig;
+    private config;
+    private trapdoors;
+    private rotationEvents;
+    private usagePatterns;
+    private rotationTimer?;
+    private anomalyDetector;
+    private logger;
+    constructor(config?: Partial<TrapdoorRotatorServiceConfig>, logger?: ILogger);
+    initialize(): Promise<void>;
+    /**
+     * Create a new trapdoor
+     */
+    createTrapdoor(userId: string, query: string, maxUsage?: number): Promise<ServiceResult<Trapdoor>>;
+    /**
+     * Rotate an existing trapdoor
+     */
+    rotateTrapdoor(trapdoorId: string): Promise<ServiceResult<Trapdoor>>;
+    /**
+     * Revoke a trapdoor
+     */
+    revokeTrapdoor(trapdoorId: string, reason?: string): Promise<void>;
+    /**
+     * Update trapdoor usage
+     */
+    updateTrapdoorUsage(trapdoorId: string): Promise<ServiceResult<{
+        shouldRotate: boolean;
+        shouldRevoke: boolean;
+        anomalyDetected: boolean;
+    }>>;
+    /**
+     * Get trapdoor information
+     */
+    getTrapdoorInfo(trapdoorId: string): ServiceResult<Trapdoor | null>;
+    /**
+     * Get user's active trapdoors
+     */
+    getUserTrapdoors(userId: string): ServiceResult<Trapdoor[]>;
+    /**
+     * Get rotation events
+     */
+    getRotationEvents(limit?: number): ServiceResult<TrapdoorRotationEvent[]>;
+    /**
+     * Get usage statistics
+     */
+    getUsageStats(): ServiceResult<{
+        totalTrapdoors: number;
+        activeTrapdoors: number;
+        revokedTrapdoors: number;
+        averageUsagePerTrapdoor: number;
+        totalRotations: number;
+        totalRevocations: number;
+        anomalyCount: number;
+    }>;
+    private initializeRotationSystem;
+    private startRotationTimer;
+    private performScheduledRotations;
+    private generateTrapdoorId;
+    private getActiveTrapdoorCount;
+    private updateUsagePattern;
+    private logRotationEvent;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * ZKIM Query Batcher Service - Query Optimization and Batching
+ * Handles query batching, load balancing, and optimization for searchable encryption
+ *
+ * Service Flow:
+ * 1. Batch multiple queries for efficient processing
+ * 2. Implement load balancing across search nodes
+ * 3. Optimize query execution and caching
+ * 4. Provide query analytics and performance metrics
+ */
+
+interface QueryBatcherServiceConfig extends QueryBatchConfig {
+    maxResultsPerQuery: number;
+    enableQueryCaching: boolean;
+    cacheSize: number;
+    cacheTTL: number;
+    enablePerformanceMetrics: boolean;
+}
+declare class QueryBatcher extends ServiceBase {
+    private readonly defaultConfig;
+    private config;
+    private isInitialized;
+    private pendingQueries;
+    private activeBatches;
+    private queryCache;
+    private batchTimer;
+    private batchCleanupTimers;
+    private logger;
+    private performanceMetrics;
+    private createPerformanceMetrics;
+    private batchCounter;
+    constructor(config?: Partial<QueryBatcherServiceConfig>, logger?: ILogger);
+    initialize(): Promise<void>;
+    /**
+     * Add query to batch processing
+     */
+    addQuery(query: SearchQuery): Promise<string>;
+    /**
+     * Process queries in batches
+     */
+    processBatch(): Promise<void>;
+    /**
+     * Get batch status and results
+     */
+    getBatchStatus(batchId: string): Promise<QueryBatch | null>;
+    /**
+     * Get query results from batch
+     */
+    getQueryResults(queryId: string): Promise<SearchResult | null>;
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics(): Promise<{
+        totalBatches: number;
+        totalQueries: number;
+        averageBatchTime: number;
+        averageQueryTime: number;
+        cacheHitRate: number;
+        loadBalancingEfficiency: number;
+        pendingQueries: number;
+        activeBatches: number;
+        cacheSize: number;
+    }>;
+    /**
+     * Clear cache and reset metrics
+     */
+    reset(): Promise<void>;
+    protected ensureInitialized(): Promise<void>;
+    private initializeBatchingSystem;
+    private startBatchProcessing;
+    private shouldStartNewBatch;
+    private generateBatchId;
+    private processBatchAsync;
+    private processQuery;
+    private getCachedResult;
+    /**
+     * Update query performance metrics
+     */
+    private updateQueryMetrics;
+    /**
+     * Calculate performance score based on processing time
+     */
+    private calculatePerformanceScore;
+    private cacheResult;
+    private generateCacheKey;
+    private isCacheValid;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * ZKIM Error Recovery Service
+ *
+ * Comprehensive error recovery strategies for ZKIM operations
+ * including corruption recovery, validation, and repair mechanisms.
+ *
+ * @fileoverview Error recovery and repair strategies
+ */
+
+/**
+ * Recovery result interface
+ */
+interface ZkimRecoveryResult {
+    success: boolean;
+    recoveredData?: Uint8Array;
+    repairActions: string[];
+    warnings: string[];
+    errors: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Corruption detection result
+ */
+interface ZkimCorruptionDetection {
+    isCorrupted: boolean;
+    corruptionType: "header" | "chunk" | "signature" | "metadata" | "unknown";
+    severity: "low" | "medium" | "high" | "critical";
+    affectedChunks: number[];
+    description: string;
+}
+/**
+ * Repair strategy
+ */
+interface ZkimRepairStrategy {
+    strategy: "skip" | "reconstruct" | "recover" | "fail";
+    confidence: number;
+    description: string;
+    actions: string[];
+}
+declare class ZkimErrorRecovery extends ServiceBase {
+    private readonly context;
+    private recoveryAttempts;
+    private logger;
+    constructor(logger?: ILogger);
+    /**
+     * Initialize error recovery service
+     */
+    initialize(): Promise<void>;
+    /**
+     * Cleanup error recovery service
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Recover from file corruption
+     */
+    recoverFromCorruption(corruptedData: Uint8Array, fileId: string, options?: {
+        maxRepairAttempts?: number;
+        enableReconstruction?: boolean;
+        strictValidation?: boolean;
+    }): Promise<ZkimRecoveryResult>;
+    /**
+     * Validate and repair file integrity
+     */
+    validateAndRepair(data: Uint8Array, fileId: string, options?: {
+        enableRepair?: boolean;
+        strictMode?: boolean;
+    }): Promise<ZkimRecoveryResult>;
+    /**
+     * Detect corruption in file data
+     */
+    private detectCorruption;
+    /**
+     * Determine repair strategy based on corruption type
+     */
+    private determineRepairStrategy;
+    /**
+     * Execute recovery based on strategy
+     */
+    private executeRecovery;
+    /**
+     * Execute skip strategy
+     */
+    private executeSkipStrategy;
+    /**
+     * Execute reconstruct strategy
+     */
+    private executeReconstructStrategy;
+    /**
+     * Execute recover strategy
+     */
+    private executeRecoverStrategy;
+    /**
+     * Validate file structure
+     */
+    private validateFileStructure;
+    /**
+     * Repair file structure
+     */
+    private repairFileStructure;
+}
+
+/**
+ * ZKIM Performance Monitor
+ *
+ * Comprehensive performance monitoring and metrics collection for ZKIM operations
+ * including encryption, decryption, serialization, and parsing performance.
+ *
+ * @fileoverview Performance monitoring and metrics collection
+ */
+
+/**
+ * Performance metrics interface
+ */
+interface ZkimPerformanceMetrics {
+    operation: string;
+    duration: number;
+    dataSize: number;
+    throughput: number;
+    memoryUsage: number;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Performance statistics
+ */
+interface ZkimPerformanceStats {
+    totalOperations: number;
+    successfulOperations: number;
+    failedOperations: number;
+    averageDuration: number;
+    averageThroughput: number;
+    averageMemoryUsage: number;
+    successRate: number;
+    p95Duration: number;
+    p99Duration: number;
+    maxDuration: number;
+    minDuration: number;
+}
+/**
+ * Performance thresholds
+ */
+interface ZkimPerformanceThresholds {
+    maxDuration: number;
+    minThroughput: number;
+    maxMemoryUsage: number;
+    minSuccessRate: number;
+}
+/**
+ * ZKIM Performance Monitor
+ */
+declare class ZkimPerformanceMonitor extends ServiceBase {
+    private readonly context;
+    private metrics;
+    private thresholds;
+    private monitoringInterval;
+    private logger;
+    constructor(thresholds?: Partial<ZkimPerformanceThresholds>, logger?: ILogger);
+    /**
+     * Initialize performance monitoring
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get memory usage from browser performance API
+     * Falls back to 0 if performance.memory is not available
+     */
+    private getMemoryUsage;
+    /**
+     * Record performance metrics for an operation
+     */
+    recordOperation(operation: string, duration: number, dataSize: number, success: boolean, error?: string): void;
+    /**
+     * Get performance statistics
+     */
+    getPerformanceStats(): ZkimPerformanceStats;
+    /**
+     * Get performance metrics for a specific operation
+     */
+    getOperationMetrics(operation: string): ZkimPerformanceMetrics[];
+    /**
+     * Get recent performance metrics
+     */
+    getRecentMetrics(limit?: number): ZkimPerformanceMetrics[];
+    /**
+     * Clear performance metrics
+     */
+    clearMetrics(): void;
+    /**
+     * Update performance thresholds
+     */
+    updateThresholds(thresholds: Partial<ZkimPerformanceThresholds>): void;
+    /**
+     * Check if a metric value violates thresholds
+     */
+    private checkMetricThreshold;
+    /**
+     * Generate alert message for threshold violation
+     */
+    private generateAlertMessage;
+    /**
+     * Get performance alerts based on statistics
+     */
+    getPerformanceAlerts(): string[];
+    /**
+     * Start performance monitoring
+     */
+    private startMonitoring;
+    /**
+     * Perform health check
+     */
+    private performHealthCheck;
+    /**
+     * Check performance thresholds for a single metric
+     */
+    private checkThresholds;
+    /**
+     * Stop performance monitoring
+     */
+    stopMonitoring(): void;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * ZKIM File Wire Format Utilities
+ *
+ * Contains all wire format I/O operations for ZKIM files.
+ * Wire Format: MAGIC + VERSION + FLAGS + EH_PLATFORM + EH_USER + CHUNKS + MERKLE_ROOT + SIG
+ *
+ * This module exports pure functions (not class methods) for wire format operations.
+ */
+
+/**
+ * Write little-endian u16
+ */
+declare function writeU16(value: number): Uint8Array;
+/**
+ * Read little-endian u16
+ */
+declare function readU16(buffer: Uint8Array, offset: number): number;
+/**
+ * Format EH header: nonce24 || tag16 (40 bytes fixed)
+ * Ciphertext is stored in chunks, not in EH header
+ */
+declare function formatEhHeader(nonce: Uint8Array, data: {
+    ciphertext: Uint8Array;
+    tag: Uint8Array;
+} | Uint8Array): Uint8Array;
+/**
+ * Calculate Merkle root from chunk integrity hashes using BLAKE3
+ */
+declare function calculateMerkleRoot(chunks: ZkimFileChunk[]): Uint8Array;
+/**
+ * Generate file signature: Ed25519(BLAKE3("zkim/root" || root || manifestHash || algSuiteId || version))
+ * Derives 64-byte signing key from 32-byte userKey using BLAKE3
+ */
+declare function generateFileSignature(merkleRoot: Uint8Array, manifestHash: Uint8Array, algSuiteId: number, version: number, userKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Calculate manifest hash (BLAKE3 of EH_USER header)
+ */
+declare function calculateManifestHash(ehUser: Uint8Array): Uint8Array;
+/**
+ * Write ZKIM file in wire format according to spec
+ * Wire Format: MAGIC + VERSION + FLAGS + EH_PLATFORM + EH_USER + CHUNKS + MERKLE_ROOT + SIG
+ */
+declare function writeWireFormat(header: ZkimFileHeader, ehPlatform: Uint8Array, ehUser: Uint8Array, chunks: ZkimFileChunk[], merkleRoot: Uint8Array, signature: Uint8Array, logger?: ILogger): Uint8Array;
+/**
+ * Parse ZKIM file from bytes (wire format only)
+ */
+declare function parseZkimFile(data: Uint8Array, userKey: Uint8Array, platformKey: Uint8Array, encryptionService: IEncryptionService, logger?: ILogger): Promise<ZkimFile>;
+
+/**
+ * Error Handling Utilities for @zkim/file-format
+ * Lightweight error handling without platform dependencies
+ */
+
+/**
+ * Error handling utilities for services
+ */
+declare class ErrorUtils {
+    private static logger;
+    /**
+     * Set custom logger instance
+     */
+    static setLogger(logger: ILogger): void;
+    /**
+     * Create error context for consistent error handling
+     */
+    static createContext(service: string, operation: string, additionalContext?: Record<string, unknown>): ErrorContext;
+    /**
+     * Extract error message from unknown error type
+     */
+    static getErrorMessage(error: unknown): string;
+    /**
+     * Create a successful service result
+     */
+    static createSuccessResult<T>(data: T): ServiceResult<T>;
+    /**
+     * Create a failed service result
+     */
+    static createErrorResult<T>(error: string | Error): ServiceResult<T>;
+    /**
+     * Wrap async operations with error handling
+     */
+    static withErrorHandling<T>(operation: () => Promise<T>, context: ErrorContext, fallback?: T): Promise<ServiceResult<T>>;
+    /**
+     * Handle errors with context and logging
+     */
+    static handleError(error: unknown, context: ErrorContext): void;
+}
+
+/**
+ * Environment-Agnostic Crypto Utilities for @zkim/file-format
+ * Provides crypto operations that work in both browser and Node.js environments
+ */
+/**
+ * Generate random bytes using libsodium
+ */
+declare function generateRandomBytes(length: number): Promise<Uint8Array>;
+/**
+ * Generate random hex string
+ */
+declare function generateRandomHex(length: number): Promise<string>;
+/**
+ * Hash data using BLAKE3
+ */
+declare function hashData(data: Uint8Array, outputLength?: number): Uint8Array;
+/**
+ * Hash data to hex string
+ */
+declare function hashDataToHex(data: Uint8Array, outputLength?: number): string;
+/**
+ * Generate key pair using X25519 (for encryption)
+ */
+declare function generateKeyPair(): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}>;
+/**
+ * Generate signing key pair using Ed25519
+ */
+declare function generateSigningKeyPair(): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}>;
+/**
+ * Encrypt data using XChaCha20-Poly1305
+ */
+declare function encryptData(data: Uint8Array, key: Uint8Array, nonce?: Uint8Array): Promise<{
+    ciphertext: Uint8Array;
+    nonce: Uint8Array;
+}>;
+/**
+ * Decrypt data using XChaCha20-Poly1305
+ */
+declare function decryptData(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Promise<Uint8Array>;
+/**
+ * Convert Uint8Array to base64 string
+ */
+declare function toBase64(data: Uint8Array): Promise<string>;
+/**
+ * Convert base64 string to Uint8Array
+ */
+declare function fromBase64(data: string): Promise<Uint8Array>;
+/**
+ * Convert Uint8Array to hex string
+ */
+declare function toHex(data: Uint8Array): Promise<string>;
+/**
+ * Convert hex string to Uint8Array
+ */
+declare function fromHex(data: string): Promise<Uint8Array>;
+
+/**
+ * ZKIM Compression Utilities
+ *
+ * Abstraction layer for compression operations
+ * Uses pako for browser compatibility, with Node.js zlib fallback for Node.js environments
+ *
+ * Note: Node.js zlib is only used as a fallback in Node.js runtime environments (e.g., Jest tests).
+ * In browser environments, pako is used exclusively. The dynamic import of zlib will fail
+ * gracefully in browsers and fall back to pako.
+ */
+
+/**
+ * Compress data using GZIP algorithm
+ * Uses pako for browser compatibility, with Node.js zlib fallback
+ */
+declare function compressGzip(data: Uint8Array, level?: number, logger?: ILogger): Promise<Uint8Array>;
+/**
+ * Decompress data using GZIP algorithm
+ * Uses pako for browser compatibility, with Node.js zlib fallback
+ */
+declare function decompressGzip(data: Uint8Array, originalSize?: number, logger?: ILogger): Promise<Uint8Array>;
+
+/**
+ * Constant-Time Security Utilities
+ *
+ * Provides constant-time implementations of common operations to prevent
+ * timing attacks in cryptographic applications.
+ *
+ * Security Features:
+ * - Constant-time string comparison
+ * - Constant-time array operations
+ * - Timing attack prevention
+ * - Secure random delays
+ * - Memory-safe operations
+ */
+declare class ConstantTimeSecurity {
+    private static readonly MIN_OPERATION_TIME;
+    private static readonly MAX_OPERATION_TIME;
+    private static readonly RANDOM_DELAY_FACTOR;
+    /**
+     * Constant-time string comparison
+     *
+     * Prevents timing attacks by ensuring comparison always takes the same time
+     * regardless of where the strings differ.
+     */
+    static constantTimeStringCompare(a: string, b: string): boolean;
+    /**
+     * Constant-time byte array comparison
+     *
+     * Prevents timing attacks on binary data comparisons.
+     */
+    static constantTimeByteCompare(a: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * Constant-time array search
+     *
+     * Prevents timing attacks on array search operations by always
+     * checking all elements regardless of early matches.
+     */
+    static constantTimeArrayIncludes<T>(array: T[], target: T, compareFn?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Constant-time string array search
+     *
+     * Specialized version for string arrays using constant-time comparison.
+     */
+    static constantTimeStringArrayIncludes(array: string[], target: string): boolean;
+    /**
+     * Constant-time length validation
+     *
+     * Validates array/string length without revealing the actual length
+     * through timing differences.
+     */
+    static constantTimeLengthCheck(data: string | Uint8Array, expectedLength: number): boolean;
+    /**
+     * Secure random delay
+     *
+     * Adds a random delay to prevent timing analysis attacks.
+     */
+    static addSecureDelay(baseTime?: number): Promise<void>;
+    /**
+     * Timing attack prevention wrapper
+     *
+     * Wraps any operation with timing attack prevention measures.
+     */
+    static withTimingProtection<T>(operation: () => T | Promise<T>, minTime?: number, maxTime?: number): Promise<T>;
+    /**
+     * Constant-time magic number validation
+     *
+     * Validates magic numbers without timing leaks.
+     */
+    static validateMagicNumber(actual: string, expected?: string): boolean;
+    /**
+     * Constant-time version validation
+     *
+     * Validates version numbers without timing leaks.
+     */
+    static validateVersion(actual: number, expected: number, minVersion?: number, maxVersion?: number): boolean;
+    /**
+     * Constant-time size validation
+     *
+     * Validates data sizes without timing leaks.
+     */
+    static validateSize(actualSize: number, expectedSize: number, tolerance?: number): boolean;
+    /**
+     * Secure comparison with logging
+     *
+     * Performs constant-time comparison with security logging.
+     */
+    static secureCompare<T>(actual: T, expected: T, context: string, compareFn?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Memory-safe string operations
+     *
+     * Performs string operations without memory leaks.
+     */
+    static memorySafeStringOperation(operation: (str: string) => string): (str: string) => string;
+    /**
+     * Secure array operations
+     *
+     * Performs array operations with timing attack prevention.
+     */
+    static secureArrayOperation<T>(array: T[], operation: (arr: T[]) => boolean): boolean;
+    /**
+     * Timing attack detection
+     *
+     * Detects potential timing attacks by monitoring operation times.
+     */
+    static detectTimingAttack(operationTimes: number[], threshold?: number): boolean;
+}
+
+/**
+ * ZKIM File Format Constants
+ * Single source of truth for all file format-related constants
+ */
+/**
+ * ZKIM Encryption Constants
+ */
+declare const ZKIM_ENCRYPTION_CONSTANTS: {
+    readonly DEFAULT_ALGORITHM: "xchacha20-poly1305";
+    readonly KEY_SIZE: 32;
+    readonly NONCE_SIZE: 24;
+    readonly TAG_SIZE: 16;
+    readonly SALT_LENGTH: 32;
+    readonly ITERATIONS: 100000;
+    readonly KEY_ROTATION_INTERVAL: number;
+    readonly MAX_KEY_AGE: number;
+    readonly ED25519_PRIVATE_KEY_SIZE: 64;
+    readonly ED25519_PUBLIC_KEY_SIZE: 32;
+    readonly EH_HEADER_SIZE: 40;
+    readonly MAGIC_BYTES_SIZE: 4;
+    readonly VERSION_BYTES_SIZE: 2;
+    readonly FLAGS_BYTES_SIZE: 2;
+    readonly MERKLE_ROOT_SIZE: 32;
+    readonly SIGNATURE_SIZE: 64;
+    readonly WORKER_BATCH_SIZE: 25;
+    readonly WORKER_BATCH_INTERVAL_MS: 25;
+};
+/**
+ * ZKIM File Service Constants
+ */
+declare const ZKIM_FILE_SERVICE_CONSTANTS: {
+    readonly COMPRESSION_TYPE_MAP: {
+        readonly brotli: 1;
+        readonly gzip: 2;
+    };
+    readonly COMPRESSION_TYPE_REVERSE_MAP: {
+        readonly 1: "brotli";
+        readonly 2: "gzip";
+    };
+    readonly DEFAULT_MAGIC: "ZKIM";
+    readonly DEFAULT_VERSION: 1;
+    readonly NONCE_PREFIX: "zkim/nonce";
+    readonly KEY_PREFIX: "zkim/key";
+    readonly USER_KEY_PREFIX: "zkim/userkey";
+};
+/**
+ * File Processing Constants
+ */
+declare const FILE_PROCESSING_CONSTANTS: {
+    readonly DEFAULT_CHUNK_SIZE: number;
+    readonly MAX_CHUNK_SIZE: number;
+    readonly MIN_CHUNK_SIZE: 1024;
+    readonly DEFAULT_MAX_FILE_SIZE: number;
+    readonly COMPRESSION_LEVEL: 6;
+    readonly DEFAULT_COMPRESSION_ALGORITHM: "gzip";
+    readonly MAX_METADATA_SIZE: number;
+};
+/**
+ * Service Lifecycle Constants
+ */
+declare const ZKIM_SERVICE_LIFECYCLE_CONSTANTS: {
+    readonly INITIALIZATION_TIMEOUT: 30000;
+    readonly CLEANUP_TIMEOUT: 10000;
+    readonly MAX_INITIALIZATION_RETRIES: 3;
+    readonly HEALTH_CHECK_INTERVAL: 60000;
+};
+/**
+ * ZKIM Binary Format Constants
+ * Magic bytes represent ASCII "ZKIM": Z=0x5a, K=0x4b, I=0x49, M=0x4d
+ */
+declare const ZKIM_BINARY_CONSTANTS: {
+    readonly MAGIC_BYTE_Z: 90;
+    readonly MAGIC_BYTE_K: 75;
+    readonly MAGIC_BYTE_I: 73;
+    readonly MAGIC_BYTE_M: 77;
+    readonly MAGIC_BYTES: Uint8Array<ArrayBuffer>;
+    readonly VERSION: 1;
+    readonly HEADER_SIZE: 16;
+    readonly MAX_FILE_SIZE: number;
+    readonly CHUNK_SIZE: number;
+};
+
+/**
+ * @zkim/file-format - ZKIM Secure File Format
+ *
+ * A secure, encrypted file format with three-layer encryption,
+ * integrity validation, and privacy-preserving search capabilities.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "1.0.0";
+
+export { AnomalyDetector, type CachedResult, ConsoleLogger, ConstantTimeSecurity, type ErrorContext, ErrorUtils, FILE_PROCESSING_CONSTANTS, type IEncryptionService, type ILogger, type IStorageBackend, InMemoryStorage, type IndexedFile, type IntegrityValidationResult, LocalStorageBackend, type MetadataWithAccessLevel, type QueryBatch, type QueryBatchConfig, QueryBatcher, type QueryBatcherPerformanceMetrics, type QueryHistoryEntry, type SearchQuery, type SearchResult, SearchableEncryption, type SearchableEncryptionConfig, ServiceBase, ServiceError, type ServiceResult, SingletonBase, type Trapdoor, type TrapdoorRotationConfig, type TrapdoorRotationEvent, TrapdoorRotator, type UsagePattern, VERSION, ZKIMEncryptionError, ZKIMFileError, ZKIMFileService, type ZKIMFileServiceConfig, ZKIMIntegrityError, ZKIMStorageError, ZKIM_BINARY_CONSTANTS, ZKIM_ENCRYPTION_CONSTANTS, ZKIM_FILE_SERVICE_CONSTANTS, ZKIM_SERVICE_LIFECYCLE_CONSTANTS, type ZkimCorruptionDetection, ZkimEncryption, type ZkimEncryptionConfig, ZkimErrorRecovery, type ZkimFile, type ZkimFileChunk, type ZkimFileHeader, type ZkimFileMetadata, type ZkimFileResult, type ZkimFileSearchResult, ZkimIntegrity, type ZkimIntegrityConfig, type ZkimPerformanceMetrics, ZkimPerformanceMonitor, type ZkimPerformanceStats, type ZkimPerformanceThresholds, type ZkimRecoveryResult, type ZkimRepairStrategy, calculateManifestHash, calculateMerkleRoot, compressGzip, decompressGzip, decryptData, defaultLogger, encryptData, formatEhHeader, fromBase64, fromHex, generateFileSignature, generateKeyPair, generateRandomBytes, generateRandomHex, generateSigningKeyPair, hashData, hashDataToHex, parseZkimFile, readU16, toBase64, toHex, writeU16, writeWireFormat };