docxmlater 11.0.10 → 12.1.0

package/src/utils/units.ts

@@ -145,7 +145,9 @@ export function emusToPixels(emus: number, dpi: number = STANDARD_DPI): number {
  * @returns Value in twips
  */
 export function pointsToTwips(points: number): number {
-  return points * UNITS.TWIPS_PER_POINT;
+  // Round to nearest integer — twips attributes (w:spacing, w:ind) require
+  // ST_DecimalNumber-based integer values
+  return Math.round(points * UNITS.TWIPS_PER_POINT);
 }
 
 /**

package/src/utils/validation.ts

@@ -23,29 +23,28 @@ export function validateDocxStructure(filePaths: string[]): void {
 
 /**
  * Checks if a file path represents a binary file based on extension
+ *
+ * Uses a text-extension whitelist rather than a binary-extension whitelist:
+ * misclassifying text as binary only changes its in-memory representation
+ * (Buffer instead of string), but misclassifying binary as text corrupts the
+ * bytes through a lossy UTF-8 decode. OOXML packages can embed arbitrary
+ * binary parts (.xlsx/.pdf OLE packages, .odttf obfuscated fonts, .emz/.wmz
+ * compressed metafiles, extensionless parts), so anything not known to be
+ * text must be preserved byte-for-byte.
+ *
  * @param filePath - The file path to check
  * @returns True if the file is likely binary
  */
 export function isBinaryFile(filePath: string): boolean {
-  const binaryExtensions = [
-    '.png',
-    '.jpg',
-    '.jpeg',
-    '.gif',
-    '.bmp',
-    '.tiff',
-    '.ico',
-    '.emf',
-    '.wmf',
-    '.bin',
-    '.dat',
-    '.ttf',
-    '.otf',
-    '.woff',
-  ];
+  const textExtensions = ['.xml', '.rels', '.svg', '.txt', '.html', '.css', '.js'];
 
-  const extension = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
-  return binaryExtensions.includes(extension);
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) {
+    return true;
+  }
+
+  const extension = filePath.substring(dotIndex).toLowerCase();
+  return !textExtensions.includes(extension);
 }
 
 /**
@@ -55,12 +54,15 @@ export function isBinaryFile(filePath: string): boolean {
  *
  * **Security:** This function validates paths to prevent:
  * - Path traversal attacks (../, ..\, URL-encoded variants)
- * - Absolute paths (C:\, /etc/, etc.)
+ * - Absolute Windows paths (C:\, D:, etc.) — rejected
  * - Malicious DOCX files attempting directory escape
  *
+ * Unix absolute paths (/etc/...) are sanitized to archive-relative paths
+ * by stripping leading slashes, not rejected.
+ *
  * @param path - The path to normalize
  * @returns Normalized path
- * @throws {Error} If path contains path traversal sequences, absolute paths, or URL-encoded attacks
+ * @throws {Error} If path contains path traversal sequences, absolute Windows paths, or URL-encoded attacks
  */
 export function normalizePath(path: string): string {
   // First convert all backslashes to forward slashes for consistent checking
@@ -97,15 +99,6 @@ export function normalizePath(path: string): string {
     );
   }
 
-  // Security: Prevent Unix absolute paths
-  // After removing leading slashes, if it starts with / it's suspicious
-  if (path.startsWith('/') && normalized.startsWith('/')) {
-    throw new Error(
-      `Invalid file path: "${path}" appears to be an absolute Unix path. ` +
-        `Only relative paths are allowed in DOCX archives.`
-    );
-  }
-
   return normalized;
 }
 
@@ -161,6 +154,11 @@ export function validateTwips(value: number, fieldName = 'value'): void {
     throw new Error(`${fieldName} must be a finite number, got ${value}`);
   }
 
+  // ST_TwipsMeasure/ST_SignedTwipsMeasure are ST_DecimalNumber-based — integers only
+  if (!Number.isInteger(value)) {
+    throw new Error(`${fieldName} must be an integer (in twips), got ${value}`);
+  }
+
   // Reasonable range: ±22 inches (31680 twips)
   const MIN_TWIPS = -31680;
   const MAX_TWIPS = 31680;
@@ -304,7 +302,7 @@ export function validateAlignment(
 
 /**
  * Validates a font size (in half-points for Word)
- * Reasonable range: 2-1638 (1-819 points)
+ * Reasonable range: 2-3276 (1-1638 points)
  * @param size - The font size in half-points to validate
  * @param fieldName - Name of the field (for error messages)
  * @throws {Error} If the size is invalid
@@ -318,9 +316,9 @@ export function validateFontSize(size: number, fieldName = 'font size'): void {
     throw new Error(`${fieldName} must be an integer (in half-points), got ${size}`);
   }
 
-  // Reasonable range: 2-1638 half-points (1-819 points)
+  // Word's limit is 1-1638 points, i.e. 2-3276 half-points for w:sz (ST_HpsMeasure)
   const MIN_SIZE = 2;
-  const MAX_SIZE = 1638;
+  const MAX_SIZE = 3276;
 
   if (size < MIN_SIZE || size > MAX_SIZE) {
     throw new Error(

package/src/utils/xmlSanitization.ts

@@ -9,11 +9,13 @@
  * - 0x09 (tab), 0x0A (newline), 0x0D (carriage return)
  * - 0x20-0xD7FF, 0xE000-0xFFFD, 0x10000-0x10FFFF
  *
- * Invalid characters (control characters that must be removed):
+ * Invalid characters that must be removed:
  * - 0x00-0x08 (NULL through BACKSPACE)
  * - 0x0B-0x0C (VERTICAL TAB and FORM FEED)
  * - 0x0E-0x1F (SHIFT OUT through UNIT SEPARATOR)
  * - 0x7F (DELETE)
+ * - 0xFFFE-0xFFFF (Unicode noncharacters excluded by the Char production)
+ * - Unpaired surrogates (0xD800-0xDFFF outside a valid high/low pair)
  *
  * @module xmlSanitization
  */
@@ -21,26 +23,40 @@
 import { getGlobalLogger } from './logger.js';
 
 /**
- * Regular expression matching invalid XML 1.0 control characters.
- * Matches: 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F
+ * Regular expression matching invalid XML 1.0 characters.
+ * Matches: 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F, 0xFFFE, 0xFFFF
  * Does NOT match valid chars: 0x09 (tab), 0x0A (newline), 0x0D (CR)
  */
-const INVALID_XML_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+const INVALID_XML_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F￾￿]/g;
 
 /**
- * Removes invalid XML 1.0 control characters from text.
+ * Matches surrogate code units that do not form a valid high/low pair.
+ * XML 1.0 Char excludes 0xD800-0xDFFF entirely; only properly paired
+ * surrogates (which decode to a single 0x10000-0x10FFFF character) are
+ * legal, so lone halves must be stripped or they corrupt the part at
+ * UTF-8 encode time.
+ */
+const UNPAIRED_SURROGATE_REGEX =
+  /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+/**
+ * Removes invalid XML 1.0 characters from text.
  *
- * Per XML 1.0 spec, characters 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid
- * and cannot appear in XML documents. This function removes them.
+ * Per XML 1.0 spec, characters 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F,
+ * 0xFFFE, 0xFFFF, and unpaired surrogates are invalid and cannot appear
+ * in XML documents. This function removes them.
  *
  * Valid control characters are preserved:
  * - Tab (0x09)
  * - Line Feed / Newline (0x0A)
  * - Carriage Return (0x0D)
  *
+ * Properly paired surrogates (astral-plane characters such as emoji)
+ * are preserved.
+ *
  * @param text - Input text to sanitize
  * @param logWarning - If true, logs a warning when invalid chars are found (default: true)
- * @returns Sanitized text with invalid control characters removed
+ * @returns Sanitized text with invalid characters removed
  *
  * @example
  * ```typescript
@@ -54,31 +70,33 @@ const INVALID_XML_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
  * ```
  */
 export function removeInvalidXmlChars(text: string, logWarning = true): string {
-  // Reset regex lastIndex for global regex
+  // Reset regex lastIndex for global regexes
   INVALID_XML_CHAR_REGEX.lastIndex = 0;
+  UNPAIRED_SURROGATE_REGEX.lastIndex = 0;
 
-  if (logWarning && INVALID_XML_CHAR_REGEX.test(text)) {
+  if (logWarning && (INVALID_XML_CHAR_REGEX.test(text) || UNPAIRED_SURROGATE_REGEX.test(text))) {
     // Reset regex lastIndex after test
     INVALID_XML_CHAR_REGEX.lastIndex = 0;
+    UNPAIRED_SURROGATE_REGEX.lastIndex = 0;
 
     const invalidChars = findInvalidXmlChars(text);
     const hexCodes = invalidChars
       .map((c) => `0x${c.toString(16).toUpperCase().padStart(2, '0')}`)
       .join(', ');
-    getGlobalLogger().warn(
-      `[XMLSanitization] Removing invalid XML control characters: ${hexCodes}`
-    );
+    getGlobalLogger().warn(`[XMLSanitization] Removing invalid XML characters: ${hexCodes}`);
   }
 
   // Reset regex lastIndex before replace
   INVALID_XML_CHAR_REGEX.lastIndex = 0;
-  return text.replace(INVALID_XML_CHAR_REGEX, '');
+  UNPAIRED_SURROGATE_REGEX.lastIndex = 0;
+  return text.replace(INVALID_XML_CHAR_REGEX, '').replace(UNPAIRED_SURROGATE_REGEX, '');
 }
 
 /**
- * Finds all invalid XML 1.0 control characters in text.
+ * Finds all invalid XML 1.0 characters in text.
  *
- * Returns an array of unique character codes that are invalid per XML 1.0 spec.
+ * Returns an array of unique character codes that are invalid per XML 1.0 spec,
+ * including 0xFFFE/0xFFFF noncharacters and unpaired surrogate code units.
  * This is useful for diagnostics and error reporting.
  *
  * @param text - Text to scan for invalid characters
@@ -100,12 +118,25 @@ export function findInvalidXmlChars(text: string): number[] {
     const code = text.charCodeAt(i);
 
     // Check if character is in invalid ranges
-    if (
+    let isInvalid =
       (code >= 0x00 && code <= 0x08) || // NULL through BACKSPACE
       (code >= 0x0b && code <= 0x0c) || // VERTICAL TAB and FORM FEED
       (code >= 0x0e && code <= 0x1f) || // SHIFT OUT through UNIT SEPARATOR
-      code === 0x7f // DELETE
-    ) {
+      code === 0x7f || // DELETE
+      code === 0xfffe || // Noncharacter excluded by XML 1.0 Char
+      code === 0xffff; // Noncharacter excluded by XML 1.0 Char
+
+    if (!isInvalid && code >= 0xd800 && code <= 0xdbff) {
+      // High surrogate is only valid when followed by a low surrogate
+      const next = text.charCodeAt(i + 1); // NaN at end of string fails the range check
+      isInvalid = !(next >= 0xdc00 && next <= 0xdfff);
+    } else if (!isInvalid && code >= 0xdc00 && code <= 0xdfff) {
+      // Low surrogate is only valid when preceded by a high surrogate
+      const prev = text.charCodeAt(i - 1); // NaN at start of string fails the range check
+      isInvalid = !(prev >= 0xd800 && prev <= 0xdbff);
+    }
+
+    if (isInvalid) {
       // Only add unique codes
       if (!invalid.includes(code)) {
         invalid.push(code);
@@ -117,7 +148,7 @@ export function findInvalidXmlChars(text: string): number[] {
 }
 
 /**
- * Checks if text contains any invalid XML 1.0 control characters.
+ * Checks if text contains any invalid XML 1.0 characters.
  *
  * This is a fast check that returns true/false without identifying specific characters.
  * Use `findInvalidXmlChars()` if you need to know which characters are invalid.
@@ -133,9 +164,174 @@ export function findInvalidXmlChars(text: string): number[] {
  * ```
  */
 export function hasInvalidXmlChars(text: string): boolean {
-  // Reset regex lastIndex for global regex
+  // Reset regex lastIndex for global regexes
   INVALID_XML_CHAR_REGEX.lastIndex = 0;
-  return INVALID_XML_CHAR_REGEX.test(text);
+  UNPAIRED_SURROGATE_REGEX.lastIndex = 0;
+  return INVALID_XML_CHAR_REGEX.test(text) || UNPAIRED_SURROGATE_REGEX.test(text);
+}
+
+/**
+ * CT_RPr child element order per ECMA-376 Part 1 §17.3.2.28 (local names,
+ * `w:` namespace). Used to repair raw-preserved run-property blocks whose
+ * children are out of schema order — Word rejects, for example, a `w:b`
+ * that appears after `w:color`/`w:sz` and reports the document as corrupt.
+ */
+const CT_RPR_CHILD_ORDER: readonly string[] = [
+  'rStyle',
+  'rFonts',
+  'b',
+  'bCs',
+  'i',
+  'iCs',
+  'caps',
+  'smallCaps',
+  'strike',
+  'dstrike',
+  'outline',
+  'shadow',
+  'emboss',
+  'imprint',
+  'noProof',
+  'snapToGrid',
+  'vanish',
+  'webHidden',
+  'color',
+  'spacing',
+  'w',
+  'kern',
+  'position',
+  'sz',
+  'szCs',
+  'highlight',
+  'u',
+  'effect',
+  'bdr',
+  'shd',
+  'fitText',
+  'vertAlign',
+  'rtl',
+  'cs',
+  'em',
+  'lang',
+  'eastAsianLayout',
+  'specVanish',
+  'oMath',
+];
+
+/**
+ * Splits the inner content of an element into its top-level child elements,
+ * respecting nesting so that a child's descendants are kept with it. Returns
+ * the raw XML fragment for each direct child in document order. Non-element
+ * text between children (whitespace) is dropped, which is safe for the
+ * element-only content models this helper targets (e.g. `w:rPr`).
+ */
+function splitTopLevelElements(inner: string): string[] {
+  const children: string[] = [];
+  const tagRegex = /<([A-Za-z][\w:.-]*)([^>]*?)(\/?)>|<\/([A-Za-z][\w:.-]*)\s*>/g;
+  let depth = 0;
+  let start = -1;
+  let match: RegExpExecArray | null;
+  while ((match = tagRegex.exec(inner)) !== null) {
+    const isClosing = match[4] !== undefined;
+    const isSelfClosing = match[3] === '/';
+    if (isClosing) {
+      if (depth > 0) {
+        depth--;
+        if (depth === 0 && start !== -1) {
+          children.push(inner.slice(start, tagRegex.lastIndex));
+          start = -1;
+        }
+      }
+      continue;
+    }
+    if (isSelfClosing) {
+      if (depth === 0) {
+        children.push(inner.slice(match.index, tagRegex.lastIndex));
+      }
+      continue;
+    }
+    // Opening tag of a paired element
+    if (depth === 0) start = match.index;
+    depth++;
+  }
+  return children;
+}
+
+/**
+ * Reorders the direct children of every `<w:rPr>` block in a raw XML part to
+ * the ECMA-376 CT_RPr sequence. Unknown/unmodeled children retain their
+ * relative position at the end of the block. The transform is idempotent:
+ * already-ordered run properties are returned unchanged.
+ *
+ * Some producers (and older versions of this framework) appended boolean
+ * toggles such as `w:b`/`w:bCs` to the end of an existing `w:rPr`, leaving
+ * them after `w:color`/`w:sz`. Word treats the out-of-order child as an
+ * unexpected element and flags the whole document as corrupt. Numbering
+ * definitions are written back verbatim for fidelity, so this repair runs on
+ * the preserved part before it is saved.
+ *
+ * @param xml - Raw XML for a part containing `w:rPr` blocks (e.g. numbering.xml)
+ * @returns XML with every `w:rPr` child sequence normalized to schema order
+ */
+export function reorderRunPropertyChildren(xml: string): string {
+  if (!xml || !xml.includes('<w:rPr')) return xml;
+
+  const orderIndex = (fragment: string): number => {
+    const nameMatch = /^<w:(\w+)/.exec(fragment);
+    const name = nameMatch?.[1];
+    if (!name) return CT_RPR_CHILD_ORDER.length;
+    const idx = CT_RPR_CHILD_ORDER.indexOf(name);
+    return idx === -1 ? CT_RPR_CHILD_ORDER.length : idx;
+  };
+
+  // Only match non-empty <w:rPr>...</w:rPr> blocks; self-closing <w:rPr/> has
+  // no children to reorder.
+  return xml.replace(/<w:rPr(\s[^>]*)?>([\s\S]*?)<\/w:rPr>/g, (full, attrs, inner) => {
+    if (!inner || !(inner as string).includes('<')) return full;
+    const children = splitTopLevelElements(inner);
+    if (children.length < 2) return full;
+
+    const ordered = children
+      .map((frag, i) => ({ frag, i, order: orderIndex(frag) }))
+      // Stable sort: ties (including unknown children) keep original order.
+      .sort((a, b) => a.order - b.order || a.i - b.i);
+
+    if (ordered.every((c, i) => c.i === i)) return full; // already in order
+
+    return `<w:rPr${attrs ?? ''}>${ordered.map((c) => c.frag).join('')}</w:rPr>`;
+  });
+}
+
+/**
+ * Normalizes malformed floating-drawing relative-size elements in a raw anchor
+ * fragment. Per ECMA-376 (DrawingML wordprocessing 2010 extensions),
+ * `wp14:sizeRelH` must contain a `wp14:pctWidth` child and `wp14:sizeRelV` a
+ * `wp14:pctHeight` child. Some producers emit the percentage as bare text
+ * content (`<wp14:sizeRelH relativeFrom="margin">0</wp14:sizeRelH>`), which
+ * Word rejects as incomplete content. This wraps such text in the required
+ * child element. Already-valid nested forms are left untouched because the
+ * text-content pattern (`[^<]`) cannot match an element child.
+ *
+ * @param xml - Raw anchor-extras fragment captured during parsing
+ * @returns Fragment with sizeRelH/sizeRelV normalized to schema-valid form
+ */
+export function normalizeAnchorSizeRel(xml: string): string {
+  if (!xml) return xml;
+  return xml
+    .replace(
+      /(<wp14:sizeRelH\b[^>]*>)([^<]+)(<\/wp14:sizeRelH>)/g,
+      (_m, open: string, text: string, close: string) =>
+        text.trim() === ''
+          ? `${open}${text}${close}`
+          : `${open}<wp14:pctWidth>${text.trim()}</wp14:pctWidth>${close}`
+    )
+    .replace(
+      /(<wp14:sizeRelV\b[^>]*>)([^<]+)(<\/wp14:sizeRelV>)/g,
+      (_m, open: string, text: string, close: string) =>
+        text.trim() === ''
+          ? `${open}${text}${close}`
+          : `${open}<wp14:pctHeight>${text.trim()}</wp14:pctHeight>${close}`
+    );
 }
 
 /**