zipUtils.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

/**
 * Low-level ZIP structure helpers used by the zipsync pack/unpack pipeline.
 *
 * Spec reference: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
 */

/**
 * Local file header signature PK\x03\x04
 */
const LOCAL_FILE_HEADER_SIGNATURE: number = 0x04034b50; // PK\x03\x04
/**
 * Central directory file header signature PK\x01\x02
 */
const CENTRAL_DIR_HEADER_SIGNATURE: number = 0x02014b50; // PK\x01\x02
/**
 * End of central directory signature PK\x05\x06
 */
const END_OF_CENTRAL_DIR_SIGNATURE: number = 0x06054b50; // PK\x05\x06
/**
 * Data descriptor signature PK\x07\x08
 */
const DATA_DESCRIPTOR_SIGNATURE: number = 0x08074b50; // PK\x07\x08

export const STORE_COMPRESSION: 0 = 0;
export const DEFLATE_COMPRESSION: 8 = 8;
export const ZSTD_COMPRESSION: 93 = 93;
export type ZipMetaCompressionMethod =
  | typeof STORE_COMPRESSION
  | typeof DEFLATE_COMPRESSION
  | typeof ZSTD_COMPRESSION;

export interface IFileEntry {
  filename: string;
  size: number;
  compressedSize: number;
  crc32: number;
  sha1Hash: string;
  localHeaderOffset: number;
  compressionMethod: ZipMetaCompressionMethod;
  dosDateTime: { time: number; date: number };
}

export interface ILocalFileHeader {
  signature: number;
  versionNeeded: number;
  flags: number;
  compressionMethod: number;
  lastModTime: number;
  lastModDate: number;
  crc32: number;
  compressedSize: number;
  uncompressedSize: number;
  filenameLength: number;
  extraFieldLength: number;
}

export interface ICentralDirectoryHeader {
  signature: number;
  versionMadeBy: number;
  versionNeeded: number;
  flags: number;
  compressionMethod: number;
  lastModTime: number;
  lastModDate: number;
  crc32: number;
  compressedSize: number;
  uncompressedSize: number;
  filenameLength: number;
  extraFieldLength: number;
  commentLength: number;
  diskNumberStart: number;
  internalFileAttributes: number;
  externalFileAttributes: number;
  localHeaderOffset: number;
}

export interface IEndOfCentralDirectory {
  signature: number;
  diskNumber: number;
  centralDirStartDisk: number;
  centralDirRecordsOnDisk: number;
  totalCentralDirRecords: number;
  centralDirSize: number;
  centralDirOffset: number;
  commentLength: number;
}

function writeUInt32LE(buffer: Buffer, value: number, offset: number): void {
  buffer.writeUInt32LE(value, offset);
}

function writeUInt16LE(buffer: Buffer, value: number, offset: number): void {
  buffer.writeUInt16LE(value, offset);
}

function readUInt32LE(buffer: Buffer, offset: number): number {
  return buffer.readUInt32LE(offset);
}

function readUInt16LE(buffer: Buffer, offset: number): number {
  return buffer.readUInt16LE(offset);
}

/**
 * Convert a JS Date into packed DOS time/date fields used by classic ZIP.
 * Seconds are stored /2 (range 0-29 => 0-58s). Years are offset from 1980.
 */
export function dosDateTime(date: Date): { time: number; date: number } {
  /* eslint-disable no-bitwise */
  const time: number =
    ((date.getHours() & 0x1f) << 11) | ((date.getMinutes() & 0x3f) << 5) | ((date.getSeconds() / 2) & 0x1f);

  const dateVal: number =
    (((date.getFullYear() - 1980) & 0x7f) << 9) |
    (((date.getMonth() + 1) & 0xf) << 5) |
    (date.getDate() & 0x1f);
  /* eslint-enable no-bitwise */

  return { time, date: dateVal };
}

/**
 * Reusable scratch buffer for the fixed-length local file header (30 bytes).
 * Using a single Buffer avoids per-file allocations; callers must copy/use synchronously.
 */
const localFileHeaderBuffer: Buffer = Buffer.allocUnsafe(30);
/**
 * Write the fixed portion of a local file header for an entry (with data descriptor flag set) and
 * return the header buffer plus the variable-length filename buffer.
 *
 * Layout (little-endian):
 *   signature(4) versionNeeded(2) flags(2) method(2) modTime(2) modDate(2)
 *   crc32(4) compSize(4) uncompSize(4) nameLen(2) extraLen(2)
 *
 * Because we set bit 3 of the general purpose flag, crc32/compSize/uncompSize are zero here and the
 * actual values appear later in a trailing data descriptor record. This enables streaming without
 * buffering entire file contents beforehand.
 */
export function writeLocalFileHeader(
  entry: IFileEntry
): [fileHeaderWithoutVariableLengthData: Buffer, fileHeaderVariableLengthData: Buffer] {
  const filenameBuffer: Buffer = Buffer.from(entry.filename, 'utf8');

  const { time, date } = entry.dosDateTime;

  let offset: number = 0;
  writeUInt32LE(localFileHeaderBuffer, LOCAL_FILE_HEADER_SIGNATURE, offset);
  offset += 4;
  writeUInt16LE(localFileHeaderBuffer, 20, offset); // version needed
  offset += 2;
  // General purpose bit flag: set bit 3 (0x0008) to indicate presence of data descriptor
  // Per APPNOTE: when bit 3 is set, CRC-32 and sizes in local header are set to zero and
  // the actual values are stored in the data descriptor that follows the file data.
  writeUInt16LE(localFileHeaderBuffer, 0x0008, offset); // flags (data descriptor)
  offset += 2;
  writeUInt16LE(localFileHeaderBuffer, entry.compressionMethod, offset); // compression method (0=store,8=deflate)
  offset += 2;
  writeUInt16LE(localFileHeaderBuffer, time, offset); // last mod time
  offset += 2;
  writeUInt16LE(localFileHeaderBuffer, date, offset); // last mod date
  offset += 2;
  // With bit 3 set, these three fields MUST be zero in the local header
  writeUInt32LE(localFileHeaderBuffer, 0, offset); // crc32 (placeholder, real value in data descriptor)
  offset += 4;
  writeUInt32LE(localFileHeaderBuffer, 0, offset); // compressed size (placeholder)
  offset += 4;
  writeUInt32LE(localFileHeaderBuffer, 0, offset); // uncompressed size (placeholder)
  offset += 4;
  writeUInt16LE(localFileHeaderBuffer, filenameBuffer.length, offset); // filename length
  offset += 2;
  writeUInt16LE(localFileHeaderBuffer, 0, offset); // extra field length
  offset += 2;

  return [localFileHeaderBuffer, filenameBuffer];
}

/**
 * Reusable scratch buffer for central directory entries (fixed-length 46 bytes before filename)
 */
const centralDirHeaderBuffer: Buffer = Buffer.allocUnsafe(46);
/**
 * Write a central directory header referencing an already written local file entry.
 * Central directory consolidates the final CRC + sizes (always present here) and provides a table
 * for fast enumeration without scanning the archive sequentially.
 */
export function writeCentralDirectoryHeader(entry: IFileEntry): Buffer[] {
  const filenameBuffer: Buffer = Buffer.from(entry.filename, 'utf8');

  const now: Date = new Date();
  const { time, date } = dosDateTime(now);

  let offset: number = 0;
  writeUInt32LE(centralDirHeaderBuffer, CENTRAL_DIR_HEADER_SIGNATURE, offset);
  offset += 4;
  writeUInt16LE(centralDirHeaderBuffer, 20, offset); // version made by
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, 20, offset); // version needed
  offset += 2;
  // Mirror flags used in local header (bit 3 set to indicate data descriptor was used)
  writeUInt16LE(centralDirHeaderBuffer, 0x0008, offset); // flags
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, entry.compressionMethod, offset); // compression method
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, time, offset); // last mod time
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, date, offset); // last mod date
  offset += 2;
  writeUInt32LE(centralDirHeaderBuffer, entry.crc32, offset); // crc32
  offset += 4;
  writeUInt32LE(centralDirHeaderBuffer, entry.compressedSize, offset); // compressed size
  offset += 4;
  writeUInt32LE(centralDirHeaderBuffer, entry.size, offset); // uncompressed size
  offset += 4;
  writeUInt16LE(centralDirHeaderBuffer, filenameBuffer.length, offset); // filename length
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, 0, offset); // extra field length
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, 0, offset); // comment length
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, 0, offset); // disk number start
  offset += 2;
  writeUInt16LE(centralDirHeaderBuffer, 0, offset); // internal file attributes
  offset += 2;
  writeUInt32LE(centralDirHeaderBuffer, 0, offset); // external file attributes
  offset += 4;
  writeUInt32LE(centralDirHeaderBuffer, entry.localHeaderOffset, offset); // local header offset
  offset += 4;

  return [centralDirHeaderBuffer, filenameBuffer];
}

/**
 * Data descriptor: signature(4) crc32(4) compSize(4) uncompSize(4)
 */
const dataDescriptorBuffer: Buffer = Buffer.allocUnsafe(16);
/**
 * Write the trailing data descriptor for an entry. Only used because we set flag bit 3 in the
 * local file header allowing deferred CRC/size calculation.
 */
export function writeDataDescriptor(entry: IFileEntry): Buffer {
  let offset: number = 0;
  writeUInt32LE(dataDescriptorBuffer, DATA_DESCRIPTOR_SIGNATURE, offset); // signature PK\x07\x08
  offset += 4;
  writeUInt32LE(dataDescriptorBuffer, entry.crc32, offset); // crc32
  offset += 4;
  writeUInt32LE(dataDescriptorBuffer, entry.compressedSize, offset); // compressed size
  offset += 4;
  writeUInt32LE(dataDescriptorBuffer, entry.size, offset); // uncompressed size
  return dataDescriptorBuffer;
}

/**
 * End of central directory (EOCD) record (22 bytes when comment length = 0)
 */
const endOfCentralDirBuffer: Buffer = Buffer.allocUnsafe(22);
/**
 * Write the EOCD record referencing the accumulated central directory. We omit archive comments
 * and do not support ZIP64 (sufficient for build cache archive sizes today).
 */
export function writeEndOfCentralDirectory(
  centralDirOffset: number,
  centralDirSize: number,
  entryCount: number
): Buffer {
  let offset: number = 0;
  writeUInt32LE(endOfCentralDirBuffer, END_OF_CENTRAL_DIR_SIGNATURE, offset);
  offset += 4;
  writeUInt16LE(endOfCentralDirBuffer, 0, offset); // disk number
  offset += 2;
  writeUInt16LE(endOfCentralDirBuffer, 0, offset); // central dir start disk
  offset += 2;
  writeUInt16LE(endOfCentralDirBuffer, entryCount, offset); // central dir records on disk
  offset += 2;
  writeUInt16LE(endOfCentralDirBuffer, entryCount, offset); // total central dir records
  offset += 2;
  writeUInt32LE(endOfCentralDirBuffer, centralDirSize, offset); // central dir size
  offset += 4;
  writeUInt32LE(endOfCentralDirBuffer, centralDirOffset, offset); // central dir offset
  offset += 4;
  writeUInt16LE(endOfCentralDirBuffer, 0, offset); // comment length

  return endOfCentralDirBuffer;
}

interface ILocalFileHeaderParseResult {
  header: ILocalFileHeader;
  nextOffset: number;
}

/**
 * Parse a local file header at the provided offset. Minimal validation: signature check only.
 * Returns header plus the offset pointing just past the variable-length name+extra field.
 */
export function parseLocalFileHeader(buffer: Buffer, offset: number): ILocalFileHeaderParseResult {
  const signature: number = readUInt32LE(buffer, offset);
  if (signature !== LOCAL_FILE_HEADER_SIGNATURE) {
    throw new Error(
      `Unexpected local file header signature at offset ${offset.toString(16)}: ${signature.toString(16)}`
    );
  }
  const header: ILocalFileHeader = {
    signature,
    versionNeeded: readUInt16LE(buffer, offset + 4),
    flags: readUInt16LE(buffer, offset + 6),
    compressionMethod: readUInt16LE(buffer, offset + 8),
    lastModTime: readUInt16LE(buffer, offset + 10),
    lastModDate: readUInt16LE(buffer, offset + 12),
    crc32: readUInt32LE(buffer, offset + 14),
    compressedSize: readUInt32LE(buffer, offset + 18),
    uncompressedSize: readUInt32LE(buffer, offset + 22),
    filenameLength: readUInt16LE(buffer, offset + 26),
    extraFieldLength: readUInt16LE(buffer, offset + 28)
  };

  return {
    header,
    nextOffset: offset + 30 + header.filenameLength + header.extraFieldLength
  };
}

export interface ICentralDirectoryHeaderParseResult {
  header: ICentralDirectoryHeader;
  filename: string;
  nextOffset: number;
}

/**
 * Parse a central directory header at the given offset (within a sliced central directory buffer).
 * Returns header, filename string, and nextOffset pointing to the next structure.
 */
export function parseCentralDirectoryHeader(
  buffer: Buffer,
  offset: number
): ICentralDirectoryHeaderParseResult {
  const signature: number = readUInt32LE(buffer, offset);
  if (signature !== CENTRAL_DIR_HEADER_SIGNATURE) {
    throw new Error(
      `Unexpected central directory signature at offset ${offset.toString(16)}: ${signature.toString(16)}`
    );
  }
  const header: ICentralDirectoryHeader = {
    signature,
    versionMadeBy: readUInt16LE(buffer, offset + 4),
    versionNeeded: readUInt16LE(buffer, offset + 6),
    flags: readUInt16LE(buffer, offset + 8),
    compressionMethod: readUInt16LE(buffer, offset + 10),
    lastModTime: readUInt16LE(buffer, offset + 12),
    lastModDate: readUInt16LE(buffer, offset + 14),
    crc32: readUInt32LE(buffer, offset + 16),
    compressedSize: readUInt32LE(buffer, offset + 20),
    uncompressedSize: readUInt32LE(buffer, offset + 24),
    filenameLength: readUInt16LE(buffer, offset + 28),
    extraFieldLength: readUInt16LE(buffer, offset + 30),
    commentLength: readUInt16LE(buffer, offset + 32),
    diskNumberStart: readUInt16LE(buffer, offset + 34),
    internalFileAttributes: readUInt16LE(buffer, offset + 36),
    externalFileAttributes: readUInt32LE(buffer, offset + 38),
    localHeaderOffset: readUInt32LE(buffer, offset + 42)
  };

  offset += 46;

  const filename: string = buffer.toString('utf8', offset, offset + header.filenameLength);

  return {
    header,
    filename,
    nextOffset: offset + header.filenameLength + header.extraFieldLength + header.commentLength
  };
}

/**
 * Locate the EOCD record by reverse scanning. Since we never write a comment the EOCD will be the
 * first matching signature encountered scanning backwards from the end.
 */
export function findEndOfCentralDirectory(buffer: Buffer): IEndOfCentralDirectory {
  for (let i: number = buffer.length - 22; i >= 0; i--) {
    if (readUInt32LE(buffer, i) === END_OF_CENTRAL_DIR_SIGNATURE) {
      return {
        signature: readUInt32LE(buffer, i),
        diskNumber: readUInt16LE(buffer, i + 4),
        centralDirStartDisk: readUInt16LE(buffer, i + 6),
        centralDirRecordsOnDisk: readUInt16LE(buffer, i + 8),
        totalCentralDirRecords: readUInt16LE(buffer, i + 10),
        centralDirSize: readUInt32LE(buffer, i + 12),
        centralDirOffset: readUInt32LE(buffer, i + 16),
        commentLength: readUInt16LE(buffer, i + 20)
      };
    }
  }

  throw new Error('End of central directory not found');
}

/**
 * Slice out the (possibly compressed) file data bytes for a central directory entry.
 * Caller will decompress if needed based on entry.header.compressionMethod.
 */
export function getFileFromZip(zipBuffer: Buffer, entry: ICentralDirectoryHeaderParseResult): Buffer {
  const { header: localFileHeader } = parseLocalFileHeader(zipBuffer, entry.header.localHeaderOffset);
  const localDataOffset: number =
    entry.header.localHeaderOffset + 30 + localFileHeader.filenameLength + localFileHeader.extraFieldLength;
  const fileZipBuffer: Buffer = zipBuffer.subarray(
    localDataOffset,
    localDataOffset + entry.header.compressedSize
  );
  return fileZipBuffer;
}