docxmlater 11.0.10 → 12.1.0

package/src/xml/XMLParser.ts

@@ -139,8 +139,9 @@ export class XMLParser {
         continue;
       }
 
-      // Find the end of opening tag
-      const openEnd = xml.indexOf('>', startIdx);
+      // Find the end of opening tag (quote-aware: attribute values may
+      // legally contain a raw '>')
+      const openEnd = XMLParser.findTagEnd(xml, startIdx);
       if (openEnd === -1) break;
 
       // Check if self-closing
@@ -333,8 +334,9 @@ export class XMLParser {
     const startIdx = xml.indexOf(startTag);
     if (startIdx === -1) return undefined;
 
-    // Find the end of the opening tag
-    const openEnd = xml.indexOf('>', startIdx);
+    // Find the end of the opening tag (quote-aware: attribute values may
+    // legally contain a raw '>')
+    const openEnd = XMLParser.findTagEnd(xml, startIdx);
     if (openEnd === -1) return undefined;
 
     // Find the closing tag
@@ -344,6 +346,28 @@ export class XMLParser {
     return xml.substring(openEnd + 1, endIdx);
   }
 
+  /**
+   * Finds the first '>' at or after startPos that is not inside a quoted
+   * attribute value. XML 1.0 §2.3 permits a raw '>' inside attribute values
+   * (only '<', '&', and the delimiting quote must be escaped), so a bare
+   * indexOf('>') can end a tag header mid-attribute.
+   * @private
+   */
+  private static findTagEnd(xml: string, startPos: number): number {
+    let quote: string | undefined;
+    for (let pos = startPos; pos < xml.length; pos++) {
+      const ch = xml[pos];
+      if (quote) {
+        if (ch === quote) quote = undefined;
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === '>') {
+        return pos;
+      }
+    }
+    return -1;
+  }
+
   /**
    * Extracts a complete self-closing tag with its attributes
    * Handles cases where multiple similar tags exist (e.g., <w:sz.../> and <w:szCs.../>)
@@ -371,19 +395,17 @@ export class XMLParser {
 
       // Valid separators after tag name: space, '/', or '>'
       if (charAfterTag === ' ' || charAfterTag === '/' || charAfterTag === '>') {
-        // Found the exact tag, now find its end
-        const endIdx = xml.indexOf('/>', startIdx);
-        if (endIdx === -1) {
-          // Try finding a closing tag instead (non-self-closing)
-          const closeTagStart = xml.indexOf('>', startIdx);
-          if (closeTagStart === -1) return undefined;
-
-          // Return attributes portion
-          return xml.substring(startIdx + startPattern.length, closeTagStart);
-        }
-
-        // Return attributes portion (between tag name and />)
-        return xml.substring(startIdx + startPattern.length, endIdx);
+        // Found the exact tag. Bound the search to this element's own tag
+        // header: a global indexOf('/>') can land inside a later sibling
+        // when the target is written in expanded form (<tag ...></tag>),
+        // attributing the sibling's attributes to this tag.
+        const tagEnd = XMLParser.findTagEnd(xml, startIdx + startPattern.length);
+        if (tagEnd === -1) return undefined;
+
+        // Self-closing: exclude the trailing '/'; expanded form: attributes
+        // run up to the '>' of the open tag.
+        const attrEnd = xml[tagEnd - 1] === '/' ? tagEnd - 1 : tagEnd;
+        return xml.substring(startIdx + startPattern.length, attrEnd);
       }
 
       // Not the exact tag (e.g., found "w:sz" when looking for "w:s")
@@ -477,6 +499,27 @@ export class XMLParser {
       return { value: {}, endPos: xml.length };
     }
 
+    // Skip processing instructions (e.g. <?mso-application ...?>); without
+    // this, '?' fails the element-name match and the PI body is mangled
+    // into text one character at a time
+    if (xml.substring(openTagStart, openTagStart + 2) === '<?') {
+      const piEnd = xml.indexOf('?>', openTagStart + 2);
+      if (piEnd !== -1) {
+        return XMLParser.parseElementToObject(xml, piEnd + 2, options, depth);
+      }
+      return { value: {}, endPos: xml.length };
+    }
+
+    // Skip CDATA found where an element is expected (e.g. at the root);
+    // CDATA inside element content is preserved by the content loop below
+    if (xml.substring(openTagStart, openTagStart + 9) === '<![CDATA[') {
+      const cdataEnd = xml.indexOf(']]>', openTagStart + 9);
+      if (cdataEnd !== -1) {
+        return XMLParser.parseElementToObject(xml, cdataEnd + 3, options, depth);
+      }
+      return { value: {}, endPos: xml.length };
+    }
+
     // Extract element name
     const nameMatch = /^([a-zA-Z0-9:_-]+)/.exec(xml.substring(openTagStart + 1));
     if (!nameMatch) {
@@ -485,7 +528,8 @@ export class XMLParser {
 
     const originalElementName: string = nameMatch[1] || '';
     let elementName: string = originalElementName;
-    const tagHeaderEnd = xml.indexOf('>', openTagStart);
+    // Quote-aware scan: attribute values may legally contain a raw '>'
+    const tagHeaderEnd = XMLParser.findTagEnd(xml, openTagStart);
     if (tagHeaderEnd === -1) {
       return { value: {}, endPos: xml.length };
     }
@@ -558,6 +602,19 @@ export class XMLParser {
         }
       }
 
+      // CDATA: append the payload verbatim — its content is by definition
+      // already unescaped, so entity decoding must not be applied
+      if (content.startsWith('<![CDATA[', nextTag)) {
+        const cdataEnd = content.indexOf(']]>', nextTag + 9);
+        if (cdataEnd === -1) {
+          textContent += content.substring(nextTag + 9);
+          break;
+        }
+        textContent += content.substring(nextTag + 9, cdataEnd);
+        pos = cdataEnd + 3;
+        continue;
+      }
+
       // Parse child element (increment depth for children)
       const childResult = XMLParser.parseElementToObject(content, nextTag, options, depth + 1);
       const childObj = childResult.value as ParsedXMLObject;
@@ -602,6 +659,11 @@ export class XMLParser {
     // Add children
     if (children.length > 0) {
       const coalescedChildren = XMLParser.coalesceChildren(children, options);
+      // Mixed content with no attributes leaves elementValue as a bare
+      // string; fold it into object form so merging children keeps the text
+      if (typeof elementValue === 'string') {
+        elementValue = { [options.textNodeName]: elementValue };
+      }
       if (typeof elementValue === 'object' && !Array.isArray(elementValue)) {
         elementValue = { ...elementValue, ...coalescedChildren };
       } else {
@@ -705,10 +767,15 @@ export class XMLParser {
       // Add prefix to attribute name
       const prefixedName = options.attributeNamePrefix + attrName;
 
+      // Unescape XML entities so stored attribute values are the actual
+      // decoded strings, matching text-node handling and extractAttribute.
+      // This prevents double-escaping when the value is later re-serialized.
+      const decodedValue = XMLBuilder.unescapeXml(attrValue);
+
       // Parse attribute value
       attributes[prefixedName] = options.parseAttributeValue
-        ? XMLParser.parseValue(attrValue)
-        : attrValue;
+        ? XMLParser.parseValue(decodedValue)
+        : decodedValue;
     }
 
     return attributes;

package/src/zip/ZipHandler.ts

@@ -14,7 +14,9 @@ import {
   SizeLimitOptions,
   DEFAULT_SIZE_LIMITS,
 } from './types.js';
+import { ResourceLimitError } from './errors.js';
 import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';
+import { normalizePath } from '../utils/validation.js';
 
 // Create scoped logger for ZipHandler operations
 function getLogger(): ILogger {
@@ -41,16 +43,19 @@ export class ZipHandler {
    * Validates document size against configured limits
    * @param sizeMB - Size in megabytes
    * @param limits - Size limit options (merged with defaults)
-   * @throws Error if size exceeds maximum
+   * @throws {ResourceLimitError} If the compressed size exceeds maxSizeMB
    */
   private validateDocumentSize(sizeMB: number, limits: Required<SizeLimitOptions>): void {
     const logger = getLogger();
     const { warningSizeMB, maxSizeMB } = limits;
 
-    // Check maximum size (if enabled)
+    // Check maximum size (if enabled). Throw the typed ResourceLimitError so this
+    // compressed-size guard is catchable by the same type as the uncompressed/ratio/
+    // entry-count guards enforced downstream in ZipReader — callers can distinguish a
+    // hostile/oversized payload from a genuinely corrupt archive.
     if (maxSizeMB > 0 && sizeMB > maxSizeMB) {
       logger.error('Document exceeds maximum size', { sizeMB: sizeMB.toFixed(1), maxSizeMB });
-      throw new Error(
+      throw new ResourceLimitError(
         `Document size (${sizeMB.toFixed(1)}MB) exceeds maximum supported size (${maxSizeMB}MB). ` +
           `This would likely cause out-of-memory errors. Consider:\n` +
           `- Compressing/optimizing images\n` +
@@ -98,15 +103,26 @@ export class ZipHandler {
     const limits = this.getSizeLimits(options);
     this.validateDocumentSize(sizeMB, limits);
 
-    await this.reader.loadFromFile(filePath, options);
-
-    // Copy all files from reader to writer for modification
-    const files = this.reader.getAllFiles();
-    this.writer.clear();
-    this.writer.addFiles(files);
-
-    this.mode = 'modify';
-    logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    try {
+      await this.reader.loadFromFile(filePath, options);
+
+      // Copy all files from reader to writer for modification
+      const files = this.reader.getAllFiles();
+      this.writer.clear();
+      this.writer.addFiles(files);
+
+      this.mode = 'modify';
+      logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    } catch (error) {
+      // A failed reload must not leave the handler serving the previously loaded
+      // archive. Reset to a deterministically empty state so getFile/save/etc.
+      // cannot silently return stale content. A fresh reader discards any
+      // partially-extracted files and the stale `loaded` flag.
+      this.writer.clear();
+      this.reader = new ZipReader();
+      this.mode = 'write';
+      throw error;
+    }
   }
 
   /**
@@ -125,15 +141,26 @@ export class ZipHandler {
     const limits = this.getSizeLimits(options);
     this.validateDocumentSize(sizeMB, limits);
 
-    await this.reader.loadFromBuffer(buffer, options);
-
-    // Copy all files from reader to writer for modification
-    const files = this.reader.getAllFiles();
-    this.writer.clear();
-    this.writer.addFiles(files);
-
-    this.mode = 'modify';
-    logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    try {
+      await this.reader.loadFromBuffer(buffer, options);
+
+      // Copy all files from reader to writer for modification
+      const files = this.reader.getAllFiles();
+      this.writer.clear();
+      this.writer.addFiles(files);
+
+      this.mode = 'modify';
+      logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    } catch (error) {
+      // A failed reload must not leave the handler serving the previously loaded
+      // archive. Reset to a deterministically empty state so getFile/save/etc.
+      // cannot silently return stale content. A fresh reader discards any
+      // partially-extracted files and the stale `loaded` flag.
+      this.writer.clear();
+      this.reader = new ZipReader();
+      this.mode = 'write';
+      throw error;
+    }
   }
 
   // ==================== FILE OPERATIONS ====================
@@ -300,6 +327,13 @@ export class ZipHandler {
     if (!file) {
       return false;
     }
+    // Guard against degenerate rename where source and destination collapse to
+    // the same archive key (identical strings or backslash/forward-slash variants).
+    // Without this, addFile would overwrite the single entry and the subsequent
+    // removeFile would delete it, silently destroying the file.
+    if (normalizePath(oldPath) === normalizePath(newPath)) {
+      return true;
+    }
     this.addFile(newPath, file.content, {
       binary: file.isBinary,
       date: file.date,
@@ -336,6 +370,12 @@ export class ZipHandler {
     if (!this.copyFile(srcPath, destPath)) {
       return false;
     }
+    // Guard against degenerate move where source and destination collapse to the
+    // same archive key. copyFile already re-added the (identical) entry, so the
+    // removeFile below would delete it, silently destroying the file.
+    if (normalizePath(srcPath) === normalizePath(destPath)) {
+      return true;
+    }
     this.removeFile(srcPath);
     return true;
   }

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,
 };
 
 /**