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

package/dist/browser/modules/archive/unzip/zip-extract-core.js

@@ -0,0 +1,475 @@
+/**
+ * Core ZIP extraction logic - shared between ZipParser and RemoteZipReader.
+ *
+ * This module provides unified functions for:
+ * - Decrypting entry data (AES and ZipCrypto)
+ * - Decompressing entry data
+ * - Reading local file header
+ * - CRC32 validation
+ *
+ * @module
+ */
+import { decompress, decompressSync } from "../compression/compress.browser.js";
+import { crc32, crc32Finalize, crc32Update } from "../compression/crc32.browser.js";
+import { ZIP_CRYPTO_HEADER_SIZE, aesDecrypt, zipCryptoDecrypt, zipCryptoDecryptByte, zipCryptoInitKeys } from "../crypto/index.js";
+import { BinaryReader } from "../zip-spec/binary.js";
+import { COMPRESSION_DEFLATE, COMPRESSION_STORE, LOCAL_FILE_HEADER_SIG } from "../zip-spec/zip-records.js";
+import { Crc32MismatchError, DecryptionError, EntrySizeMismatchError, PasswordRequiredError, UnsupportedCompressionError, throwIfAborted, toError } from "../shared/errors.js";
+import { createAsyncQueue } from "../shared/async-queue.js";
+import { createInflateStream } from "../compression/streaming-compress.browser.js";
+import { collect } from "../io/archive-sink.js";
+/**
+ * Local file header fixed size (30 bytes)
+ */
+export const LOCAL_HEADER_FIXED_SIZE = 30;
+/**
+ * Process compressed (and possibly encrypted) entry data to get the final content.
+ *
+ * This is the core extraction logic used by both ZipParser and RemoteZipReader.
+ *
+ * @param entry - Entry metadata
+ * @param compressedData - Raw compressed (and possibly encrypted) data from the ZIP
+ * @param password - Optional password for decryption
+ * @param checkCrc32 - Whether to validate CRC32 checksum (default: false)
+ * @param validateEntrySizes - Whether to validate decompressed size matches declared size (default: true)
+ * @returns Decompressed entry content
+ */
+export async function processEntryData(entry, compressedData, password, checkCrc32 = false, validateEntrySizes = true) {
+    let result;
+    // Handle encrypted entries
+    if (entry.isEncrypted) {
+        if (!password) {
+            throw new PasswordRequiredError(entry.path);
+        }
+        if (entry.encryptionMethod === "aes" && entry.aesKeyStrength) {
+            // AES decryption
+            const decrypted = await aesDecrypt(compressedData, password, entry.aesKeyStrength);
+            if (!decrypted) {
+                throw new DecryptionError(entry.path);
+            }
+            // Decompress if needed (use original compression method)
+            result = await decompressData(decrypted, entry.originalCompressionMethod ?? COMPRESSION_STORE, entry.path);
+        }
+        else if (entry.encryptionMethod === "zipcrypto") {
+            // ZipCrypto decryption
+            const decrypted = zipCryptoDecrypt(compressedData, password, entry.crc32, entry.dosTime);
+            if (!decrypted) {
+                throw new DecryptionError(entry.path);
+            }
+            result = await decompressData(decrypted, entry.compressionMethod, entry.path);
+        }
+        else {
+            throw new DecryptionError(entry.path, "Unsupported encryption method");
+        }
+    }
+    else {
+        // Non-encrypted entry
+        result = await decompressData(compressedData, entry.compressionMethod, entry.path);
+    }
+    // Validate entry size (ZIP bomb protection)
+    if (validateEntrySizes && result.length !== entry.uncompressedSize) {
+        const reason = result.length > entry.uncompressedSize ? "too-many-bytes" : "too-few-bytes";
+        throw new EntrySizeMismatchError(entry.path, entry.uncompressedSize, result.length, reason);
+    }
+    // Validate CRC32
+    // Note: AES-encrypted entries don't use CRC32 (they use HMAC instead)
+    // ZipCrypto: Always verify CRC32 because header verification only checks 1 byte
+    // (1/256 false positive rate with wrong password per ZIP spec)
+    const shouldCheckCrc = entry.encryptionMethod === "zipcrypto" || (checkCrc32 && entry.encryptionMethod !== "aes");
+    if (shouldCheckCrc) {
+        const actualCrc = crc32(result);
+        if (actualCrc !== entry.crc32) {
+            throw new Crc32MismatchError(entry.path, entry.crc32, actualCrc);
+        }
+    }
+    return result;
+}
+/**
+ * Process compressed (and possibly encrypted) entry data synchronously.
+ *
+ * Note: AES-encrypted files cannot be processed synchronously because
+ * the Web Crypto API is async. Use processEntryData() instead.
+ *
+ * @param entry - Entry metadata
+ * @param compressedData - Raw compressed (and possibly encrypted) data from the ZIP
+ * @param password - Optional password for decryption
+ * @param validateEntrySizes - Whether to validate decompressed size matches declared size (default: true)
+ * @returns Decompressed entry content
+ * @throws Error if the entry uses AES encryption
+ */
+export function processEntryDataSync(entry, compressedData, password, validateEntrySizes = true) {
+    let result;
+    // Handle encrypted entries
+    if (entry.isEncrypted) {
+        if (!password) {
+            throw new PasswordRequiredError(entry.path);
+        }
+        if (entry.encryptionMethod === "aes") {
+            // AES requires async Web Crypto API
+            throw new Error(`File "${entry.path}" uses AES encryption. Use the async extract() method instead of extractSync().`);
+        }
+        else if (entry.encryptionMethod === "zipcrypto") {
+            // ZipCrypto decryption (synchronous)
+            const decrypted = zipCryptoDecrypt(compressedData, password, entry.crc32, entry.dosTime);
+            if (!decrypted) {
+                throw new DecryptionError(entry.path);
+            }
+            result = decompressDataSync(decrypted, entry.compressionMethod, entry.path);
+            // Always verify CRC32 for ZipCrypto because header verification only checks 1 byte
+            // (1/256 false positive rate with wrong password per ZIP spec)
+            const actualCrc = crc32(result);
+            if (actualCrc !== entry.crc32) {
+                throw new Crc32MismatchError(entry.path, entry.crc32, actualCrc);
+            }
+        }
+        else {
+            throw new DecryptionError(entry.path, "Unsupported encryption method");
+        }
+    }
+    else {
+        // Non-encrypted entry
+        result = decompressDataSync(compressedData, entry.compressionMethod, entry.path);
+    }
+    // Validate entry size (ZIP bomb protection)
+    if (validateEntrySizes && result.length !== entry.uncompressedSize) {
+        const reason = result.length > entry.uncompressedSize ? "too-many-bytes" : "too-few-bytes";
+        throw new EntrySizeMismatchError(entry.path, entry.uncompressedSize, result.length, reason);
+    }
+    return result;
+}
+/**
+ * Decompress data based on compression method (async).
+ */
+async function decompressData(data, compressionMethod, path) {
+    if (compressionMethod === COMPRESSION_STORE) {
+        return data;
+    }
+    if (compressionMethod === COMPRESSION_DEFLATE) {
+        return decompress(data);
+    }
+    throw new UnsupportedCompressionError(compressionMethod);
+}
+async function* decryptZipCryptoStream(entry, encrypted, password, options = {}) {
+    const { signal } = options;
+    const state = zipCryptoInitKeys(password);
+    const header = new Uint8Array(ZIP_CRYPTO_HEADER_SIZE);
+    let headerOffset = 0;
+    let verified = false;
+    for await (const chunk of encrypted) {
+        throwIfAborted(signal);
+        let offset = 0;
+        // Fill and verify header first.
+        if (!verified) {
+            while (headerOffset < ZIP_CRYPTO_HEADER_SIZE && offset < chunk.length) {
+                header[headerOffset++] = chunk[offset++];
+            }
+            if (headerOffset < ZIP_CRYPTO_HEADER_SIZE) {
+                continue;
+            }
+            // Decrypt header in-place and verify check byte.
+            let lastPlain = 0;
+            for (let i = 0; i < ZIP_CRYPTO_HEADER_SIZE; i++) {
+                lastPlain = zipCryptoDecryptByte(state, header[i]);
+            }
+            const crcHighByte = (entry.crc32 >>> 24) & 0xff;
+            const timeHighByte = entry.dosTime !== undefined ? (entry.dosTime >>> 8) & 0xff : -1;
+            if (lastPlain !== crcHighByte && lastPlain !== timeHighByte) {
+                throw new DecryptionError(entry.path);
+            }
+            verified = true;
+        }
+        // Decrypt remaining bytes in this chunk.
+        if (offset < chunk.length) {
+            const out = new Uint8Array(chunk.length - offset);
+            for (let i = 0; i < out.length; i++) {
+                out[i] = zipCryptoDecryptByte(state, chunk[offset + i]);
+            }
+            if (out.length) {
+                yield out;
+            }
+        }
+    }
+    if (!verified) {
+        throw new DecryptionError(entry.path);
+    }
+}
+async function* inflateRawStream(source, options = {}) {
+    const { signal } = options;
+    const inflator = createInflateStream();
+    const queue = createAsyncQueue({
+        onCancel: () => {
+            try {
+                inflator.destroy();
+            }
+            catch {
+                // ignore
+            }
+        }
+    });
+    inflator.on("data", (chunk) => {
+        if (chunk && chunk.length) {
+            queue.push(chunk);
+        }
+    });
+    inflator.on("end", () => {
+        queue.close();
+    });
+    inflator.on("error", (err) => {
+        queue.fail(err);
+    });
+    const producer = (async () => {
+        try {
+            for await (const chunk of source) {
+                throwIfAborted(signal);
+                await new Promise((resolve, reject) => {
+                    inflator.write(chunk, err => {
+                        if (err) {
+                            reject(err);
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                });
+            }
+            throwIfAborted(signal);
+            await new Promise((resolve, reject) => {
+                inflator.end(err => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
+        catch (e) {
+            queue.fail(toError(e));
+            try {
+                inflator.destroy(toError(e));
+            }
+            catch {
+                // ignore
+            }
+        }
+    })();
+    try {
+        for await (const out of queue.iterable) {
+            throwIfAborted(signal);
+            yield out;
+        }
+    }
+    finally {
+        // Ensure producer completion is observed.
+        await producer.catch(() => { });
+        try {
+            inflator.destroy();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/**
+ * Validate that the decompressed data size matches the declared size.
+ * Throws early if too many bytes are produced (ZIP bomb protection).
+ * Throws at the end if too few bytes are produced (corruption detection).
+ */
+async function* validateSizeStream(entry, source, options = {}) {
+    const { signal } = options;
+    const expectedSize = entry.uncompressedSize;
+    let totalBytes = 0;
+    for await (const chunk of source) {
+        throwIfAborted(signal);
+        if (chunk.length) {
+            totalBytes += chunk.length;
+            // Early abort if too many bytes (ZIP bomb protection)
+            if (totalBytes > expectedSize) {
+                throw new EntrySizeMismatchError(entry.path, expectedSize, totalBytes, "too-many-bytes");
+            }
+            yield chunk;
+        }
+    }
+    // Check if too few bytes at the end
+    if (totalBytes < expectedSize) {
+        throw new EntrySizeMismatchError(entry.path, expectedSize, totalBytes, "too-few-bytes");
+    }
+}
+async function* validateCrc32Stream(entry, source, options = {}) {
+    const { signal } = options;
+    let crc = 0xffffffff;
+    for await (const chunk of source) {
+        throwIfAborted(signal);
+        if (chunk.length) {
+            crc = crc32Update(crc, chunk);
+            yield chunk;
+        }
+    }
+    const actual = crc32Finalize(crc);
+    if (actual !== entry.crc32) {
+        throw new Crc32MismatchError(entry.path, entry.crc32, actual);
+    }
+}
+/**
+ * Apply validation streams (size and CRC32) to an output stream.
+ * This centralizes the common pattern of chaining validation streams.
+ */
+function applyValidationStreams(entry, source, options) {
+    const { validateEntrySizes, checkCrc32, signal } = options;
+    let stream = source;
+    // Size validation first (for early abort on ZIP bombs)
+    if (validateEntrySizes) {
+        stream = validateSizeStream(entry, stream, { signal });
+    }
+    // Then CRC32 validation
+    if (checkCrc32) {
+        stream = validateCrc32Stream(entry, stream, { signal });
+    }
+    return stream;
+}
+/**
+ * Process entry data as an async iterable of output chunks.
+ *
+ * This avoids buffering the full output in memory for STORE/DEFLATE entries.
+ *
+ * Note: AES-encrypted entries cannot be truly streamed because HMAC verification
+ * requires the full ciphertext; this function falls back to buffering for AES.
+ */
+export function processEntryDataStream(entry, compressedData, options = {}) {
+    const { password, checkCrc32 = false, validateEntrySizes = true, signal } = options;
+    const run = async function* () {
+        throwIfAborted(signal);
+        if (entry.type === "directory") {
+            return;
+        }
+        // Encrypted cases
+        if (entry.isEncrypted) {
+            if (!password) {
+                throw new PasswordRequiredError(entry.path);
+            }
+            if (entry.encryptionMethod === "aes" && entry.aesKeyStrength) {
+                // AES requires full ciphertext to verify HMAC.
+                const encrypted = await collect(compressedData);
+                const decrypted = await aesDecrypt(encrypted, password, entry.aesKeyStrength);
+                const method = entry.originalCompressionMethod ?? COMPRESSION_STORE;
+                const out = await decompressData(decrypted, method, entry.path);
+                // Validate size for AES entries (already fully buffered)
+                if (validateEntrySizes && out.length !== entry.uncompressedSize) {
+                    const reason = out.length > entry.uncompressedSize ? "too-many-bytes" : "too-few-bytes";
+                    throw new EntrySizeMismatchError(entry.path, entry.uncompressedSize, out.length, reason);
+                }
+                if (out.length) {
+                    yield out;
+                }
+                return;
+            }
+            if (entry.encryptionMethod === "zipcrypto") {
+                const decrypted = decryptZipCryptoStream(entry, compressedData, password, { signal });
+                let outStream;
+                if (entry.compressionMethod === COMPRESSION_STORE) {
+                    outStream = decrypted;
+                }
+                else if (entry.compressionMethod === COMPRESSION_DEFLATE) {
+                    outStream = inflateRawStream(decrypted, { signal });
+                }
+                else {
+                    throw new UnsupportedCompressionError(entry.compressionMethod);
+                }
+                // Apply validation streams - always check CRC32 for ZipCrypto
+                // (header verification only checks 1 byte, 1/256 false positive rate)
+                outStream = applyValidationStreams(entry, outStream, {
+                    validateEntrySizes,
+                    checkCrc32: true,
+                    signal
+                });
+                for await (const chunk of outStream) {
+                    yield chunk;
+                }
+                return;
+            }
+            // Fallback for other encryption methods.
+            const encrypted = await collect(compressedData);
+            // processEntryData already handles size validation internally
+            const out = await processEntryData(entry, encrypted, password, checkCrc32, validateEntrySizes);
+            if (out.length) {
+                yield out;
+            }
+            return;
+        }
+        // Non-encrypted
+        let outStream;
+        if (entry.compressionMethod === COMPRESSION_STORE) {
+            outStream = compressedData;
+        }
+        else if (entry.compressionMethod === COMPRESSION_DEFLATE) {
+            outStream = inflateRawStream(compressedData, { signal });
+        }
+        else {
+            throw new UnsupportedCompressionError(entry.compressionMethod);
+        }
+        // Apply validation streams using centralized helper
+        outStream = applyValidationStreams(entry, outStream, {
+            validateEntrySizes,
+            checkCrc32,
+            signal
+        });
+        for await (const chunk of outStream) {
+            yield chunk;
+        }
+    };
+    return run();
+}
+/**
+ * Decompress data based on compression method (sync).
+ */
+function decompressDataSync(data, compressionMethod, path) {
+    if (compressionMethod === COMPRESSION_STORE) {
+        return data;
+    }
+    if (compressionMethod === COMPRESSION_DEFLATE) {
+        return decompressSync(data);
+    }
+    throw new UnsupportedCompressionError(compressionMethod);
+}
+/**
+ * Read the data offset from a local file header.
+ *
+ * The data offset is the position after the local file header where
+ * the actual compressed data begins.
+ *
+ * @param reader - Binary reader positioned at the local file header
+ * @param expectedOffset - Expected offset (for error messages)
+ * @returns Offset where the compressed data starts
+ */
+export function readLocalHeaderDataOffset(reader, expectedOffset) {
+    const sig = reader.readUint32();
+    if (sig !== LOCAL_FILE_HEADER_SIG) {
+        throw new Error(`Invalid local file header signature at offset ${expectedOffset}`);
+    }
+    reader.skip(2); // version needed
+    reader.skip(2); // flags
+    reader.skip(2); // compression method
+    reader.skip(2); // last mod time
+    reader.skip(2); // last mod date
+    reader.skip(4); // crc32
+    reader.skip(4); // compressed size
+    reader.skip(4); // uncompressed size
+    const fileNameLength = reader.readUint16();
+    const extraFieldLength = reader.readUint16();
+    reader.skip(fileNameLength);
+    reader.skip(extraFieldLength);
+    return reader.position;
+}
+/**
+ * Read compressed data for an entry from a buffer.
+ *
+ * @param data - Full ZIP buffer
+ * @param entry - Entry to read
+ * @returns Compressed data for the entry
+ */
+export function readEntryCompressedData(data, entry) {
+    const reader = new BinaryReader(data, entry.localHeaderOffset);
+    const dataOffset = readLocalHeaderDataOffset(reader, entry.localHeaderOffset);
+    return data.subarray(dataOffset, dataOffset + entry.compressedSize);
+}

package/dist/browser/modules/archive/unzip/zip-parser.d.ts

@@ -3,7 +3,8 @@
  * Works in both Node.js and browser environments
  * No dependency on Node.js stream module
  */
-import type { ZipEntryInfo } from "@archive/zip-spec/zip-entry-info";
+import type { ZipEntryInfo } from "../zip-spec/zip-entry-info.js";
+import type { ZipStringEncoding } from "../shared/text.js";
 export type { ZipEntryInfo };
 /**
  * ZIP parsing options
@@ -11,6 +12,17 @@ export type { ZipEntryInfo };
 export interface ZipParseOptions {
     /** Whether to decode file names as UTF-8 (default: true) */
     decodeStrings?: boolean;
+    /** Optional string encoding for legacy (non-UTF8) names/comments. */
+    encoding?: ZipStringEncoding;
+    /** Password for encrypted entries */
+    password?: string | Uint8Array;
+}
+/**
+ * Extraction options with optional password support.
+ */
+export interface ExtractOptions {
+    /** Password for encrypted entries */
+    password?: string | Uint8Array;
 }
 /**
  * High-level ZIP parser class
@@ -19,7 +31,13 @@ export declare class ZipParser {
     private data;
     private entries;
     private entryMap;
+    private password?;
+    private archiveComment;
     constructor(data: Uint8Array | ArrayBuffer, options?: ZipParseOptions);
+    /**
+     * Set the password for encrypted entries.
+     */
+    setPassword(password: string | Uint8Array | undefined): void;
     /**
      * Get all entries in the ZIP file
      */
@@ -28,35 +46,87 @@ export declare class ZipParser {
      * Get entry by path
      */
     getEntry(path: string): ZipEntryInfo | undefined;
+    /**
+     * Get a zero-copy view of the raw (compressed) entry payload.
+     *
+     * Notes:
+     * - This returns the bytes as stored in the ZIP (compressed and possibly encrypted).
+     * - The returned Uint8Array is a view into the original ZIP buffer.
+     * - This does NOT include the local file header, extra field, or data descriptor.
+     */
+    getRawCompressedData(path: string): Uint8Array | null;
+    /**
+     * Get raw (compressed) payload together with its parsed entry info.
+     */
+    getRawEntry(path: string): {
+        info: ZipEntryInfo;
+        compressedData: Uint8Array;
+    } | null;
     /**
      * Check if entry exists
      */
     hasEntry(path: string): boolean;
+    /**
+     * Get the number of child entries in a directory.
+     *
+     * Returns the count of entries whose paths start with the directory prefix,
+     * excluding the directory entry itself. For non-directory entries, returns 0.
+     *
+     * @param path - Directory path (with or without trailing slash)
+     * @returns Number of child entries
+     */
+    childCount(path: string): number;
+    /**
+     * Get the archive comment.
+     */
+    getZipComment(): string;
+    /**
+     * Check if the archive contains encrypted entries
+     */
+    hasEncryptedEntries(): boolean;
+    /**
+     * Get all encrypted entries
+     */
+    getEncryptedEntries(): ZipEntryInfo[];
     /**
      * List all file paths
      */
     listFiles(): string[];
     /**
      * Extract a single file (async)
+     * @param path - File path within the archive
+     * @param password - Optional password for this entry (overrides constructor password)
      */
-    extract(path: string): Promise<Uint8Array | null>;
+    extract(path: string, password?: string | Uint8Array): Promise<Uint8Array | null>;
     /**
      * Extract a single file (sync)
      *
-     * This is supported in both Node.js and browser builds.
+     * Note: AES-encrypted files cannot be extracted synchronously.
+     * Use the async extract() method for AES-encrypted files.
+     *
+     * @param path - File path within the archive
+     * @param password - Optional password for this entry (overrides constructor password)
      */
-    extractSync(path: string): Uint8Array | null;
+    extractSync(path: string, password?: string | Uint8Array): Uint8Array | null;
     /**
      * Extract all files (async)
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    extractAll(): Promise<Map<string, Uint8Array>>;
+    extractAll(password?: string | Uint8Array): Promise<Map<string, Uint8Array>>;
     /**
      * Extract all files (sync)
      * Returns object with file paths as keys and Uint8Array content as values
+     *
+     * Note: AES-encrypted files cannot be extracted synchronously.
+     * Use the async extractAll() method if the archive contains AES-encrypted files.
+     *
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    extractAllSync(): Record<string, Uint8Array>;
+    extractAllSync(password?: string | Uint8Array): Record<string, Uint8Array>;
     /**
      * Iterate over entries with async callback
+     * @param callback - Callback for each entry
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    forEach(callback: (entry: ZipEntryInfo, getData: () => Promise<Uint8Array>) => Promise<boolean | void>): Promise<void>;
+    forEach(callback: (entry: ZipEntryInfo, getData: () => Promise<Uint8Array>) => Promise<boolean | void>, password?: string | Uint8Array): Promise<void>;
 }