node-pptx-templater 1.0.4 → 1.0.6

package/src/parsers/XMLParser.js

@@ -23,6 +23,139 @@
 const { XMLParser: FastXMLParser, XMLBuilder } = require('fast-xml-parser')
 const { PPTXError } = require('../utils/errors.js')
 
+const Z_ORDER_SYMBOL = Symbol('zOrder')
+
+const drawingTags = new Set(['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp'])
+
+function findcNvPr(node) {
+  const tagName = Object.keys(node).find(k => k !== ':@')
+  if (!tagName) return null
+  const children = node[tagName]
+  if (!Array.isArray(children)) return null
+
+  const nvPrNode = children.find(child => {
+    const k = Object.keys(child).find(key => key !== ':@')
+    return (
+      k &&
+      (k === 'p:nvSpPr' ||
+        k === 'p:nvPicPr' ||
+        k === 'p:nvGraphicFramePr' ||
+        k === 'p:nvGrpSpPr' ||
+        k === 'p:nvCxnSpPr')
+    )
+  })
+
+  if (nvPrNode) {
+    const nvPrTagName = Object.keys(nvPrNode).find(k => k !== ':@')
+    const nvPrChildren = nvPrNode[nvPrTagName]
+    if (Array.isArray(nvPrChildren)) {
+      const cNvPrNode = nvPrChildren.find(child => Object.keys(child).includes('p:cNvPr'))
+      if (cNvPrNode) {
+        return cNvPrNode[':@']
+      }
+    }
+  }
+  return null
+}
+
+function buildZOrderMap(orderedNode, containerMap = new Map()) {
+  if (!orderedNode) return containerMap
+  const tagName = Object.keys(orderedNode).find(k => k !== ':@')
+  if (!tagName) return containerMap
+  const children = orderedNode[tagName]
+  if (!Array.isArray(children)) return containerMap
+
+  if (tagName === 'p:spTree') {
+    const order = []
+    for (const child of children) {
+      const childTagName = Object.keys(child).find(k => k !== ':@')
+      if (drawingTags.has(childTagName)) {
+        const attrs = findcNvPr(child)
+        if (attrs && attrs['@_id']) {
+          order.push(String(attrs['@_id']))
+        }
+        buildZOrderMap(child, containerMap)
+      }
+    }
+    containerMap.set('root', order)
+  } else if (tagName === 'p:grpSp') {
+    const attrs = findcNvPr(orderedNode)
+    const grpId = attrs ? String(attrs['@_id']) : null
+    const order = []
+    for (const child of children) {
+      const childTagName = Object.keys(child).find(k => k !== ':@')
+      if (drawingTags.has(childTagName)) {
+        const attrs = findcNvPr(child)
+        if (attrs && attrs['@_id']) {
+          order.push(String(attrs['@_id']))
+        }
+        buildZOrderMap(child, containerMap)
+      }
+    }
+    if (grpId) {
+      containerMap.set(grpId, order)
+    }
+  } else {
+    for (const child of children) {
+      buildZOrderMap(child, containerMap)
+    }
+  }
+
+  return containerMap
+}
+
+function attachZOrder(normalContainer, containerId, containerMap) {
+  if (!normalContainer) return
+
+  const order = containerMap.get(containerId)
+  if (order) {
+    normalContainer[Z_ORDER_SYMBOL] = order
+  }
+
+  let grpSps = normalContainer['p:grpSp'] || []
+  if (!Array.isArray(grpSps)) grpSps = [grpSps]
+
+  for (const grpSp of grpSps) {
+    const cNvPr = grpSp?.['p:nvGrpSpPr']?.['p:cNvPr']
+    const grpId = cNvPr ? String(cNvPr['@_id']) : null
+    if (grpId) {
+      attachZOrder(grpSp, grpId, containerMap)
+    }
+  }
+}
+
+/**
+ * Unescapes XML entities safely and non-recursively.
+ * Supports standard XML entities and numeric decimal/hex code points.
+ *
+ * @param {string} str - XML value to unescape.
+ * @returns {string} Unescaped string.
+ */
+function unescapeXml(str) {
+  if (typeof str !== 'string') return str
+  if (str.indexOf('&') === -1) return str
+  return str
+    .replace(/&/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (match, dec) => {
+      try {
+        return String.fromCodePoint(parseInt(dec, 10))
+      } catch (e) {
+        return match
+      }
+    })
+    .replace(/&#x([0-9a-fA-F]+);/g, (match, hex) => {
+      try {
+        return String.fromCodePoint(parseInt(hex, 16))
+      } catch (e) {
+        return match
+      }
+    })
+}
+
 /**
  * Parser configuration for fast-xml-parser.
  * These settings ensure lossless round-trip XML parsing.
@@ -38,7 +171,9 @@ const PARSER_OPTIONS = {
   commentPropName: '__comment',
   preserveOrder: false,
   trimValues: false,
-  processEntities: true,
+  processEntities: false,
+  tagValueProcessor: (tagName, val) => unescapeXml(val),
+  attributeValueProcessor: (attrName, val) => unescapeXml(val),
   htmlEntities: false,
   isArray: (name, jpath) => {
     // Elements that should ALWAYS be arrays (even when there's only one)
@@ -101,9 +236,25 @@ class XMLParser {
    */
   #builder
 
+  /**
+   * @private
+   * @type {FastXMLParser}
+   */
+  #orderedParser
+
   constructor() {
     this.#parser = new FastXMLParser(PARSER_OPTIONS)
     this.#builder = new XMLBuilder(BUILDER_OPTIONS)
+    this.#orderedParser = new FastXMLParser({
+      ignoreAttributes: false,
+      preserveOrder: true,
+      attributeNamePrefix: '@_',
+      parseAttributeValue: false,
+      parseTagValue: false,
+      processEntities: false,
+      tagValueProcessor: (tagName, val) => unescapeXml(val),
+      attributeValueProcessor: (attrName, val) => unescapeXml(val),
+    })
   }
 
   /**
@@ -124,7 +275,31 @@ class XMLParser {
     }
 
     try {
-      return this.#parser.parse(xmlString)
+      const normalObj = this.#parser.parse(xmlString)
+
+      // Automatically inspect for spTree to build and attach Z-order
+      const spTree =
+        normalObj?.['p:sld']?.['p:cSld']?.['p:spTree'] ||
+        normalObj?.['p:sldLayout']?.['p:cSld']?.['p:spTree'] ||
+        normalObj?.['p:sldMaster']?.['p:cSld']?.['p:spTree']
+
+      if (spTree) {
+        try {
+          const orderedObj = this.#orderedParser.parse(xmlString)
+          const orderedRootNode = orderedObj.find(n => {
+            const keys = Object.keys(n)
+            return (
+              keys.includes('p:sld') || keys.includes('p:sldLayout') || keys.includes('p:sldMaster')
+            )
+          })
+          const containerMap = buildZOrderMap(orderedRootNode)
+          attachZOrder(spTree, 'root', containerMap)
+        } catch (err) {
+          // Fallback gracefully if ordered parsing fails
+        }
+      }
+
+      return normalObj
     } catch (err) {
       throw new PPTXError(`XML parse error${context ? ` in ${context}` : ''}: ${err.message}`, err)
     }
@@ -142,13 +317,101 @@ class XMLParser {
    */
   build(obj, xmlDeclaration = '') {
     try {
-      const xml = this.#builder.build(obj)
+      const spTreeObj =
+        obj?.['p:sld']?.['p:cSld']?.['p:spTree'] ||
+        obj?.['p:sldLayout']?.['p:cSld']?.['p:spTree'] ||
+        obj?.['p:sldMaster']?.['p:cSld']?.['p:spTree']
+
+      let xml = this.#builder.build(obj)
+
+      if (spTreeObj) {
+        const correctSpTreeXml = this.serializeContainer(spTreeObj, 'p:spTree')
+        if (xml.includes('<p:spTree/>')) {
+          xml = xml.replace('<p:spTree/>', correctSpTreeXml)
+        } else {
+          xml = xml.replace(/<p:spTree>[\s\S]*<\/p:spTree>/, correctSpTreeXml)
+        }
+      }
+
       return xmlDeclaration ? `${xmlDeclaration}\n${xml}` : xml
     } catch (err) {
       throw new PPTXError(`XML build error: ${err.message}`, err)
     }
   }
 
+  /**
+   * Helper to serialize drawing containers (p:spTree, p:grpSp) recursively in Z-order.
+   */
+  serializeContainer(container, containerTagName) {
+    const zOrder = container[Z_ORDER_SYMBOL] || []
+
+    let headerXml = ''
+    if (container['p:nvGrpSpPr']) {
+      headerXml += this.#builder.build({ 'p:nvGrpSpPr': container['p:nvGrpSpPr'] })
+    }
+    if (container['p:grpSpPr']) {
+      headerXml += this.#builder.build({ 'p:grpSpPr': container['p:grpSpPr'] })
+    }
+
+    // Gather drawing children
+    const drawingElements = new Map()
+    for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+      let items = container[tag] || []
+      if (!Array.isArray(items)) items = [items]
+      for (const item of items) {
+        let id = null
+        if (tag === 'p:sp') id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:pic') id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:graphicFrame') id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:grpSp') id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:cxnSp') id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+
+        if (id !== undefined && id !== null) {
+          drawingElements.set(String(id), { tag, obj: item })
+        }
+      }
+    }
+
+    // Append items not in the explicit Z-order list
+    const fullZOrder = [...zOrder]
+    for (const id of drawingElements.keys()) {
+      if (!fullZOrder.includes(id)) {
+        fullZOrder.push(id)
+      }
+    }
+
+    // Build children in Z-order
+    let childrenXml = ''
+    for (const id of fullZOrder) {
+      const el = drawingElements.get(id)
+      if (!el) continue
+
+      if (el.tag === 'p:grpSp') {
+        childrenXml += this.serializeContainer(el.obj, 'p:grpSp')
+      } else {
+        childrenXml += this.#builder.build({ [el.tag]: el.obj })
+      }
+    }
+
+    // Container attributes
+    let attrsStr = ''
+    const attrs = {}
+    for (const k in container) {
+      if (k.startsWith('@_')) {
+        attrs[k] = container[k]
+      }
+    }
+    if (Object.keys(attrs).length > 0) {
+      const attrXml = this.#builder.build({ [containerTagName]: { ...attrs } })
+      const match = attrXml.match(/<[^>]+>/)
+      if (match) {
+        attrsStr = match[0].slice(containerTagName.length + 1, -1)
+      }
+    }
+
+    return `<${containerTagName}${attrsStr}>${headerXml}${childrenXml}</${containerTagName}>`
+  }
+
   /**
    * Extracts the XML declaration line from an XML string.
    *
@@ -289,4 +552,5 @@ class XMLParser {
 
 module.exports = {
   XMLParser,
+  Z_ORDER_SYMBOL,
 }

package/src/utils/xmlUtils.js

@@ -1,42 +1,194 @@
 /**
- * @fileoverview XML validation and repair utilities.
+ * @fileoverview XML validation, repair, recovery, and security diagnostics utilities.
  *
- * Provides tools to check if generated XML is well-formed and
- * attempt automatic repairs for common PPTX corruption issues.
+ * Provides tools to check if generated XML is well-formed, protect against
+ * XML Entity Attacks (XXE, DTD abuse, Billion Laughs), and recover diagnostics.
  */
 
+const { XMLValidator } = require('fast-xml-parser')
 const { XMLParser } = require('../parsers/XMLParser.js')
+const { PPTXError } = require('./errors.js')
 
 const parser = new XMLParser()
 
+/**
+ * Helper to compute line and column numbers from a string index.
+ */
+function getLineAndCol(str, index) {
+  let line = 1
+  let col = 1
+  for (let i = 0; i < index; i++) {
+    if (str[i] === '\n') {
+      line++
+      col = 1
+    } else if (str[i] !== '\r') {
+      col++
+    }
+  }
+  return { line, col }
+}
+
+/**
+ * Validates that an XML string is secure and well-formed.
+ * Checks for DTDs, recursive/custom entities, external references (XXE), and malformed tags.
+ *
+ * @param {string} xmlString - Raw XML content.
+ * @returns {{ valid: boolean, error: string|null, line: number|null, column: number|null, recommendation: string|null }}
+ */
+function validateXml(xmlString) {
+  if (typeof xmlString !== 'string') {
+    return {
+      valid: false,
+      error: 'Invalid XML input: expected string.',
+      line: 1,
+      column: 1,
+      recommendation: 'Ensure XML input is passed as a string.',
+    }
+  }
+
+  // 1. Check for external references (XXE)
+  if (/SYSTEM\b/i.test(xmlString) || /PUBLIC\b/i.test(xmlString)) {
+    const match = xmlString.match(/(SYSTEM|PUBLIC)\b/i)
+    const index = match ? match.index : 0
+    const { line, col } = getLineAndCol(xmlString, index)
+    return {
+      valid: false,
+      error: 'External reference SYSTEM/PUBLIC detected',
+      line,
+      column: col,
+      recommendation: 'Remove external system/public identifiers to prevent XXE attacks.',
+    }
+  }
+
+  // 2. Check for entity declarations (prevent custom/recursive entities)
+  if (/<!ENTITY/i.test(xmlString)) {
+    const index = xmlString.search(/<!ENTITY/i)
+    const { line, col } = getLineAndCol(xmlString, index)
+    return {
+      valid: false,
+      error: 'Custom entity declaration detected',
+      line,
+      column: col,
+      recommendation: 'Do not declare custom entities to protect against XML entity injection.',
+    }
+  }
+
+  // 3. Check for DTD / DOCTYPE declarations (DTD abuse, recursive entities, Billion Laughs)
+  if (/<!DOCTYPE/i.test(xmlString)) {
+    const index = xmlString.search(/<!DOCTYPE/i)
+    const { line, col } = getLineAndCol(xmlString, index)
+    return {
+      valid: false,
+      error: 'DTD/DOCTYPE declaration detected: entity expansion limit exceeded / DTD abuse',
+      line,
+      column: col,
+      recommendation:
+        'Remove DOCTYPE declarations or DTD abuse to prevent entity expansion attacks.',
+    }
+  }
+
+  // 4. Check for oversized entity references to prevent DoS (exceeding 50,000 entity references)
+  const entityCount = (xmlString.match(/&[a-zA-Z0-9#x]+;/g) || []).length
+  if (entityCount > 50000) {
+    return {
+      valid: false,
+      error: `Entity expansion limit exceeded: ${entityCount} references (max 50000)`,
+      line: 1,
+      column: 1,
+      recommendation: 'Reduce the density of standard entity references.',
+    }
+  }
+
+  // 5. Well-formedness check using XMLValidator
+  const validation = XMLValidator.validate(xmlString)
+  if (validation !== true) {
+    return {
+      valid: false,
+      error: validation.err.msg || 'Malformed XML',
+      line: validation.err.line || 1,
+      column: validation.err.col || 1,
+      recommendation:
+        'Fix XML syntax errors (unclosed tags, invalid characters, mismatched brackets).',
+    }
+  }
+
+  return {
+    valid: true,
+    error: null,
+    line: null,
+    column: null,
+    recommendation: null,
+  }
+}
+
 /**
  * Validates that an XML string is well-formed.
+ * Backwards compatibility wrapper for original validateXML.
  *
  * @param {string} xmlString - XML to validate.
  * @returns {{ valid: boolean, error: string|null }} Validation result.
- *
- * @example
- * const { valid, error } = validateXML(xml);
- * if (!valid) console.error('XML error:', error);
  */
 function validateXML(xmlString) {
-  return parser.validate(xmlString)
+  const result = validateXml(xmlString)
+  return {
+    valid: result.valid,
+    error: result.error,
+  }
 }
 
 /**
- * Attempts to repair common XML corruption issues in PPTX files.
+ * Safely parses XML with validation, recovery diagnostics, and fallback reporting.
  *
- * Known issues this addresses:
- * 1. Unescaped & in attribute values (e.g., href="a&b" → href="a&amp;b")
- * 2. Unclosed tags (limited heuristic repair)
- * 3. Invalid XML characters (removes control chars below 0x20 except tab/LF/CR)
+ * @param {string} xmlString - Raw XML content.
+ * @param {string} filename - Filename for error reporting context.
+ * @param {XMLParser} [xmlParserInstance] - Optional parser instance.
+ * @returns {Object} Parsed JS object.
+ * @throws {PPTXError} If parsing fails or security limits are violated.
+ */
+function safeParseXml(xmlString, filename = 'unknown.xml', xmlParserInstance = null) {
+  const validation = validateXml(xmlString)
+  if (!validation.valid) {
+    const errorDetails = {
+      file: filename,
+      line: validation.line || 1,
+      column: validation.column || 1,
+      error: validation.error,
+      recommendation: validation.recommendation || 'Malformed entity reference detected',
+    }
+    const err = new PPTXError(`XML parse validation error in ${filename}: ${validation.error}`)
+    err.diagnostic = errorDetails
+    throw err
+  }
+
+  try {
+    const p = xmlParserInstance || parser
+    return p.parse(xmlString, filename)
+  } catch (err) {
+    let line = 1
+    let col = 1
+    const lineMatch = err.message.match(/line:?\s*(\d+)/i) || err.message.match(/:(\d+):\d+$/)
+    const colMatch = err.message.match(/col(umn)?:?\s*(\d+)/i) || err.message.match(/:\d+:(\d+)$/)
+    if (lineMatch) line = parseInt(lineMatch[1], 10)
+    if (colMatch) col = parseInt(colMatch[2] || colMatch[1], 10)
+
+    const errorDetails = {
+      file: filename,
+      line,
+      column: col,
+      error: err.message,
+      recommendation: 'Ensure all XML tags are closed properly and entity syntax is valid.',
+    }
+    const newErr = new PPTXError(`XML parse error in ${filename}: ${err.message}`)
+    newErr.diagnostic = errorDetails
+    throw newErr
+  }
+}
+
+/**
+ * Attempts to repair common XML corruption issues in PPTX files.
  *
  * @param {string} xmlString - Potentially broken XML.
  * @returns {{ xml: string, repaired: boolean, changes: string[] }}
- *
- * @example
- * const { xml, repaired, changes } = repairXML(brokenXml);
- * if (repaired) console.log('Repaired:', changes);
  */
 function repairXML(xmlString) {
   const changes = []
@@ -48,7 +200,6 @@ function repairXML(xmlString) {
   if (xml !== before) changes.push('Removed invalid control characters')
 
   // Fix 2: Fix unescaped ampersands in text content (not in entities)
-  // Match & not followed by valid entity patterns
   const fixedAmp = xml.replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d+;|#x[0-9a-fA-F]+;)/g, '&amp;')
   if (fixedAmp !== xml) {
     xml = fixedAmp
@@ -76,10 +227,6 @@ function repairXML(xmlString) {
 
 /**
  * Checks if an XML string contains a specific element.
- *
- * @param {string} xmlString
- * @param {string} elementName - Element tag name (e.g., 'a:tbl').
- * @returns {boolean}
  */
 function xmlContainsElement(xmlString, elementName) {
   return xmlString.includes(`<${elementName}`) || xmlString.includes(`<${elementName}>`)
@@ -87,10 +234,6 @@ function xmlContainsElement(xmlString, elementName) {
 
 /**
  * Counts occurrences of an element in XML.
- *
- * @param {string} xmlString
- * @param {string} elementName
- * @returns {number}
  */
 function countElements(xmlString, elementName) {
   const pattern = new RegExp(`<${elementName}[\\s>/]`, 'g')
@@ -99,10 +242,6 @@ function countElements(xmlString, elementName) {
 
 /**
  * Extracts all attribute values for a given attribute name.
- *
- * @param {string} xmlString - XML string to search.
- * @param {string} attrName - Attribute name (e.g., 'r:id', 'name').
- * @returns {string[]} Array of attribute values found.
  */
 function extractAttributeValues(xmlString, attrName) {
   const pattern = new RegExp(`${attrName.replace(':', '\\:')}="([^"]*)"`, 'g')
@@ -114,10 +253,126 @@ function extractAttributeValues(xmlString, attrName) {
   return values
 }
 
+/**
+ * Scans an XML string for entity references.
+ *
+ * @param {string} xmlString - XML string to scan.
+ * @returns {{ standard: number, custom: number, numeric: number, hex: number, total: number, entities: string[] }}
+ */
+function scanForEntities(xmlString) {
+  const result = {
+    standard: 0,
+    custom: 0,
+    numeric: 0,
+    hex: 0,
+    total: 0,
+    entities: [],
+  }
+  if (typeof xmlString !== 'string') return result
+
+  const entityRegex = /&[a-zA-Z0-9#x_:-]+;/g
+  const matches = xmlString.match(entityRegex) || []
+  result.total = matches.length
+
+  const standardSet = new Set(['&amp;', '&lt;', '&gt;', '&quot;', '&apos;'])
+
+  matches.forEach(match => {
+    result.entities.push(match)
+    if (standardSet.has(match)) {
+      result.standard++
+    } else if (match.startsWith('&#x')) {
+      result.hex++
+    } else if (match.startsWith('&#')) {
+      result.numeric++
+    } else {
+      result.custom++
+    }
+  })
+
+  return result
+}
+
+/**
+ * Analyzes XML properties.
+ *
+ * @param {string} xmlString - XML content.
+ * @returns {{ sizeBytes: number, lineCount: number, elementCount: number, attributeCount: number, entityStats: Object }}
+ */
+function analyzeXmlFile(xmlString) {
+  if (typeof xmlString !== 'string') {
+    return { sizeBytes: 0, lineCount: 0, elementCount: 0, attributeCount: 0, entityStats: {} }
+  }
+
+  const sizeBytes = Buffer.byteLength(xmlString, 'utf8')
+  const lineCount = xmlString.split('\n').length
+  const elementCount = (xmlString.match(/<[a-zA-Z0-9_:-]+/g) || []).length
+  const attributeCount = (xmlString.match(/\s[a-zA-Z0-9_:-]+=/g) || []).length
+  const entityStats = scanForEntities(xmlString)
+
+  return {
+    sizeBytes,
+    lineCount,
+    elementCount,
+    attributeCount,
+    entityStats,
+  }
+}
+
+/**
+ * Reports complexity indicators of the XML document.
+ *
+ * @param {string} xmlString - XML content.
+ * @returns {{ maxDepth: number, nodeCount: number, ratioTextToMarkup: number }}
+ */
+function reportXmlComplexity(xmlString) {
+  if (typeof xmlString !== 'string') {
+    return { maxDepth: 0, nodeCount: 0, ratioTextToMarkup: 0 }
+  }
+
+  let currentDepth = 0
+  let maxDepth = 0
+  let nodeCount = 0
+
+  const tagRegex = /<\/?([a-zA-Z0-9_:-]+)(\s[^>]*)*>/g
+  let match
+  while ((match = tagRegex.exec(xmlString)) !== null) {
+    const rawTag = match[0]
+    nodeCount++
+    if (rawTag.startsWith('</')) {
+      currentDepth--
+    } else if (rawTag.endsWith('/>')) {
+      if (currentDepth + 1 > maxDepth) {
+        maxDepth = currentDepth + 1
+      }
+    } else {
+      currentDepth++
+      if (currentDepth > maxDepth) {
+        maxDepth = currentDepth
+      }
+    }
+  }
+
+  const textOnly = xmlString.replace(/<[^>]+>/g, '')
+  const textLength = textOnly.length
+  const xmlLength = xmlString.length
+  const ratioTextToMarkup = xmlLength > 0 ? parseFloat((textLength / xmlLength).toFixed(4)) : 0
+
+  return {
+    maxDepth,
+    nodeCount,
+    ratioTextToMarkup,
+  }
+}
+
 module.exports = {
+  validateXml,
   validateXML,
+  safeParseXml,
   repairXML,
   xmlContainsElement,
   countElements,
   extractAttributeValues,
+  scanForEntities,
+  analyzeXmlFile,
+  reportXmlComplexity,
 }