neozipkit 0.2.1 → 0.3.0

package/src/core/components/HashCalculator.ts

@@ -0,0 +1,384 @@
+// ======================================
+//  HashCalculator.ts - Unified Hash Component
+//  Combines StreamHashCalculator, HashAccumulator, and MerkleTree functionality
+// ======================================
+
+import * as crypto from 'crypto';
+import { crc32update } from '../encryption/ZipCrypto';
+
+/**
+ * Configuration options for Merkle tree construction
+ */
+interface MerkleTreeOptions {
+  hashLeaves: boolean;      // Whether to hash the leaf nodes before adding to tree
+  sortLeaves: boolean;      // Whether to sort leaf nodes for consistent trees
+  sortPairs: boolean;       // Whether to sort each pair before hashing
+  duplicateOdd: boolean;    // Whether to duplicate last leaf when odd number of leaves
+}
+
+/**
+ * Unified hash calculator supporting:
+ * - Incremental CRC-32 and SHA-256 calculation from raw data chunks
+ * - Accumulation of pre-computed SHA-256 hashes with XOR and Merkle tree operations
+ * - Merkle tree construction, proof generation, and verification
+ * 
+ * Usage examples:
+ * 
+ * Incremental hash calculation:
+ * ```typescript
+ * const calculator = new HashCalculator({ useSHA256: true });
+ * calculator.update(dataChunk);
+ * const crc32 = calculator.finalizeCRC32();
+ * const sha256 = calculator.finalizeSHA256();
+ * ```
+ * 
+ * Hash accumulation:
+ * ```typescript
+ * const calculator = new HashCalculator({ enableAccumulation: true });
+ * calculator.addHash(sha256Hash1);
+ * calculator.addHash(sha256Hash2);
+ * const xor = calculator.xorHash();
+ * const merkle = calculator.merkleRoot();
+ * ```
+ */
+export class HashCalculator {
+  // Incremental hash calculation state (from StreamHashCalculator)
+  private crc32State: number = ~0;
+  private sha256Hash: crypto.Hash | null = null;
+  private useSHA256: boolean = false;
+
+  // Hash accumulation state (from HashAccumulator)
+  private hashes: Buffer[] = [];
+  private xorResult: Buffer = Buffer.alloc(32, 0);
+  private enableAccumulation: boolean = false;
+
+  // Merkle tree state (from MerkleTree)
+  private merkleLeaves: Buffer[] = [];
+  private merkleLayers: Buffer[][] = [];
+  private merkleOptions: MerkleTreeOptions = {
+    hashLeaves: false,
+    sortLeaves: true,
+    sortPairs: true,
+    duplicateOdd: true
+  };
+
+  /**
+   * Creates a new HashCalculator instance
+   * @param options - Configuration options:
+   *   - useSHA256: Enable SHA-256 calculation for incremental mode (default: false)
+   *   - enableAccumulation: Enable hash accumulation mode (default: false)
+   */
+  constructor(options?: {
+    useSHA256?: boolean;
+    enableAccumulation?: boolean;
+  }) {
+    this.useSHA256 = options?.useSHA256 || false;
+    this.enableAccumulation = options?.enableAccumulation || false;
+
+    if (this.useSHA256) {
+      this.sha256Hash = crypto.createHash('sha256');
+    }
+  }
+
+  // ============================================================================
+  // Incremental Hash Calculation Methods (from StreamHashCalculator)
+  // ============================================================================
+
+  /**
+   * Update hash state with a new chunk of data
+   * Updates both CRC-32 and SHA-256 (if enabled) incrementally
+   * @param chunk - Data chunk to process
+   */
+  update(chunk: Buffer): void {
+    // Update CRC-32 incrementally using existing crc32update function
+    for (let i = 0; i < chunk.length; i++) {
+      this.crc32State = crc32update(this.crc32State, chunk[i]);
+    }
+    
+    // Update SHA-256 incrementally
+    if (this.sha256Hash) {
+      this.sha256Hash.update(chunk);
+    }
+  }
+
+  /**
+   * Get final CRC-32 value
+   * @returns Final CRC-32 value as unsigned 32-bit integer
+   */
+  finalizeCRC32(): number {
+    return ~this.crc32State >>> 0; // Finalize with ~0 like the existing crc32 function
+  }
+
+  /**
+   * Get final SHA-256 hash as hex string
+   * @returns SHA-256 hash as hex string, or null if SHA-256 not enabled
+   */
+  finalizeSHA256(): string | null {
+    if (this.sha256Hash) {
+      return this.sha256Hash.digest('hex');
+    }
+    return null;
+  }
+
+  /**
+   * Reset the incremental hash calculation state
+   */
+  reset(): void {
+    this.crc32State = ~0;
+    if (this.sha256Hash) {
+      this.sha256Hash = crypto.createHash('sha256');
+    }
+  }
+
+  // ============================================================================
+  // Hash Accumulation Methods (from HashAccumulator)
+  // ============================================================================
+
+  /**
+   * Adds a pre-computed SHA-256 hash to both the XOR accumulation and hash array
+   * @param hash - Hash value as hex string or Buffer (must be 32 bytes for SHA-256)
+   */
+  addHash(hash: string | Buffer): void {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+
+    // Convert hash to Buffer if it's a string
+    const hashBuffer = typeof hash === 'string' 
+      ? Buffer.from(hash, 'hex') 
+      : hash;
+
+    // Add to array for Merkle tree
+    this.hashes.push(hashBuffer);
+    this.merkleLeaves.push(hashBuffer);
+
+    // XOR accumulation
+    for (let i = 0; i < 32; i++) {
+      this.xorResult[i] ^= hashBuffer[i];
+    }
+
+    // Rebuild Merkle tree when hash is added
+    this.rebuildMerkleTree();
+  }
+
+  /**
+   * Gets the accumulated XOR of all added hashes
+   * @returns Hex string of XOR result
+   */
+  xorHash(): string {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+    return this.xorResult.toString('hex');
+  }
+
+  /**
+   * Creates a Merkle tree from accumulated hashes and returns the root
+   * @returns Hex string of Merkle root, or null if no hashes added
+   */
+  merkleRoot(): string | null {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+
+    if (this.merkleLeaves.length === 0) {
+      return null;
+    }
+
+    // If Merkle tree not built yet, build it
+    if (this.merkleLayers.length === 0) {
+      this.rebuildMerkleTree();
+    }
+
+    const root = this.merkleLayers[this.merkleLayers.length - 1];
+    if (root && root.length > 0) {
+      return root[0].toString('hex');
+    }
+
+    return null;
+  }
+
+  /**
+   * Gets the number of hashes accumulated
+   * @returns Number of accumulated hashes
+   */
+  leafCount(): number {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+    return this.hashes.length;
+  }
+
+  /**
+   * Clears the accumulated hashes and resets XOR buffer
+   */
+  clear(): void {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+    this.hashes = [];
+    this.merkleLeaves = [];
+    this.merkleLayers = [];
+    this.xorResult = Buffer.alloc(32, 0);
+  }
+
+  /**
+   * Combines multiple hash results into a single Merkle root
+   * Static method for combining results from multiple HashCalculator instances
+   * @param results - Array of objects containing merkleRoot properties
+   * @returns Combined Merkle root as hex string, or null if no valid roots
+   */
+  static combineResults(results: { merkleRoot?: string }[]): string | null {
+    const calculator = new HashCalculator({ enableAccumulation: true });
+    
+    // Combine all hashes
+    for (const result of results) {
+      if (result.merkleRoot) {
+        calculator.addHash(result.merkleRoot);
+      }
+    }
+
+    return calculator.merkleRoot();
+  }
+
+  // ============================================================================
+  // Merkle Tree Methods (from MerkleTree)
+  // ============================================================================
+
+  /**
+   * Computes SHA-256 hash of input data
+   * @param data - Data to hash
+   * @returns Buffer containing hash
+   */
+  private hash(data: Buffer): Buffer {
+    return crypto.createHash('sha256').update(data).digest();
+  }
+
+  /**
+   * Combines two child hashes to create parent hash
+   * @param left - Left child hash
+   * @param right - Right child hash
+   * @returns Combined hash of children
+   */
+  private combinedHash(left: Buffer, right: Buffer): Buffer {
+    if (this.merkleOptions.sortPairs && Buffer.compare(left, right) > 0) {
+      [left, right] = [right, left];
+    }
+    return this.hash(Buffer.concat([left, right]));
+  }
+
+  /**
+   * Builds the Merkle tree by creating successive layers of hashes
+   * @param nodes - Array of nodes in current layer
+   */
+  private createHashes(nodes: Buffer[]): void {
+    while (nodes.length > 1) {
+      const layerIndex = this.merkleLayers.length;
+      this.merkleLayers.push([]);
+
+      // Process pairs of nodes
+      for (let i = 0; i < nodes.length - 1; i += 2) {
+        const left = nodes[i];
+        const right = nodes[i + 1];
+        const hash = this.combinedHash(left, right);
+        this.merkleLayers[layerIndex].push(hash);
+      }
+
+      // Handle odd number of nodes
+      if (nodes.length % 2 === 1) {
+        const last = nodes[nodes.length - 1];
+        if (this.merkleOptions.duplicateOdd) {
+          // Duplicate the last node if odd
+          const hash = this.combinedHash(last, last);
+          this.merkleLayers[layerIndex].push(hash);
+        } else {
+          // Push last node up to next layer
+          this.merkleLayers[layerIndex].push(last);
+        }
+      }
+
+      nodes = this.merkleLayers[layerIndex];
+    }
+  }
+
+  /**
+   * Rebuilds the Merkle tree from current leaves
+   */
+  private rebuildMerkleTree(): void {
+    if (this.merkleLeaves.length === 0) {
+      this.merkleLayers = [];
+      return;
+    }
+
+    // Process leaves according to options
+    const processedLeaves = this.merkleLeaves.map(leaf => {
+      if (this.merkleOptions.hashLeaves) {
+        return this.hash(leaf);
+      }
+      return Buffer.isBuffer(leaf) ? leaf : Buffer.from(leaf);
+    });
+
+    if (this.merkleOptions.sortLeaves) {
+      processedLeaves.sort(Buffer.compare);
+    }
+
+    this.merkleLayers = [processedLeaves];
+    this.createHashes(processedLeaves);
+  }
+
+  /**
+   * Generates a proof of inclusion for a leaf node
+   * @param leaf - The leaf node to generate proof for
+   * @returns Array of sibling hashes needed to reconstruct root
+   * @throws Error if leaf not found in tree or accumulation not enabled
+   */
+  getProof(leaf: Buffer): Buffer[] {
+    if (!this.enableAccumulation) {
+      throw new Error('Hash accumulation not enabled. Set enableAccumulation: true in constructor.');
+    }
+
+    if (this.merkleLayers.length === 0) {
+      this.rebuildMerkleTree();
+    }
+
+    let index = this.merkleLeaves.findIndex(item => item.equals(leaf));
+    if (index === -1) {
+      throw new Error('Leaf not found in tree');
+    }
+
+    return this.merkleLayers.reduce((proof, layer) => {
+      if (layer.length === 1) return proof;
+
+      const pairIndex = index % 2 === 0 ? index + 1 : index - 1;
+      if (pairIndex < layer.length) {
+        proof.push(layer[pairIndex]);
+      }
+
+      index = Math.floor(index / 2);
+      return proof;
+    }, [] as Buffer[]);
+  }
+
+  /**
+   * Verifies a proof of inclusion for a leaf node
+   * @param proof - Array of sibling hashes from getProof()
+   * @param targetHash - Hash of the leaf node being verified
+   * @param root - Expected root hash
+   * @returns boolean indicating if proof is valid
+   */
+  verify(proof: Buffer[], targetHash: Buffer, root: Buffer): boolean {
+    let computedHash = targetHash;
+
+    for (const proofElement of proof) {
+      computedHash = Buffer.compare(computedHash, proofElement) <= 0
+        ? this.combinedHash(computedHash, proofElement)
+        : this.combinedHash(proofElement, computedHash);
+    }
+
+    return computedHash.equals(root);
+  }
+}
+
+// Default export
+export default HashCalculator;
+

package/src/core/components/Logger.ts

@@ -0,0 +1,180 @@
+/**
+ * Global Logger Utility for NeoZipKit
+ * Provides centralized console control with configurable log levels
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface LoggerConfig {
+  enabled: boolean;
+  level: LogLevel;
+}
+
+/**
+ * Global Logger class for controlling console output throughout NeoZipKit
+ */
+export class Logger {
+  private static config: LoggerConfig = {
+    enabled: true,
+    level: 'info'
+  };
+
+  private static originalConsole = {
+    log: console.log,
+    error: console.error,
+    warn: console.warn,
+    debug: console.debug,
+    info: console.info
+  };
+
+  /**
+   * Configure the logger
+   */
+  static configure(config: Partial<LoggerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current logger configuration
+   */
+  static getConfig(): LoggerConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Enable logging
+   */
+  static enable(): void {
+    this.config.enabled = true;
+  }
+
+  /**
+   * Disable all logging
+   */
+  static disable(): void {
+    this.config.enabled = false;
+  }
+
+  /**
+   * Set log level
+   */
+  static setLevel(level: LogLevel): void {
+    this.config.level = level;
+  }
+
+
+  /**
+   * Check if a log level should be output
+   */
+  private static shouldLog(level: LogLevel): boolean {
+    if (!this.config.enabled) return false;
+    
+    const levels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'silent'];
+    const currentLevelIndex = levels.indexOf(this.config.level);
+    const requestedLevelIndex = levels.indexOf(level);
+    
+    return requestedLevelIndex >= currentLevelIndex;
+  }
+
+  /**
+   * Log a message
+   */
+  static log(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      this.originalConsole.log(...args);
+    }
+  }
+
+  /**
+   * Log an error message
+   */
+  static error(...args: any[]): void {
+    if (this.shouldLog('error')) {
+      this.originalConsole.error(...args);
+    }
+  }
+
+  /**
+   * Log a warning message
+   */
+  static warn(...args: any[]): void {
+    if (this.shouldLog('warn')) {
+      this.originalConsole.warn(...args);
+    }
+  }
+
+  /**
+   * Log a debug message
+   */
+  static debug(...args: any[]): void {
+    if (this.shouldLog('debug')) {
+      // Use console.log for debug messages to ensure they're visible
+      this.originalConsole.log(...args);
+    }
+  }
+
+  /**
+   * Log an info message
+   */
+  static info(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      this.originalConsole.info(...args);
+    }
+  }
+
+
+  /**
+   * Override console methods globally (use with caution)
+   */
+  static overrideConsole(): void {
+    console.log = (...args: any[]) => this.log(...args);
+    console.error = (...args: any[]) => this.error(...args);
+    console.warn = (...args: any[]) => this.warn(...args);
+    console.debug = (...args: any[]) => this.debug(...args);
+    console.info = (...args: any[]) => this.info(...args);
+  }
+
+  /**
+   * Restore original console methods
+   */
+  static restoreConsole(): void {
+    console.log = this.originalConsole.log;
+    console.error = this.originalConsole.error;
+    console.warn = this.originalConsole.warn;
+    console.debug = this.originalConsole.debug;
+    console.info = this.originalConsole.info;
+  }
+
+}
+
+/**
+ * Environment-based configuration
+ */
+export function configureLoggerFromEnvironment(): void {
+  const env = typeof process !== 'undefined' ? process.env : {};
+  
+  // Check for NEOZIP_DEBUG environment variable
+  if (env.NEOZIP_DEBUG === 'false') {
+    Logger.disable();
+  } else if (env.NEOZIP_DEBUG === 'true') {
+    Logger.enable();
+    Logger.setLevel('debug');
+  }
+
+  // Check for NEOZIP_LOG_LEVEL
+  if (env.NEOZIP_LOG_LEVEL) {
+    const level = env.NEOZIP_LOG_LEVEL as LogLevel;
+    if (['debug', 'info', 'warn', 'error', 'silent'].includes(level)) {
+      Logger.setLevel(level);
+    }
+  }
+
+  // Check for NODE_ENV
+  if (env.NODE_ENV === 'production') {
+    Logger.setLevel('error');
+  }
+}
+
+// Auto-configure from environment on import
+// Only run in Node.js environment
+configureLoggerFromEnvironment();

package/src/core/components/ProgressTracker.ts

@@ -0,0 +1,134 @@
+/**
+ * Progress tracker for streaming operations
+ * Provides real-time progress updates and ETA calculations
+ */
+export class ProgressTracker {
+  private startTime: number;
+  private lastUpdateTime: number;
+  private totalBytes: number;
+  private processedBytes: number;
+  private fileName: string;
+  private lastReportedPercent: number = -1;
+
+  constructor(fileName: string, totalBytes: number) {
+    this.fileName = fileName;
+    this.totalBytes = totalBytes;
+    this.processedBytes = 0;
+    this.startTime = Date.now();
+    this.lastUpdateTime = this.startTime;
+  }
+
+  /**
+   * Update progress with bytes processed
+   * @param bytesProcessed - Number of bytes processed in this update
+   */
+  update(bytesProcessed: number): void {
+    this.processedBytes += bytesProcessed;
+    this.reportProgress();
+  }
+
+  /**
+   * Set total bytes (useful when file size changes)
+   */
+  setTotalBytes(totalBytes: number): void {
+    this.totalBytes = totalBytes;
+  }
+
+  /**
+   * Report progress if enough time has passed or significant progress made
+   */
+  private reportProgress(): void {
+    const now = Date.now();
+    const percent = Math.floor((this.processedBytes / this.totalBytes) * 100);
+    
+    // Report if:
+    // 1. 1% or more progress made, OR
+    // 2. 500ms have passed since last report
+    const shouldReport = 
+      percent > this.lastReportedPercent || 
+      (now - this.lastUpdateTime) > 500;
+
+    if (shouldReport) {
+      this.lastReportedPercent = percent;
+      this.lastUpdateTime = now;
+      this.printProgress();
+    }
+  }
+
+  /**
+   * Print progress information
+   */
+  private printProgress(): void {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    const rate = this.processedBytes / elapsed;
+    const eta = this.totalBytes > this.processedBytes 
+      ? (this.totalBytes - this.processedBytes) / rate 
+      : 0;
+    const percent = Math.floor((this.processedBytes / this.totalBytes) * 100);
+
+    const formatBytes = (bytes: number): string => {
+      const units = ['B', 'KB', 'MB', 'GB'];
+      let size = bytes;
+      let unitIndex = 0;
+      
+      while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+      }
+      
+      return `${size.toFixed(1)}${units[unitIndex]}`;
+    };
+
+    const formatTime = (seconds: number): string => {
+      if (seconds < 60) return `${seconds.toFixed(0)}s`;
+      if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${(seconds % 60).toFixed(0)}s`;
+      return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+    };
+
+    process.stdout.write(
+      `\r${this.fileName}: ${percent}% (${formatBytes(this.processedBytes)}/${formatBytes(this.totalBytes)}) ` +
+      `[${formatBytes(rate)}/s] ETA: ${formatTime(eta)}`
+    );
+  }
+
+  /**
+   * Complete progress tracking
+   */
+  complete(): void {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    const rate = this.processedBytes / elapsed;
+    
+    const formatBytes = (bytes: number): string => {
+      const units = ['B', 'KB', 'MB', 'GB'];
+      let size = bytes;
+      let unitIndex = 0;
+      
+      while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+      }
+      
+      return `${size.toFixed(1)}${units[unitIndex]}`;
+    };
+
+    console.log(
+      `\r${this.fileName}: 100% (${formatBytes(this.processedBytes)}) ` +
+      `[${formatBytes(rate)}/s] completed in ${elapsed.toFixed(1)}s`
+    );
+  }
+
+  /**
+   * Get current progress percentage
+   */
+  getProgressPercent(): number {
+    return Math.floor((this.processedBytes / this.totalBytes) * 100);
+  }
+
+  /**
+   * Get processing rate in bytes per second
+   */
+  getProcessingRate(): number {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    return this.processedBytes / elapsed;
+  }
+}