docxmlater 11.0.10 → 12.0.1

package/src/zip/ZipReader.ts

@@ -4,12 +4,13 @@
 
 import JSZip from 'jszip';
 import { promises as fs } from 'fs';
-import { ZipFile, FileMap, LoadOptions } from './types.js';
+import { ZipFile, FileMap, LoadOptions, SizeLimitOptions, DEFAULT_SIZE_LIMITS } from './types.js';
 import {
   DocxNotFoundError,
   InvalidDocxError,
   CorruptedArchiveError,
   FileOperationError,
+  ResourceLimitError,
 } from './errors.js';
 import {
   validateDocxStructure,
@@ -18,6 +19,25 @@ import {
   isValidZipBuffer,
 } from '../utils/validation.js';
 
+/**
+ * Shape of JSZip's undocumented per-entry `_data` field, consulted only as an
+ * early-reject hint — never as the authoritative size guard (measured decompressed
+ * bytes are). Mirrors the commented-out `CompressedObject` interface in jszip's own
+ * `node_modules/jszip/index.d.ts`.
+ *
+ * [TS-5] Verified against jszip 3.10.x (package.json range `^3.10.1`). A minor jszip
+ * bump could rename or remove this field; if so the early-reject/ratio hints silently
+ * degrade to no-ops while the measured-byte accounting in {@link extractFiles} keeps
+ * enforcing the budgets. `tests/zip/JSZipInternalContract.test.ts` canaries the field
+ * so such a regression surfaces on upgrade.
+ */
+interface JSZipObjectPrivate {
+  _data?: {
+    compressedSize?: number;
+    uncompressedSize?: number;
+  };
+}
+
 /**
  * Handles reading operations on ZIP archives
  */
@@ -44,7 +64,14 @@ export class ZipReader {
       const buffer = await fs.readFile(filePath);
       await this.loadFromBuffer(buffer, options);
     } catch (error: unknown) {
-      if (error instanceof DocxNotFoundError) {
+      // Surface load-classification errors verbatim so callers can distinguish a
+      // missing/oversized/hostile archive from a generic read failure.
+      if (
+        error instanceof DocxNotFoundError ||
+        error instanceof ResourceLimitError ||
+        error instanceof InvalidDocxError ||
+        error instanceof CorruptedArchiveError
+      ) {
         throw error;
       }
       const message = error instanceof Error ? error.message : String(error);
@@ -59,6 +86,7 @@ export class ZipReader {
    */
   async loadFromBuffer(buffer: Buffer, options: LoadOptions = {}): Promise<void> {
     const { validate = true } = options;
+    const limits: Required<SizeLimitOptions> = { ...DEFAULT_SIZE_LIMITS, ...options.sizeLimits };
 
     try {
       // Validate ZIP signature
@@ -69,8 +97,19 @@ export class ZipReader {
       // Load ZIP archive
       this.zip = await JSZip.loadAsync(buffer);
 
-      // Extract all files
-      await this.extractFiles();
+      // Enumerate non-directory entries once; reused for the count guard below and
+      // for extraction, so the file list is not filtered twice.
+      const filePaths = Object.keys(this.zip.files).filter((path) => !this.zip!.files[path]!.dir);
+
+      // Reject entry-count amplification before decompressing anything.
+      if (limits.maxEntryCount > 0 && filePaths.length > limits.maxEntryCount) {
+        throw new ResourceLimitError(
+          `archive entry count (${filePaths.length}) exceeds maxEntryCount (${limits.maxEntryCount})`
+        );
+      }
+
+      // Extract all files (enforces uncompressed/ratio budgets while decompressing)
+      await this.extractFiles(limits, filePaths);
 
       // Validate DOCX structure if requested
       if (validate) {
@@ -79,7 +118,9 @@ export class ZipReader {
 
       this.loaded = true;
     } catch (error: unknown) {
-      if (error instanceof InvalidDocxError) {
+      // A resource-limit breach must not be masked as a generic corruption error;
+      // the cause (which budget was exceeded) is actionable for the caller.
+      if (error instanceof InvalidDocxError || error instanceof ResourceLimitError) {
         throw error;
       }
       const message = error instanceof Error ? error.message : String(error);
@@ -91,20 +132,41 @@ export class ZipReader {
    * Extracts all files from the ZIP archive into memory
    *
    * **Encoding Note:**
-   * - Text files (XML, etc.) are extracted as UTF-8 strings using `async('string')`
+   * - Known-text parts (.xml, .rels, etc.) are extracted as UTF-8 strings using `async('string')`
    * - JSZip automatically decodes UTF-8 when extracting as 'string'
-   * - Binary files are extracted as Buffers to preserve exact content
+   * - Everything else is extracted as a Buffer to preserve exact bytes — a
+   *   string decode is lossy (invalid UTF-8 becomes U+FFFD), which would
+   *   corrupt embedded binary parts (OLE packages, fonts, metafiles)
    * - All text content is guaranteed to be valid UTF-8
+   *
+   * **Resource limits:** the running total of *actual* decompressed bytes is the
+   * primary defense against high-ratio archives. JSZip's internal `_data` metadata
+   * is consulted only as an early-reject hint (it is undocumented and may be absent),
+   * never as the sole guard — every breach is re-checked against measured bytes.
+   *
+   * @param limits - Fully-resolved size limits to enforce while extracting
+   * @param filePaths - Pre-filtered non-directory entry paths (computed by the caller)
    */
-  private async extractFiles(): Promise<void> {
+  private async extractFiles(
+    limits: Required<SizeLimitOptions>,
+    filePaths: string[]
+  ): Promise<void> {
     if (!this.zip) {
       throw new Error('ZIP archive not loaded');
     }
 
     this.files.clear();
 
-    // Get all file paths
-    const filePaths = Object.keys(this.zip.files).filter((path) => !this.zip!.files[path]!.dir);
+    const maxEntryBytes =
+      limits.maxEntryUncompressedMB > 0 ? limits.maxEntryUncompressedMB * 1024 * 1024 : 0;
+    const maxTotalBytes =
+      limits.maxTotalUncompressedMB > 0 ? limits.maxTotalUncompressedMB * 1024 * 1024 : 0;
+    // Only enforce the compression ratio on entries large enough for the ratio to be
+    // meaningful, so a small but highly-compressible part (e.g. tiny repetitive XML)
+    // cannot trip a false positive.
+    const ratioFloorBytes = 1024 * 1024;
+
+    let totalBytes = 0;
 
     // Extract each file
     for (const filePath of filePaths) {
@@ -115,20 +177,80 @@ export class ZipReader {
         continue;
       }
 
+      // Early-reject hint: JSZip exposes declared uncompressed/compressed sizes on a
+      // private `_data` field. Cast once per entry (see {@link JSZipObjectPrivate}) and
+      // use it only to avoid decompressing an obviously oversized entry; the
+      // authoritative check below uses the measured byte count.
+      const internalData = (zipObject as unknown as JSZipObjectPrivate)._data;
+      const declaredSize = internalData?.uncompressedSize;
+      if (typeof declaredSize === 'number' && declaredSize >= 0) {
+        if (maxEntryBytes > 0 && declaredSize > maxEntryBytes) {
+          throw new ResourceLimitError(
+            `entry "${normalizedPath}" uncompressed size (${declaredSize} bytes) exceeds ` +
+              `maxEntryUncompressedMB (${limits.maxEntryUncompressedMB}MB)`
+          );
+        }
+        if (maxTotalBytes > 0 && totalBytes + declaredSize > maxTotalBytes) {
+          throw new ResourceLimitError(
+            `total uncompressed size would exceed maxTotalUncompressedMB ` +
+              `(${limits.maxTotalUncompressedMB}MB)`
+          );
+        }
+      }
+
       const isBinary = isBinaryFile(normalizedPath);
 
       // Extract content based on type
-      // For text files: JSZip's async('string') automatically uses UTF-8 decoding
-      // For binary files: async('nodebuffer') preserves exact bytes
+      // For known-text files: JSZip's async('string') automatically uses UTF-8 decoding
+      // For everything else: async('nodebuffer') preserves exact bytes
       let content;
       if (isBinary) {
         content = await zipObject.async('nodebuffer');
       } else {
-        // Text files are extracted as UTF-8 strings
+        // Known-text files are extracted as UTF-8 strings
         // JSZip automatically handles UTF-8 decoding for 'string' type
         content = await zipObject.async('string');
       }
 
+      // Measure the *actual* decompressed byte count (UTF-8 for strings) — this is the
+      // primary, authoritative resource accounting that does not trust archive metadata.
+      const entryBytes = Buffer.isBuffer(content)
+        ? content.length
+        : Buffer.byteLength(content, 'utf8');
+
+      if (maxEntryBytes > 0 && entryBytes > maxEntryBytes) {
+        throw new ResourceLimitError(
+          `entry "${normalizedPath}" uncompressed size (${entryBytes} bytes) exceeds ` +
+            `maxEntryUncompressedMB (${limits.maxEntryUncompressedMB}MB)`
+        );
+      }
+
+      totalBytes += entryBytes;
+      if (maxTotalBytes > 0 && totalBytes > maxTotalBytes) {
+        throw new ResourceLimitError(
+          `total uncompressed size (${totalBytes} bytes) exceeds maxTotalUncompressedMB ` +
+            `(${limits.maxTotalUncompressedMB}MB)`
+        );
+      }
+
+      // Compression-ratio guard for sizable entries, when the archive reports a
+      // compressed size we can divide by (reusing the single `_data` read above).
+      const compressedSize = internalData?.compressedSize;
+      if (
+        limits.maxCompressionRatio > 0 &&
+        entryBytes > ratioFloorBytes &&
+        typeof compressedSize === 'number' &&
+        compressedSize > 0
+      ) {
+        const ratio = entryBytes / compressedSize;
+        if (ratio > limits.maxCompressionRatio) {
+          throw new ResourceLimitError(
+            `entry "${normalizedPath}" compression ratio (${ratio.toFixed(1)}:1) exceeds ` +
+              `maxCompressionRatio (${limits.maxCompressionRatio}:1)`
+          );
+        }
+      }
+
       // Get file metadata
       const date = zipObject.date;
 

package/src/zip/errors.ts

@@ -46,6 +46,21 @@ export class CorruptedArchiveError extends DocxError {
   }
 }
 
+/**
+ * Error thrown when an archive breaches a configured resource limit.
+ *
+ * Distinct from {@link CorruptedArchiveError} so callers can tell a hostile/oversized
+ * input (a "zip bomb" style payload) apart from a genuinely malformed archive. The
+ * message names the specific limit that was exceeded so it is actionable.
+ */
+export class ResourceLimitError extends DocxError {
+  constructor(message: string) {
+    super(`Resource limit exceeded: ${message}`);
+    this.name = 'ResourceLimitError';
+    Object.setPrototypeOf(this, ResourceLimitError.prototype);
+  }
+}
+
 /**
  * Error thrown when a required DOCX file is missing
  */

package/src/zip/types.ts

@@ -28,18 +28,60 @@ export interface SizeLimitOptions {
    */
   warningSizeMB?: number;
   /**
-   * Maximum size in MB to load (default: 150 MB)
+   * Maximum *compressed* archive size in MB to load (default: 150 MB)
    * Set to 0 to disable the limit (not recommended)
    */
   maxSizeMB?: number;
+  /**
+   * Maximum total *uncompressed* size in MB across all archive entries
+   * (default: 300 MB). This is the primary, authoritative defense against
+   * high-ratio "zip bomb" payloads whose compressed size is small: it is
+   * enforced against measured decompressed bytes, never archive-reported
+   * metadata. Set to 0 to disable.
+   *
+   * Note: decompression is non-streaming (JSZip buffers each entry fully), so
+   * peak transient heap can approach `maxTotalUncompressedMB + maxEntryUncompressedMB`
+   * (the already-accumulated total plus the entry being decoded) before a limit
+   * fires. Size the limits with that headroom in mind for memory-constrained hosts.
+   */
+  maxTotalUncompressedMB?: number;
+  /**
+   * Maximum *uncompressed* size in MB for any single archive entry
+   * (default: 150 MB). Set to 0 to disable.
+   */
+  maxEntryUncompressedMB?: number;
+  /**
+   * Maximum number of entries (files) allowed in the archive
+   * (default: 2000). Guards against entry-count amplification. Set to 0 to disable.
+   */
+  maxEntryCount?: number;
+  /**
+   * Maximum allowed per-entry compression ratio (uncompressed / compressed)
+   * (default: 200). Only enforced for sizable entries where the ratio is
+   * meaningful and the compressed size is reported by the archive.
+   *
+   * Best-effort: it relies on a compressed size that JSZip exposes only on an
+   * undocumented internal field, so it is silently skipped for any entry where
+   * that size is absent. `maxTotalUncompressedMB` is the authoritative guard
+   * against high-ratio payloads; treat this ratio limit as a defense-in-depth
+   * early reject, not a sole defense. Set to 0 to disable.
+   */
+  maxCompressionRatio?: number;
 }
 
 /**
- * Default size limits for document loading
+ * Default size limits for document loading.
+ *
+ * Defaults are intentionally generous so legitimate large documents load
+ * unchanged; tighten them via {@link LoadOptions.sizeLimits} for untrusted input.
  */
 export const DEFAULT_SIZE_LIMITS: Required<SizeLimitOptions> = {
   warningSizeMB: 50,
   maxSizeMB: 150,
+  maxTotalUncompressedMB: 300,
+  maxEntryUncompressedMB: 150,
+  maxEntryCount: 2000,
+  maxCompressionRatio: 200,
 };
 
 /**