@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/archive/zip-spec/zip-parser-core.js

@@ -0,0 +1,361 @@
+/**
+ * Shared ZIP parsing primitives.
+ *
+ * This module contains pure functions for parsing EOCD, ZIP64 EOCD, and Central Directory.
+ * Used by both `ZipParser` (in-memory) and `RemoteZipReader` (random-access).
+ */
+import { BinaryReader } from "./binary.js";
+import { parseZipExtraFields } from "./zip-extra-fields.js";
+import { resolveZipLastModifiedDateFromUnixSeconds } from "./timestamps.js";
+import { decodeZipPath, decodeZipComment, resolveZipStringCodec } from "../shared/text.js";
+import { uint8ArrayToString as decodeUtf8 } from "../../../utils/binary.js";
+import { CENTRAL_DIR_HEADER_SIG, COMPRESSION_AES, UINT16_MAX, UINT32_MAX, ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG, ZIP64_END_OF_CENTRAL_DIR_SIG, ZIP_OS_MSDOS, getUnixModeFromExternalAttributes, isSymlinkMode, isDirectoryMode } from "./zip-records.js";
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/** Minimum EOCD size (22 bytes fixed + 0-byte comment) */
+export const EOCD_MIN_SIZE = 22;
+/** Maximum comment size (2^16 - 1) */
+export const EOCD_MAX_COMMENT_SIZE = 65535;
+/** Maximum bytes to search for EOCD signature */
+export const EOCD_MAX_SEARCH_SIZE = EOCD_MIN_SIZE + EOCD_MAX_COMMENT_SIZE;
+/** ZIP64 EOCD Locator size */
+export const ZIP64_EOCD_LOCATOR_SIZE = 20;
+function resolveDecoder(options) {
+    return options.encoding ? resolveZipStringCodec(options.encoding) : undefined;
+}
+// -----------------------------------------------------------------------------
+// EOCD Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Find EOCD signature by searching backwards in a buffer.
+ *
+ * @param data - Buffer to search (should be the tail of the ZIP file)
+ * @param validate - If true, validates the EOCD by checking comment length matches remaining bytes
+ * @returns Offset within the buffer, or -1 if not found
+ */
+export function findEOCDSignature(data, validate = false) {
+    // Signature bytes (little-endian): 0x06054b50 -> 50 4b 05 06
+    const b0 = 0x50;
+    const b1 = 0x4b;
+    const b2 = 0x05;
+    const b3 = 0x06;
+    for (let i = data.length - EOCD_MIN_SIZE; i >= 0; i--) {
+        if (data[i] === b0 && data[i + 1] === b1 && data[i + 2] === b2 && data[i + 3] === b3) {
+            if (validate) {
+                // Verify by checking comment length
+                const commentLen = data[i + 20] | (data[i + 21] << 8);
+                const expectedEnd = i + EOCD_MIN_SIZE + commentLen;
+                if (expectedEnd === data.length) {
+                    return i;
+                }
+            }
+            else {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Find ZIP64 EOCD Locator signature.
+ *
+ * @param data - Buffer containing the locator (should be 20 bytes before EOCD)
+ * @param eocdOffset - Offset of EOCD within the buffer
+ * @returns Offset within the buffer, or -1 if not found
+ */
+export function findZIP64EOCDLocator(data, eocdOffset) {
+    const locatorOffset = eocdOffset - ZIP64_EOCD_LOCATOR_SIZE;
+    if (locatorOffset < 0) {
+        return -1;
+    }
+    // Signature bytes (little-endian): 0x07064b50 -> 50 4b 06 07
+    if (data[locatorOffset] === 0x50 &&
+        data[locatorOffset + 1] === 0x4b &&
+        data[locatorOffset + 2] === 0x06 &&
+        data[locatorOffset + 3] === 0x07) {
+        return locatorOffset;
+    }
+    return -1;
+}
+/**
+ * Parse EOCD from a buffer at the given offset.
+ *
+ * @param data - Buffer containing EOCD
+ * @param offset - Offset of EOCD within the buffer
+ * @param decodeStrings - Whether to decode the comment as UTF-8
+ * @returns Parsed EOCD info and comment
+ */
+export function parseEOCD(data, offset, decodeStrings = true, decoder) {
+    const reader = new BinaryReader(data, offset);
+    reader.skip(4); // signature
+    const diskNumber = reader.readUint16();
+    const centralDirDisk = reader.readUint16();
+    const entriesOnDisk = reader.readUint16();
+    const totalEntries = reader.readUint16();
+    const centralDirSize = reader.readUint32();
+    const centralDirOffset = reader.readUint32();
+    const commentLength = reader.readUint16();
+    let comment = "";
+    if (commentLength > 0) {
+        const commentBytes = reader.readBytes(commentLength);
+        if (decodeStrings) {
+            comment = decoder ? decoder.decode(commentBytes) : decodeUtf8(commentBytes);
+        }
+    }
+    return {
+        eocd: {
+            diskNumber,
+            centralDirDisk,
+            entriesOnDisk,
+            totalEntries,
+            centralDirSize,
+            centralDirOffset
+        },
+        comment
+    };
+}
+/**
+ * Parse ZIP64 EOCD Locator and return the offset of ZIP64 EOCD.
+ *
+ * @param data - Buffer containing the locator
+ * @param offset - Offset of locator within the buffer
+ * @returns ZIP64 EOCD file offset, or -1 if invalid
+ */
+export function parseZIP64EOCDLocator(data, offset) {
+    const reader = new BinaryReader(data, offset);
+    const sig = reader.readUint32();
+    if (sig !== ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG) {
+        return -1;
+    }
+    reader.skip(4); // disk number with ZIP64 EOCD
+    return Number(reader.readBigUint64());
+}
+/**
+ * Parse ZIP64 EOCD.
+ *
+ * @param data - Buffer containing ZIP64 EOCD
+ * @param offset - Offset within the buffer
+ * @returns Parsed ZIP64 EOCD info, or null if invalid signature
+ */
+export function parseZIP64EOCD(data, offset) {
+    const reader = new BinaryReader(data, offset);
+    const sig = reader.readUint32();
+    if (sig !== ZIP64_END_OF_CENTRAL_DIR_SIG) {
+        return null;
+    }
+    reader.skip(8); // size of ZIP64 EOCD record
+    reader.skip(2); // version made by
+    reader.skip(2); // version needed
+    reader.skip(4); // disk number
+    reader.skip(4); // disk with central dir
+    const entriesOnDisk = reader.readBigUint64();
+    const totalEntries = reader.readBigUint64();
+    const centralDirSize = reader.readBigUint64();
+    const centralDirOffset = reader.readBigUint64();
+    return {
+        entriesOnDisk,
+        totalEntries,
+        centralDirSize,
+        centralDirOffset
+    };
+}
+/**
+ * Apply ZIP64 values to EOCD if standard values are maxed out.
+ *
+ * Mutates the provided `eocd` object.
+ */
+export function applyZIP64ToEOCD(eocd, zip64) {
+    if (eocd.totalEntries === UINT16_MAX) {
+        eocd.totalEntries = Number(zip64.totalEntries);
+    }
+    if (eocd.entriesOnDisk === UINT16_MAX) {
+        eocd.entriesOnDisk = Number(zip64.entriesOnDisk);
+    }
+    if (eocd.centralDirSize === UINT32_MAX) {
+        eocd.centralDirSize = Number(zip64.centralDirSize);
+    }
+    if (eocd.centralDirOffset === UINT32_MAX) {
+        eocd.centralDirOffset = Number(zip64.centralDirOffset);
+    }
+}
+// -----------------------------------------------------------------------------
+// Central Directory Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Parse a single Central Directory entry from a BinaryReader.
+ *
+ * The reader should be positioned at the start of the entry (after signature validation).
+ * After this call, the reader is positioned at the next entry (or end of CD).
+ *
+ * @param reader - BinaryReader positioned after the CD header signature
+ * @param decodeStrings - Whether to decode strings as UTF-8
+ * @returns Parsed entry info
+ */
+export function parseCentralDirectoryEntry(reader, decodeStrings, decoder) {
+    const versionMadeBy = reader.readUint16();
+    reader.skip(2); // version needed
+    const flags = reader.readUint16();
+    const compressionMethod = reader.readUint16();
+    const lastModTime = reader.readUint16();
+    const lastModDate = reader.readUint16();
+    const crc32Value = reader.readUint32();
+    let compressedSize = reader.readUint32();
+    let uncompressedSize = reader.readUint32();
+    const fileNameLength = reader.readUint16();
+    const extraFieldLength = reader.readUint16();
+    const commentLength = reader.readUint16();
+    reader.skip(2); // disk number start
+    reader.skip(2); // internal attributes
+    const externalAttributes = reader.readUint32();
+    let localHeaderOffset = reader.readUint32();
+    // Read raw bytes first, we need them for CRC32 verification in Unicode extra fields
+    const fileNameBytes = fileNameLength > 0 ? reader.readBytes(fileNameLength) : new Uint8Array(0);
+    let extraFields = {};
+    let rawExtraField = new Uint8Array(0);
+    if (extraFieldLength > 0) {
+        rawExtraField = reader.readBytes(extraFieldLength);
+        const vars = {
+            compressedSize,
+            uncompressedSize,
+            offsetToLocalFileHeader: localHeaderOffset
+        };
+        extraFields = parseZipExtraFields(rawExtraField, vars);
+        compressedSize = vars.compressedSize;
+        uncompressedSize = vars.uncompressedSize;
+        localHeaderOffset = vars.offsetToLocalFileHeader ?? localHeaderOffset;
+    }
+    const commentBytes = commentLength > 0 ? reader.readBytes(commentLength) : new Uint8Array(0);
+    // Decode fileName and comment using unified decoder
+    // Handles: UTF-8 flag, Unicode extra fields (0x7075/0x6375), CP437 fallback
+    const fileName = decodeStrings ? decodeZipPath(fileNameBytes, flags, extraFields, decoder) : "";
+    const comment = decodeStrings ? decodeZipComment(commentBytes, flags, extraFields, decoder) : "";
+    // Extract Unix mode from external attributes
+    const mode = getUnixModeFromExternalAttributes(externalAttributes);
+    const madeByOs = (versionMadeBy >> 8) & 0xff;
+    // Determine entry type using helper functions
+    const isSymlink = isSymlinkMode(mode);
+    const isDirectory = isDirectoryMode(mode) ||
+        (madeByOs === ZIP_OS_MSDOS && (externalAttributes & 0x10) !== 0) ||
+        fileName.endsWith("/");
+    const isEncrypted = (flags & 0x01) !== 0;
+    // Map to ZipEntryType
+    const type = isSymlink ? "symlink" : isDirectory ? "directory" : "file";
+    const unixSecondsMtime = extraFields.mtimeUnixSeconds;
+    const lastModified = resolveZipLastModifiedDateFromUnixSeconds(lastModDate, lastModTime, unixSecondsMtime);
+    // Determine encryption method
+    let encryptionMethod = "none";
+    let aesVersion;
+    let aesKeyStrength;
+    let originalCompressionMethod;
+    if (isEncrypted) {
+        if (compressionMethod === COMPRESSION_AES && extraFields.aesInfo) {
+            encryptionMethod = "aes";
+            aesVersion = extraFields.aesInfo.version;
+            aesKeyStrength = extraFields.aesInfo.keyStrength;
+            originalCompressionMethod = extraFields.aesInfo.compressionMethod;
+        }
+        else {
+            encryptionMethod = "zipcrypto";
+        }
+    }
+    return {
+        path: fileName,
+        type,
+        compressedSize,
+        compressedSize64: extraFields.compressedSize64,
+        uncompressedSize,
+        uncompressedSize64: extraFields.uncompressedSize64,
+        compressionMethod,
+        crc32: crc32Value,
+        lastModified,
+        localHeaderOffset,
+        localHeaderOffset64: extraFields.offsetToLocalFileHeader64,
+        comment,
+        externalAttributes,
+        mode,
+        versionMadeBy,
+        extraField: rawExtraField,
+        isEncrypted,
+        encryptionMethod,
+        aesVersion,
+        aesKeyStrength,
+        originalCompressionMethod,
+        dosTime: lastModTime
+    };
+}
+/**
+ * Parse all Central Directory entries from a buffer.
+ *
+ * @param data - Buffer containing the entire Central Directory
+ * @param totalEntries - Expected number of entries
+ * @param options - Parse options
+ * @returns Array of parsed entries
+ */
+export function parseCentralDirectory(data, totalEntries, options = {}) {
+    return parseCentralDirectoryAt(data, 0, totalEntries, options);
+}
+/**
+ * Parse all Central Directory entries from a buffer starting at a specific offset.
+ *
+ * @param data - Buffer containing the Central Directory
+ * @param offset - Offset within the buffer where CD starts
+ * @param totalEntries - Expected number of entries
+ * @param options - Parse options
+ * @returns Array of parsed entries
+ */
+export function parseCentralDirectoryAt(data, offset, totalEntries, options = {}) {
+    const decodeStrings = options.decodeStrings ?? true;
+    const decoder = resolveDecoder(options);
+    if (totalEntries === 0) {
+        return [];
+    }
+    const entries = new Array(totalEntries);
+    const reader = new BinaryReader(data, offset);
+    for (let i = 0; i < totalEntries; i++) {
+        const sig = reader.readUint32();
+        if (sig !== CENTRAL_DIR_HEADER_SIG) {
+            throw new Error(`Invalid Central Directory header signature at entry ${i}`);
+        }
+        entries[i] = parseCentralDirectoryEntry(reader, decodeStrings, decoder);
+    }
+    return entries;
+}
+// -----------------------------------------------------------------------------
+// Combined In-Memory Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Parse a complete ZIP archive from an in-memory buffer.
+ *
+ * This is a convenience function that handles EOCD + ZIP64 + Central Directory parsing.
+ *
+ * @param data - Complete ZIP file buffer
+ * @param options - Parse options
+ * @returns Parsed entries and archive comment
+ */
+export function parseZipArchiveFromBuffer(data, options = {}) {
+    const decodeStrings = options.decodeStrings ?? true;
+    const decoder = resolveDecoder(options);
+    // Find EOCD
+    const eocdOffset = findEOCDSignature(data);
+    if (eocdOffset === -1) {
+        throw new Error("Invalid ZIP file: End of Central Directory not found");
+    }
+    // Parse EOCD
+    const { eocd, comment } = parseEOCD(data, eocdOffset, decodeStrings, decoder);
+    // Check for ZIP64
+    const zip64LocatorOffset = findZIP64EOCDLocator(data, eocdOffset);
+    if (zip64LocatorOffset !== -1) {
+        const zip64EocdOffset = parseZIP64EOCDLocator(data, zip64LocatorOffset);
+        if (zip64EocdOffset >= 0) {
+            const zip64Eocd = parseZIP64EOCD(data, zip64EocdOffset);
+            if (zip64Eocd) {
+                applyZIP64ToEOCD(eocd, zip64Eocd);
+            }
+        }
+    }
+    // Parse Central Directory - use offset directly, not subarray
+    // This allows reading from a larger buffer without needing exact sizing
+    const entries = parseCentralDirectoryAt(data, eocd.centralDirOffset, eocd.totalEntries, options);
+    return { entries, comment };
+}

package/dist/browser/modules/archive/zip-spec/zip-path.d.ts

@@ -0,0 +1,15 @@
+export type ZipPathMode = "legacy" | "posix" | "safe";
+export interface ZipPathOptions {
+    /**
+     * - "legacy": replace backslashes with '/', strip leading '/'
+     * - "posix": also normalizes '.' and '..' segments using POSIX rules
+     * - "safe": like "posix" but rejects absolute paths and any remaining '..' traversal
+     */
+    mode?: ZipPathMode;
+    /** If true, ensures a single leading '/'. */
+    prependSlash?: boolean;
+    /** If true, strips a Windows drive prefix like `C:`. Default: true for posix/safe. */
+    stripDrive?: boolean;
+}
+export declare function normalizeZipPath(pathName: string, options?: ZipPathOptions): string;
+export declare function joinZipPath(options: ZipPathOptions, ...parts: string[]): string;

package/dist/browser/modules/archive/zip-spec/zip-path.js

@@ -0,0 +1,87 @@
+function replaceBackslashes(p) {
+    return p.replace(/\\/g, "/");
+}
+function stripLeadingSlashes(p) {
+    return p.replace(/^\/+/, "");
+}
+function stripWindowsDrive(p) {
+    // C:/path or C:path
+    return p.replace(/^[a-zA-Z]:\/?/, "");
+}
+function normalizePosix(p) {
+    const parts = p.split("/");
+    const out = [];
+    for (const part of parts) {
+        if (!part || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            if (out.length > 0) {
+                out.pop();
+            }
+            else {
+                // Preserve leading '..' to be handled by caller (safe mode may reject).
+                out.push("..");
+            }
+            continue;
+        }
+        out.push(part);
+    }
+    return out.join("/");
+}
+function isAbsoluteZipPath(p) {
+    // Backslashes are normalized earlier, so this only needs to check '/'.
+    return p.startsWith("/");
+}
+function hasWindowsDrivePrefix(p) {
+    // C:/path or C:path
+    return /^[a-zA-Z]:/.test(p);
+}
+export function normalizeZipPath(pathName, options = {}) {
+    const mode = options.mode ?? "legacy";
+    let p = pathName;
+    p = replaceBackslashes(p);
+    const hadWindowsDrive = hasWindowsDrivePrefix(p);
+    if (mode === "legacy") {
+        p = stripLeadingSlashes(p);
+        return options.prependSlash ? "/" + p : p;
+    }
+    const stripDrive = options.stripDrive ?? true;
+    if (mode === "safe" && hadWindowsDrive && !stripDrive) {
+        throw new Error(`Unsafe ZIP path (drive): ${pathName}`);
+    }
+    if (stripDrive) {
+        p = stripWindowsDrive(p);
+    }
+    const hadLeadingSlash = isAbsoluteZipPath(p);
+    p = stripLeadingSlashes(p);
+    p = normalizePosix(p);
+    if (mode === "safe") {
+        if (hadLeadingSlash) {
+            throw new Error(`Unsafe ZIP path (absolute): ${pathName}`);
+        }
+        if (p === ".." || p.startsWith("../")) {
+            throw new Error(`Unsafe ZIP path (traversal): ${pathName}`);
+        }
+    }
+    if (options.prependSlash) {
+        return "/" + p;
+    }
+    return p;
+}
+export function joinZipPath(options, ...parts) {
+    const normalizeOptions = { ...options, prependSlash: false };
+    const normalized = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!part) {
+            continue;
+        }
+        const next = normalizeZipPath(part, normalizeOptions);
+        if (next) {
+            normalized.push(next);
+        }
+    }
+    const joined = normalized.join("/");
+    return options.prependSlash ? "/" + stripLeadingSlashes(joined) : joined;
+}

package/dist/browser/modules/archive/zip-spec/zip-records.d.ts

@@ -3,6 +3,14 @@
  *
  * Shared by streaming zip writer and buffer zip builder.
  */
+/**
+ * Shared ZIP64 mode type.
+ *
+ * - "auto": write ZIP64 only when required by ZIP limits.
+ * - true: force ZIP64 structures.
+ * - false: forbid ZIP64; throw if required.
+ */
+export type Zip64Mode = boolean | "auto";
 export declare const LOCAL_FILE_HEADER_SIG = 67324752;
 export declare const CENTRAL_DIR_HEADER_SIG = 33639248;
 export declare const END_OF_CENTRAL_DIR_SIG = 101010256;
@@ -11,15 +19,50 @@ export declare const ZIP64_END_OF_CENTRAL_DIR_SIG = 101075792;
 export declare const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG = 117853008;
 export declare const VERSION_NEEDED = 20;
 export declare const VERSION_MADE_BY = 20;
+export declare const VERSION_ZIP64 = 45;
 export declare const COMPRESSION_STORE = 0;
 export declare const COMPRESSION_DEFLATE = 8;
+export declare const COMPRESSION_AES = 99;
+export declare const FLAG_ENCRYPTED = 1;
 export declare const FLAG_UTF8 = 2048;
 export declare const FLAG_DATA_DESCRIPTOR = 8;
+/** Unix file type mask */
+export declare const S_IFMT = 61440;
+/** Unix symbolic link type */
+export declare const S_IFLNK = 40960;
+/** Unix directory type */
+export declare const S_IFDIR = 16384;
+/** Unix regular file type */
+export declare const S_IFREG = 32768;
+/** MS-DOS / Windows OS code */
+export declare const ZIP_OS_MSDOS = 0;
+/** Unix OS code */
+export declare const ZIP_OS_UNIX = 3;
+/**
+ * Extract Unix mode from ZIP external attributes.
+ * Returns 0 if no Unix mode information is available.
+ */
+export declare function getUnixModeFromExternalAttributes(externalAttributes: number): number;
+/**
+ * Get the OS code from versionMadeBy field.
+ */
+export declare function getOsFromVersionMadeBy(versionMadeBy: number | undefined): number;
+/**
+ * Check if Unix mode indicates a symbolic link.
+ */
+export declare function isSymlinkMode(mode: number): boolean;
+/**
+ * Check if Unix mode indicates a directory.
+ */
+export declare function isDirectoryMode(mode: number): boolean;
 export declare const UINT16_MAX = 65535;
 export declare const UINT32_MAX = 4294967295;
 export declare const ZIP_LOCAL_FILE_HEADER_FIXED_SIZE = 30;
 export declare const ZIP_CENTRAL_DIR_HEADER_FIXED_SIZE = 46;
 export declare const ZIP_END_OF_CENTRAL_DIR_FIXED_SIZE = 22;
+export declare const ZIP64_END_OF_CENTRAL_DIR_FIXED_SIZE = 56;
+export declare const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_FIXED_SIZE = 20;
+export declare const ZIP64_EXTRA_FIELD_ID = 1;
 export interface ZipLocalFileHeaderInput {
     fileName: Uint8Array;
     extraField: Uint8Array;
@@ -61,3 +104,30 @@ export interface ZipEndOfCentralDirectoryInput {
 export declare function writeEndOfCentralDirectoryInto(out: Uint8Array, view: DataView, offset: number, input: ZipEndOfCentralDirectoryInput): number;
 export declare function buildEndOfCentralDirectory(input: ZipEndOfCentralDirectoryInput): Uint8Array;
 export declare function buildDataDescriptor(crc32: number, compressedSize: number, uncompressedSize: number): Uint8Array<ArrayBuffer>;
+export declare function buildDataDescriptorZip64(crc32: number, compressedSize: number, uncompressedSize: number): Uint8Array;
+export declare function buildZip64ExtraField(input: {
+    uncompressedSize?: number;
+    compressedSize?: number;
+    localHeaderOffset?: number;
+    diskNumberStart?: number;
+}): Uint8Array;
+export declare function concatExtraFields(a: Uint8Array, b: Uint8Array): Uint8Array;
+export interface Zip64EndOfCentralDirectoryInput {
+    versionMadeBy?: number;
+    versionNeeded?: number;
+    diskNumber?: number;
+    centralDirectoryDiskNumber?: number;
+    entryCountOnDisk: number;
+    entryCountTotal: number;
+    centralDirSize: number;
+    centralDirOffset: number;
+}
+export declare function writeZip64EndOfCentralDirectoryInto(out: Uint8Array, view: DataView, offset: number, input: Zip64EndOfCentralDirectoryInput): number;
+export declare function buildZip64EndOfCentralDirectory(input: Zip64EndOfCentralDirectoryInput): Uint8Array;
+export interface Zip64EndOfCentralDirectoryLocatorInput {
+    zip64EndOfCentralDirectoryDiskNumber?: number;
+    zip64EndOfCentralDirectoryOffset: number;
+    totalDisks?: number;
+}
+export declare function writeZip64EndOfCentralDirectoryLocatorInto(out: Uint8Array, view: DataView, offset: number, input: Zip64EndOfCentralDirectoryLocatorInput): number;
+export declare function buildZip64EndOfCentralDirectoryLocator(input: Zip64EndOfCentralDirectoryLocatorInput): Uint8Array;