neozipkit 0.1.1

package/src/shared/ZipKit.ts

@@ -0,0 +1,899 @@
+// ======================================
+//	ZipKit.ts
+//  Copyright (c) 2025 NeoWare, Inc. All rights reserved.
+// ======================================
+
+import ZipEntry from './ZipEntry';
+import Errors from './constants/Errors';
+import { crc32, readBigUInt64LE } from './components/Util';
+import { sha256, decrypter, encrypter } from './components/ZipCrypto';
+import Support from './components/Support';
+import pako from 'pako';
+import { 
+  LOCAL_HDR,
+  ENCRYPT_HDR_SIZE,
+  CMP_METHOD,
+  CENTRAL_END, 
+  CENTRAL_DIR, 
+  ZIP64_CENTRAL_END, 
+  ZIP64_CENTRAL_DIR ,
+  GP_FLAG,
+  TIMESTAMP_SUBMITTED,
+  TIMESTAMP_METADATA,
+  TOKENIZED_METADATA,
+  LOCAL_FILE_HEADER,
+  CENTRAL_FILE_HEADER,
+  CENTRAL_DIRECTORY_END,
+  HDR_ID
+} from './constants/Headers';
+import HashAccumulater from './components/HashAccumulator';
+import { ZstdInit, ZstdSimple } from '@oneidentity/zstd-js';
+import { NEOZIPKIT_INFO } from './types';
+
+// We'll initialize zstd when needed
+let zstdCodec: { ZstdSimple: typeof ZstdSimple } | null = null;
+
+// Async initialization function for zstd
+async function initZstd(): Promise<{ ZstdSimple: typeof ZstdSimple }> {
+  if (!zstdCodec) {
+    zstdCodec = await ZstdInit();
+  }
+  return zstdCodec;
+}
+
+export { 
+  ZipEntry, 
+  Errors, 
+  CMP_METHOD, 
+  TIMESTAMP_METADATA, 
+  TIMESTAMP_SUBMITTED,
+  TOKENIZED_METADATA,
+  LOCAL_HDR,
+  ENCRYPT_HDR_SIZE,
+  CENTRAL_END, 
+  CENTRAL_DIR, 
+  ZIP64_CENTRAL_END, 
+  ZIP64_CENTRAL_DIR ,
+  GP_FLAG,
+  LOCAL_FILE_HEADER,
+  CENTRAL_FILE_HEADER,
+  CENTRAL_DIRECTORY_END,
+  HDR_ID
+};
+
+/**
+ * Options for compressing files in a ZIP archive
+ */
+export interface CompressOptions {
+  level?: number;             // Compression level (1-9, 0=store)
+  password?: string | null;   // Password for encryption
+  useSHA256?: boolean;        // Whether to calculate SHA256 hash default is false
+  useZstd?: boolean;          // Whether to use Zstandard compression default is true
+}
+
+/**
+ * Callbacks for ZIP file creation process
+ */
+export interface CreateZipOptions {
+  onError?: (error: Error) => void;              // Called when an error occurs
+  onEntryDone?: (entry: ZipEntry, status: string) => void;  // Called when entry processing completes
+  onReadEntryData?: (entry: ZipEntry) => Buffer; // Called to read entry data
+  onOutputBuffer?: (data: Buffer) => void;       // Called to write output data
+}
+
+/**
+ * Main class for ZIP file operations including compression, extraction, and encryption
+ */
+export default class ZipKit {
+  static readonly version = NEOZIPKIT_INFO.version;
+  static readonly releaseDate = NEOZIPKIT_INFO.releaseDate;
+
+  private inBuffer: Buffer | null = null;
+  private zipEntries: ZipEntry[] = [];
+  private sortName = false;
+
+  // Central End Directory values for existing Zip file
+  private centralDirSize: number = 0;
+  private centralDirOffset: number = 0;
+
+  // Timestamp values
+  private stampEntry: ZipEntry | null = null;
+
+  zipComment: string | null = null;
+
+  static support = Support;
+
+  /**
+   * Creates a new ZipKit instance
+   */
+  constructor() {
+  }
+
+  /**
+   * Resets all ZIP-related data to initial state
+   */
+  resetZipData() {
+    this.inBuffer = null;
+    this.zipEntries = [];
+    this.centralDirSize = 0;
+    this.centralDirOffset = 0;
+    this.zipComment = null;
+  }
+  
+  /**
+   * Loads a ZIP file from a buffer
+   * @param inBuf - Buffer containing ZIP file data
+   */
+  loadZip(inBuf: Buffer) {
+    this.resetZipData();
+    this.inBuffer = inBuf;
+  }
+
+  /**
+   * Tests if data matches the CRC32 checksum
+   * @param entry - ZIP entry to check
+   * @param data - Data buffer to verify
+   * @returns boolean indicating if CRC matches
+   */
+  testCRC32(entry: ZipEntry, data: Buffer): boolean {
+    // if bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written
+    if ((entry.bitFlags & 0x8) !== 0x8) {
+      const _crc = crc32(data);
+      // console.log('    CRC: '+ sprintf("%08x", _crc));
+      // console.log('ent.CRC: ' + sprintf("%08x", entry.crc));
+      if (_crc !== entry.crc) {
+          return false;
+      }
+    } else {
+      // @TODO: load and check data descriptor header
+      // The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure
+      // (optionally preceded by a 4-byte signature) immediately after the compressed data:
+    }
+
+    return true;
+  }
+
+  /**
+   * Tests if data matches the SHA256 hash
+   * @param entry - ZIP entry to check
+   * @param data - Data buffer to verify
+   * @returns boolean indicating if SHA256 matches
+   * @throws Error if entry has no SHA256 hash
+   */
+  testSHA256(entry: ZipEntry, data: Buffer): boolean {
+    if (!entry.sha256) {
+      throw new Error(Errors.UNKNOWN_SHA256);
+    }
+    const _sha256 = sha256(data);
+    return _sha256 === entry.sha256;
+  }
+
+  /**
+   * Locates and parses the central end directory
+   * @param inBuffer - Buffer containing ZIP file data
+   * @returns Number of entries in ZIP file
+   * @throws Error if central directory is invalid
+   */
+  getCentralEnd(inBuffer: Buffer): number {
+    let i = inBuffer.length - CENTRAL_END.SIZE;
+    let max = Math.max(0, i - 0xffff);            // 0xFFFF is the max zip file comment length
+    let endStart = inBuffer.length;
+    let endOffset = -1;                           // Start offset of the END header
+    let commentEnd = 0;
+    let volEntries = 0;
+    let totalEntries = 0;
+
+    for (let n=max; i >= n; i--) {
+      if (inBuffer[i] !== 0x50) continue; // quick check that the byte is 'P'
+      if (inBuffer.readUInt32LE(i) === CENTRAL_END.SIGNATURE) {
+        // "PK\005\006"
+        endOffset = i;
+        commentEnd = i;
+        endStart = i + CENTRAL_END.SIZE;
+        // We already found a regular signature, let's look just a bit further to check if there's any zip64 signature
+        n = i - ZIP64_CENTRAL_END.SIZE;
+        continue;
+      }
+
+      if (inBuffer.readUInt32LE(i) === ZIP64_CENTRAL_END.SIGNATURE) {
+        // Found a zip64 signature, let's continue reading the whole zip64 record
+        n = max;
+        continue;
+      }
+
+      if (inBuffer.readUInt32LE(i) === ZIP64_CENTRAL_DIR.SIGNATURE) {
+        // Found the zip64 record, let's determine it's size
+        endOffset = i;
+        endStart = i + readBigUInt64LE(inBuffer, i + ZIP64_CENTRAL_DIR.SIZE) + ZIP64_CENTRAL_DIR.LEAD;
+        break;
+      }
+    }
+    
+    if (!~endOffset) throw new Error(Errors.INVALID_FORMAT);
+
+    let data = inBuffer.subarray(endOffset, endStart);
+
+    if (data.readUInt32LE(0) == CENTRAL_END.SIGNATURE) {
+      // number of entries on this volume
+      volEntries = data.readUInt16LE(CENTRAL_END.VOL_ENTRIES);
+      // total number of entries
+      totalEntries = data.readUInt16LE(CENTRAL_END.TOTAL_ENTRIES);
+      // central directory size in bytes
+      this.centralDirSize = data.readUInt32LE(CENTRAL_END.CENTRAL_DIR_SIZE);
+      // offset of first CEN header
+      this.centralDirOffset = data.readUInt32LE(CENTRAL_END.CENTRAL_DIR_OFFSET);
+    } else {
+      // number of entries on this volume
+      volEntries = readBigUInt64LE(data, ZIP64_CENTRAL_DIR.VOL_ENTRIES);
+      // total number of entries
+      totalEntries = readBigUInt64LE(data, ZIP64_CENTRAL_DIR.TOTAL_ENTRIES);
+      // central directory size in bytes
+      this.centralDirSize = readBigUInt64LE(data, ZIP64_CENTRAL_DIR.CENTRAL_DIR_SIZE);
+      // offset of first CEN header
+      this.centralDirOffset = readBigUInt64LE(data, ZIP64_CENTRAL_DIR.CENTRAL_DIR_OFFSET);
+    }
+
+    // zip file comment length
+    let commentLength = data.readUInt16LE(CENTRAL_END.ZIP_COMMENT_LEN);
+    if (commentLength > 0) {
+      this.zipComment = inBuffer.subarray(endStart, endStart + commentLength).toString();
+    } 
+
+    // console.log('totalEntries: ', totalEntries);
+    // console.log('centralDirSize; ', this.centralDirSize);
+    // console.log('centralDirOffset: ', this.centralDirOffset);
+    // console.log('commentLength: ', commentLength);
+    // console.log('zipComment: ', this.zipComment);
+
+    return totalEntries;
+  }
+
+  /**
+   * Creates the central end directory header
+   * @param centralDirSize - Size of central directory
+   * @param centralDirOffset - Offset to central directory
+   * @returns Buffer containing end directory header
+   */
+  centralEndHdr(centralDirSize: number, centralDirOffset: number): Buffer {
+    const commentLen = this.zipComment ? this.zipComment.length : 0;
+    const data = Buffer.alloc(CENTRAL_END.SIZE + commentLen);
+    
+    // "PK\005\006"
+    data.writeUInt32LE(CENTRAL_END.SIGNATURE, 0);
+    // number of this disk
+    data.writeUInt16LE(0, CENTRAL_END.VOL_NUM);
+    // number of the volume/disk with start of the Central Directory
+    data.writeUInt16LE(0, CENTRAL_END.VOLDIR_START);
+    // number of entries on this volume/disk
+    data.writeUInt16LE(0, CENTRAL_END.VOL_ENTRIES);
+    // total number of entries on this disk
+    data.writeUInt16LE(this.zipEntries.length, CENTRAL_END.TOTAL_ENTRIES);
+    // central directory size in bytes
+    data.writeUInt32LE(centralDirSize, CENTRAL_END.CENTRAL_DIR_SIZE);
+    // offset of first Central Directory Entry
+    data.writeUInt32LE(centralDirOffset, CENTRAL_END.CENTRAL_DIR_OFFSET);
+    // Zip file comment length
+    data.writeUInt16LE(commentLen, CENTRAL_END.ZIP_COMMENT_LEN);
+
+    if (commentLen > 0 && this.zipComment) {
+        const zipCommentBuf = Buffer.from(this.zipComment, 'utf8');
+        zipCommentBuf.copy(data, CENTRAL_END.SIZE);  
+    }
+
+    return data;
+  }
+
+  /**
+   * Reads and parses the ZIP file directory
+   * @param debug - Enable debug logging
+   * @returns Array of ZIP entries
+   */
+  getDirectory(debug?: boolean): ZipEntry[] {
+    if (this.zipEntries.length > 0) {
+      return this.zipEntries;
+    }
+    const buffer = this.ensureBuffer();
+    
+    // Add this check for empty buffers - if empty, there's no need to try parsing
+    if (buffer.length === 0) {
+      // This is a new ZIP file, so we return an empty array
+      return this.zipEntries;
+    }
+    
+    const entries = this.getCentralEnd(buffer);
+    if (entries === 0) return [];
+
+    var entryData = buffer.subarray(this.centralDirOffset, this.centralDirOffset + this.centralDirSize);
+    if (entryData.readUInt32LE(0) !== CENTRAL_DIR.SIGNATURE) throw new Error(Errors.INVALID_CEN);
+
+    const entryList: ZipEntry[] = [];
+    for (var i=0; i < entries; i++) {
+      let entry = new ZipEntry(null, null, debug);
+      entryData = entry.readZipEntry(entryData);
+      entryList.push(entry);
+      // entry.outputZipEntry();
+    }
+
+    this.zipEntries = entryList;
+
+    // Sort Zip Entries if sortName option set
+    if (this.sortName && this.zipEntries.length > 1)
+      this.zipEntries.sort((a,b) => {
+        return (a.filename || '').toLowerCase()
+          .localeCompare((b.filename || '').toLowerCase());
+      });
+
+    return this.zipEntries;
+  }
+
+  /**
+   * Gets a ZIP entry by filename
+   * @param fname - Filename to search for
+   * @returns ZipEntry if found, null otherwise
+   */
+  getZipEntry(fname: string): ZipEntry | null {
+    try {
+      const centralDir = this.getDirectory();
+      if (centralDir) {
+        for (const entry of centralDir) {
+          if (entry.filename === fname) {
+            return entry;
+          }
+        }
+      }
+      return null;
+    } catch (error) {
+      // If we get here, treat as a new file (no existing entry)
+      return null;
+    }
+  }
+
+  /**
+   * Creates a new ZIP entry
+   * @param fname - Filename for new entry
+   * @param comment - Optional entry comment
+   * @returns Created ZipEntry
+   */
+  createZipEntry(fname: string, comment?: string): ZipEntry {
+    const entry = new ZipEntry(fname, comment);
+    this.zipEntries.push(entry);
+    return entry;
+  }
+
+  /**
+   * Deletes an entry from the ZIP file
+   * @param fname - Filename to delete
+   * @returns boolean indicating if file was deleted
+   */
+  deleteFile(fname: string): boolean {
+    const entries = this.ensureZipEntries();
+    const index = entries.findIndex(zipEntry => zipEntry.filename === fname);
+    if (index < 0) return false;
+    entries.splice(index, 1);
+    return true;
+  }
+
+  /**
+   * Parses local header and returns entry data
+   * @param entry - ZIP entry to parse
+   * @param withLocalHdrData - Include header in returned data
+   * @returns Buffer containing entry data
+   * @throws Error if header is invalid
+   */
+  parseLocalHeader(entry: ZipEntry, withLocalHdrData?: boolean): Buffer {
+    const buffer = this.ensureBuffer();
+    const localData = buffer.subarray(entry.localHdrOffset);
+
+    // data should be 30 bytes and start with "PK 03 04" 
+    if (localData.readUInt32LE(0) !==  LOCAL_HDR.SIGNATURE) {
+      throw new Error(Errors. INVALID_CEN);
+    }
+
+    // Check for Data Descriptor Flag
+    let _encryptLen = 0;
+    const _bitFlags = localData.readUInt16LE(LOCAL_HDR.FLAGS);
+    if (_bitFlags & GP_FLAG.ENCRYPTED) {
+      _encryptLen = ENCRYPT_HDR_SIZE;
+    }
+    if (_bitFlags & GP_FLAG.DATA_DESC) {
+      entry.bitFlags |= GP_FLAG.DATA_DESC;
+      entry.lastModTimeDate = localData.readUInt32LE(LOCAL_HDR.TIMEDATE_DOS);
+    }
+
+    let _fnameLen = localData.readUInt16LE(LOCAL_HDR.FNAME_LEN);
+    let _extraLen = localData.readUInt16LE(LOCAL_HDR.EXTRA_LEN);
+    let _localSize = LOCAL_HDR.SIZE + _fnameLen + _extraLen;
+    if (_encryptLen != 0) {
+      entry.encryptHdr = Buffer.from(localData.subarray(_localSize, _localSize + _encryptLen));
+    }
+
+    if (withLocalHdrData) 
+      return localData.subarray(0, _localSize + entry.compressedSize);
+
+    return localData.subarray(_localSize + _encryptLen, _localSize + entry.compressedSize);
+  }
+
+  /**
+   * Copies an entry's data from source ZIP
+   * @param entry - Entry to copy
+   * @returns Buffer containing entry data with headers
+   */
+  copyEntry(entry: ZipEntry): Buffer {
+     return this.parseLocalHeader(entry, true);
+  }
+
+  /**
+   * Compresses data for a ZIP entry
+   * @param entry - ZIP entry to compress
+   * @param data - Data to compress
+   * @param options - Compression options
+   * @returns Buffer containing compressed data
+   */
+  async compressData(entry: ZipEntry, data: Buffer, options?: CompressOptions) : Promise<Buffer> {
+    // Initialize with empty buffer instead of null
+    let buffer: Buffer = Buffer.alloc(0);
+    
+    // Determine compression method based on options
+    if (options?.level === 0) {
+      // Level 0 means "store" (no compression)
+      entry.cmpMethod = CMP_METHOD.STORED;
+      buffer = data;
+    } else if (options?.useZstd) {
+      // Use Zstandard compression
+      if (data.length < 100) {
+        // ZStd requires at least 100 bytes, store it without compression
+        entry.cmpMethod = CMP_METHOD.STORED;
+        buffer = data;
+      } else {
+        entry.cmpMethod = CMP_METHOD.ZSTD;
+        buffer = await this.zstdCompress(data, options);
+      }
+    } else {
+      // Default to deflate
+      entry.cmpMethod = CMP_METHOD.DEFLATED;
+      buffer = this.deflate(data, options);
+    }
+  
+    entry.crc = crc32(data);
+    // console.log('CRC: '+ sprintf("%08x", entry.crc));
+
+    if (options?.useSHA256) {
+      entry.sha256 = sha256(data);
+      console.log('SHA256: ', entry.sha256);
+    };
+
+    if (options?.password) {
+      entry.bitFlags = GP_FLAG.ENCRYPTED;
+      const _check = (entry.crc >> 24) & 0xff;
+      const encryptedBuffer = encrypter(buffer, _check, options.password);
+      // Handle potential null return from encrypter
+      if (!encryptedBuffer) {
+        throw new Error(Errors.ENCRYPT_FAILED);
+      }
+      buffer = encryptedBuffer;
+    }
+    entry.compressedSize = buffer.length;
+
+    return buffer;
+  }
+
+  /**
+   * Compresses data using deflate algorithm
+   * @param inbuf - Data to compress
+   * @param options - Compression options
+   * @returns Compressed data buffer
+   */
+  private deflate(inbuf: Buffer, options?: CompressOptions): Buffer {
+    if (options?.level == 0) {
+      return inbuf; // Store without compression
+    }
+    try {
+      const level = options?.level as 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | undefined;
+      const result = pako.deflateRaw(inbuf, {
+        level: level ?? 6
+      });
+      return Buffer.from(result.buffer, result.byteOffset, result.byteLength);
+    } catch (e) {
+      console.error('Error during compression:', e);
+      throw new Error(Errors.COMPRESSION_ERROR);
+    }
+  }
+
+  /**
+   * Compresses data using Zstandard (zstd) algorithm
+   * @param inbuf - Data to compress
+   * @param options - Compression options
+   * @returns Compressed data buffer
+   */
+  private async zstdCompress(inbuf: Buffer, options?: CompressOptions): Promise<Buffer> {
+    if (options?.level == 0) {
+      return inbuf; // Store without compression
+    }
+    try {
+      // Ensure zstd is initialized
+      const codec = await initZstd();
+      
+      // Zstd compression levels range from 1 (fastest) to 22 (highest compression)
+      // Map our 1-9 level to a reasonable zstd range (1-19)
+      const level = options?.level ?? 6;
+      const zstdLevel = Math.min(Math.max(1, Math.floor(level * 2.1)), 19);
+      
+      // Compress the data with zstd
+      const compressedData = codec.ZstdSimple.compress(inbuf, zstdLevel);
+      return Buffer.from(compressedData);
+    } catch (e) {
+      console.error('Error during zstd compression:', e);
+      throw new Error(Errors.COMPRESSION_ERROR);
+    }
+  }
+  
+  /**
+   * Decompresses data using Zstandard (zstd) algorithm
+   * @param inbuf - Compressed data buffer
+   * @returns Decompressed data buffer
+   */
+  async zstdDecompress(inbuf: Buffer): Promise<Buffer> {
+    try {
+      // Ensure zstd is initialized
+      const codec = await initZstd();
+      
+      const decompressedData = codec.ZstdSimple.decompress(inbuf);
+      return Buffer.from(decompressedData);
+    } catch (e) {
+      console.error('Error during zstd decompression:', e);
+      throw new Error(Errors.DECOMPRESSION_ERROR);
+    }
+  }
+
+  // ======================================
+  // deflateAsync(inbuf: Buffer, callback: (result: Buffer) => void) {
+  //   var opts = { chunkSize: ((inbuf.length >> 10) + 1) * 1024 };
+
+  //   var tmp = zlib.createDeflateRaw(opts),
+  //   parts = [],
+  //   total = 0;
+  //   tmp.on("data", function (data) {
+  //     parts.push(data);
+  //     total += data.length;
+  //   });
+  //   tmp.on("end", function () {
+  //     var buf = Buffer.alloc(total),
+  //       written = 0;
+  //     buf.fill(0);
+  //     for (var i = 0; i < parts.length; i++) {
+  //       var part = parts[i];
+  //       part.copy(buf, written);
+  //       written += part.length;
+  //     }
+  //     callback && callback(buf);
+  //   });
+  //   tmp.end(inbuf);
+  // }
+
+  /**
+   * Creates new Zip data file with the passed ZipEntries
+   * @param cmpOptions - Compression options
+   * @param zipOptions - Create ZIP options
+   * @returns Promise<number> - The offset of the last entry
+   */
+  async createZipFileData(cmpOptions?: CompressOptions, zipOptions?: CreateZipOptions): Promise<number> {
+    const _onError = zipOptions?.onError || ((error: Error) => { throw error; });
+    const _onEntryDone = zipOptions?.onEntryDone || (() => {});
+    const _onReadEntryData = zipOptions?.onReadEntryData || 
+        (() => { throw new Error('onReadEntryData callback is required'); });
+    const _onOutputBuffer = zipOptions?.onOutputBuffer || (() => {});
+
+    if (this.zipEntries.length === 0) {
+        _onError(new Error(Errors.NO_FILES));
+        return 0;  // Return 0 instead of undefined
+    }
+        
+    // console.log('Creating Zip File Data with ZipEntries: ', this.zipEntries);
+    let offset = 0;
+    let entryCnt = this.zipEntries.length;
+    for (let index = 0; index < entryCnt; index++) {
+      const entry = this.zipEntries[index];
+
+      // Remove any existing Timestamp Metadata entries
+      if (entry.filename === TIMESTAMP_METADATA || entry.filename === TIMESTAMP_SUBMITTED) {
+        this.zipEntries.splice(index, 1);
+        entryCnt--;
+        index--;
+        console.log('Deleting Timestamp Metadata entry: ', entry.filename);
+        continue;
+      }
+
+      if (!entry.isUpdated) {
+        console.log('Copying Entry: ', entry.filename);
+        const inData = this.copyEntry(entry);
+        entry.localHdrOffset = offset
+        offset += inData.length;
+        _onOutputBuffer(inData);
+        _onEntryDone(entry, 'Copied ');
+        continue;
+      }
+
+      // Compress the file data to set all zipEntry fields correctly
+      const fileBuffer = _onReadEntryData(entry);
+      const cmpData = await this.compressData(entry, fileBuffer, cmpOptions);
+
+      // Create a local header data buffer
+      const localHdr = entry.createLocalHdr();
+  
+      // Save local header offset for entry and calculate next offset
+      entry.localHdrOffset = offset;
+      
+      offset += localHdr.length + cmpData.length;
+  
+      // Write the data to the output file
+      _onOutputBuffer(localHdr);
+      _onOutputBuffer(cmpData);
+      _onEntryDone(entry, 'Written');
+    }
+
+    return offset;
+  }
+
+  /**
+   * Finishes Zip data file by adding any Metadata entries and the Central End Directory
+   * @param offset - The current offset in the zip data file
+   * @param onOutputBuffer - The callback function to output the data buffer
+   * @param metaEntry - The Metadata ZipEntry to add to the Zip file
+   */
+  async finishZipFileData(offset: number, onOutputBuffer: (data: Buffer) => void, metaEntry?: ZipEntry) {
+    if (metaEntry && metaEntry.fileBuffer) {
+        const localHdr = metaEntry.createLocalHdr();
+        metaEntry.localHdrOffset = offset;
+        offset += localHdr.length + metaEntry.fileBuffer.length;
+
+        onOutputBuffer(localHdr);
+        onOutputBuffer(metaEntry.fileBuffer);
+    }
+
+    // Output ZipEntries as Central End Directory
+    const centralDirOffset = offset;
+    for (const entry of this.zipEntries) {
+      const centralDirEntry = entry.centralDirEntry();
+      offset += centralDirEntry.length;
+      onOutputBuffer(centralDirEntry);
+    }
+    
+    const centralDirSize = offset - centralDirOffset;
+    const ceBuf = this.centralEndHdr(centralDirSize, centralDirOffset);
+    onOutputBuffer(ceBuf);
+  }
+
+  /**
+   * Unzips the data buffer using pako inflate method
+   * @param inbuf - Data buffer to inflate
+   * @returns Inflated data buffer
+   * @throws Error if extraction fails
+   */
+  inflate(inbuf: Buffer): Buffer {
+    const result = pako.inflateRaw(inbuf);
+    return Buffer.from(result.buffer, result.byteOffset, result.byteLength);
+  }
+
+  /**
+   * Extracts the data from the ZipEntry and returns the data as a Buffer
+   * @param entry - ZIP entry to extract
+   * @param skipHashCheck - Whether to skip hash checking
+   * @returns Buffer containing extracted data or null if extraction fails
+   */
+  async extract(entry: ZipEntry, skipHashCheck?: boolean): Promise<Buffer | null> {
+    const fdata = this.parseLocalHeader(entry);
+    if (fdata.length == 0) {
+      return null;
+    }
+
+    let outBuf = null;
+    switch (entry.cmpMethod) {
+      case CMP_METHOD.STORED:
+        outBuf = fdata;
+        break;
+      case CMP_METHOD.DEFLATED:
+        outBuf = this.inflate(fdata);
+        break;
+      case CMP_METHOD.ZSTD:
+        outBuf = await this.zstdDecompress(fdata);
+        break;
+      default:
+        throw new Error(Errors.UNKNOWN_METHOD);
+    }
+
+    // If no hash checking is requested, return the unmodified data
+    if (skipHashCheck) {
+      return outBuf;
+    }
+
+    // Verify integrity - use SHA256 if available, otherwise CRC32
+    if (entry.sha256) {
+      if (!this.testSHA256(entry, outBuf)) {
+        throw new Error(Errors.INVALID_SHA256);
+      }
+    } else {
+      if (!this.testCRC32(entry, outBuf)) {
+        throw new Error(Errors.INVALID_CRC);
+      }
+    }
+
+    return outBuf;
+  }  
+
+  /**
+   * Decrypts the entry data
+   * @param entry - ZIP entry to decrypt
+   * @param password - Password for decryption
+   * @returns Decrypted data buffer or null if decryption fails
+   */
+  decryptEntry(entry: ZipEntry, password: string): Buffer | null {
+    if (!entry.isEncrypted) return null;
+    if (entry.isStrongEncrypt)
+        throw new Error(Errors.STRONG_ENCRYPT_UNSUPPORTED);
+    if (!password) return null;
+
+    // Read the encryption header at start of data
+    let _localData = this.parseLocalHeader(entry);
+    const _decrypt = decrypter(password);
+    
+    const _encHdr = entry.encryptHdr;
+    if (!_encHdr) return null;
+    
+    const decryptedHeader = _decrypt(_encHdr);
+    
+    const _check = (entry.bitFlags & GP_FLAG.DATA_DESC) ? 
+        (entry.lastModTimeDate >> 8) & 0xff : 
+        ((entry.crc >> 24) & 0xff);
+        
+    if (decryptedHeader[11] !== _check)
+        return null;
+
+    _localData = _decrypt(_localData);
+    return _localData;
+  }
+
+  /**
+   * Checks if a filename is a blockchain metadata file that should be excluded from Merkle Root calculation
+   * @param filename - The filename to check
+   * @returns boolean - True if the file is a metadata file
+   */
+  private isMetadataFile(filename: string): boolean {
+    return filename === TIMESTAMP_SUBMITTED ||
+           filename === TIMESTAMP_METADATA ||
+           filename === TOKENIZED_METADATA;
+  }
+
+  /**
+   * Calculates the Merkle Root of the ZIP file
+   * Excludes blockchain metadata files (META-INF/*) to ensure consistent calculation
+   * @returns string - The Merkle Root of the ZIP file
+   */
+  getMerkleRoot(): string | null {
+    const zipEntries = this.getDirectory();
+    if (zipEntries.length === 0) return null;
+  
+    let _hashAccumulator = new HashAccumulater();
+    
+    // Filter out blockchain metadata files to ensure consistent Merkle Root calculation
+    const contentEntries = zipEntries.filter(entry => !this.isMetadataFile(entry.filename));
+    
+    for (const entry of contentEntries) {
+      if (entry.sha256) {
+        _hashAccumulator.addHash(entry.sha256);
+      }
+    }
+    
+    const merkleRoot = _hashAccumulator.merkleRoot();
+    if (!merkleRoot) return null;
+
+    return merkleRoot;
+  }
+
+  /**
+   * Checks if a ZIP file contains valid timestamp metadata
+   * @returns { merkleRoot: string | null, ots: Buffer | null } 
+   * Returns the merkle root hash and timestamp metadata if found, null otherwise
+   */
+  checkForTimestamp(): string | null {
+    const zipEntries = this.getDirectory();
+    if (zipEntries.length === 0) return null;
+
+    this.stampEntry = null;
+    let _hashAccumulator = new HashAccumulater();
+    for (const entry of zipEntries) {
+      if (entry.filename === TIMESTAMP_METADATA) {
+        this.stampEntry = entry;
+      } else if (entry.filename === TIMESTAMP_SUBMITTED) {
+        if (this.stampEntry == null)
+          this.stampEntry = entry;
+      } else if (!this.isMetadataFile(entry.filename) && entry.sha256) {
+        // Only include content files (non-metadata) in Merkle Root calculation
+        _hashAccumulator.addHash(entry.sha256);
+      }
+    }
+    if (!this.stampEntry) return null;
+
+    const merkleRoot = _hashAccumulator.merkleRoot();
+    return merkleRoot;
+  }
+
+  /**
+   * Gets the OTS from the timestamp metadata entry
+   * @returns Promise<Buffer | null> - The OTS from the timestamp metadata entry or null if not found
+   */
+  async getOts(): Promise<Buffer | null> {
+    if (!this.stampEntry) return null;
+    const ots = await this.extract(this.stampEntry);
+    return ots;
+  }
+
+  /**
+   * Creates a new timestamp metadata entry for the ZIP file
+   * Calculates merkle root from file hashes and obtains blockchain timestamp
+   * @returns Promise<ZipEntry | null> The created timestamp metadata entry or null if failed
+   */
+  createTimestampMetadataEntry(ots: Buffer | null): ZipEntry | null {
+    if (!ots) return null;
+    const tsEntry = this.createZipEntry(TIMESTAMP_SUBMITTED);
+    tsEntry.crc = crc32(ots);
+    tsEntry.uncompressedSize = ots.length;
+    tsEntry.compressedSize = ots.length;
+    tsEntry.cmpMethod = CMP_METHOD.STORED;
+    tsEntry.fileBuffer = ots;
+    tsEntry.isMetaData = true;
+
+    return tsEntry;
+  }
+
+  /**
+   * Sets the ZIP file comment
+   * @param msg - Comment to set
+   */
+  setZipComment(msg: string | null) {
+    this.zipComment = msg;
+  }
+  /**
+   * Gets the ZIP file comment
+   * @returns string | null - The ZIP file comment
+   */
+  getZipComment(): string | null {
+    return this.zipComment;
+  }
+
+  /**
+   * Converts the compression method to a string
+   * @param cmpMethod - Compression method number
+   * @returns string - Compression method as a string
+   */
+  cmpMethodToString(cmpMethod: number): string {
+    switch (cmpMethod) {
+      case 0: return 'Stored';
+      case 8: return 'Deflate';
+      case 93: return 'Zstd';
+      default: return 'Unknown';
+    }
+  }
+
+  /**
+   * Ensures ZIP entries are loaded
+   * @returns Array of ZIP entries
+   * @throws Error if no ZIP entries are loaded
+   */
+  private ensureZipEntries(): ZipEntry[] {
+    if (this.zipEntries.length === 0) throw new Error('No ZIP entries loaded');
+    return this.zipEntries;
+  }
+
+  /**
+   * Ensures ZIP data buffer is loaded
+   * @returns Buffer containing ZIP data
+   * @throws Error if no ZIP data is loaded
+   */
+  private ensureBuffer(): Buffer {
+    if (!this.inBuffer) {
+      // Instead of throwing an error, return an empty buffer
+      this.inBuffer = Buffer.alloc(0);
+    }
+    return this.inBuffer;
+  }
+}