Source: lib/util/xml_utils.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.XmlUtils');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.util.Lazy');
  12. goog.require('shaka.util.StringUtils');
  15. /**
  16.  * @summary A set of XML utility functions.
  17.  */
  18. shaka.util.XmlUtils = class {
  19.   /**
  20.    * Finds a child XML element.
  21.    * @param {!Node} elem The parent XML element.
  22.    * @param {string} name The child XML element's tag name.
  23.    * @return {Element} The child XML element, or null if a child XML element
  24.    *   does not exist with the given tag name OR if there exists more than one
  25.    *   child XML element with the given tag name.
  26.    */
  27.   static findChild(elem, name) {
  28.     const children = shaka.util.XmlUtils.findChildren(elem, name);
  29.     if (children.length != 1) {
  30.       return null;
  31.     }
  32.     return children[0];
  33.   }
  36.   /**
  37.    * Finds a namespace-qualified child XML element.
  38.    * @param {!Node} elem The parent XML element.
  39.    * @param {string} ns The child XML element's namespace URI.
  40.    * @param {string} name The child XML element's local name.
  41.    * @return {Element} The child XML element, or null if a child XML element
  42.    *   does not exist with the given tag name OR if there exists more than one
  43.    *   child XML element with the given tag name.
  44.    */
  45.   static findChildNS(elem, ns, name) {
  46.     const children = shaka.util.XmlUtils.findChildrenNS(elem, ns, name);
  47.     if (children.length != 1) {
  48.       return null;
  49.     }
  50.     return children[0];
  51.   }
  54.   /**
  55.    * Finds child XML elements.
  56.    * @param {!Node} elem The parent XML element.
  57.    * @param {string} name The child XML element's tag name.
  58.    * @return {!Array.<!Element>} The child XML elements.
  59.    */
  60.   static findChildren(elem, name) {
  61.     const found = [];
  62.     for (const child of elem.childNodes) {
  63.       if (child instanceof Element && child.tagName == name) {
  64.         found.push(child);
  65.       }
  66.     }
  67.     return found;
  68.   }
  71.   /**
  72.    * @param {!Node} elem the parent XML element.
  73.    * @return {!Array.<!Element>} The child XML elements.
  74.    */
  75.   static getChildren(elem) {
  76.     return Array.from(elem.childNodes).filter((child) => {
  77.       return child instanceof Element;
  78.     });
  79.   }
  82.   /**
  83.    * Finds namespace-qualified child XML elements.
  84.    * @param {!Node} elem The parent XML element.
  85.    * @param {string} ns The child XML element's namespace URI.
  86.    * @param {string} name The child XML element's local name.
  87.    * @return {!Array.<!Element>} The child XML elements.
  88.    */
  89.   static findChildrenNS(elem, ns, name) {
  90.     const found = [];
  91.     for (const child of elem.childNodes) {
  92.       if (child instanceof Element && child.localName == name &&
  93.           child.namespaceURI == ns) {
  94.         found.push(child);
  95.       }
  96.     }
  97.     return found;
  98.   }
  101.   /**
  102.    * Gets a namespace-qualified attribute.
  103.    * @param {!Element} elem The element to get from.
  104.    * @param {string} ns The namespace URI.
  105.    * @param {string} name The local name of the attribute.
  106.    * @return {?string} The attribute's value, or null if not present.
  107.    */
  108.   static getAttributeNS(elem, ns, name) {
  109.     // Some browsers return the empty string when the attribute is missing,
  110.     // so check if it exists first.  See: https://mzl.la/2L7F0UK
  111.     return elem.hasAttributeNS(ns, name) ? elem.getAttributeNS(ns, name) : null;
  112.   }
  115.   /**
  116.    * Gets a namespace-qualified attribute.
  117.    * @param {!Element} elem The element to get from.
  118.    * @param {!Array.<string>} nsList The lis of namespace URIs.
  119.    * @param {string} name The local name of the attribute.
  120.    * @return {?string} The attribute's value, or null if not present.
  121.    */
  122.   static getAttributeNSList(elem, nsList, name) {
  123.     // Some browsers return the empty string when the attribute is missing,
  124.     // so check if it exists first.  See: https://mzl.la/2L7F0UK
  125.     for (const ns of nsList) {
  126.       if (elem.hasAttributeNS(ns, name)) {
  127.         return elem.getAttributeNS(ns, name);
  128.       }
  129.     }
  130.     return null;
  131.   }
  134.   /**
  135.    * Gets the text contents of a node.
  136.    * @param {!Node} elem The XML element.
  137.    * @return {?string} The text contents, or null if there are none.
  138.    */
  139.   static getContents(elem) {
  140.     const XmlUtils = shaka.util.XmlUtils;
  141.     if (!Array.from(elem.childNodes).every(XmlUtils.isText)) {
  142.       return null;
  143.     }
  145.     // Read merged text content from all text nodes.
  146.     return elem.textContent.trim();
  147.   }
  149.   /**
  150.    * Checks if a node is of type text.
  151.    * @param {!Node} elem The XML element.
  152.    * @return {boolean} True if it is a text node.
  153.    */
  154.   static isText(elem) {
  155.     return elem.nodeType == Node.TEXT_NODE ||
  156.         elem.nodeType == Node.CDATA_SECTION_NODE;
  157.   }
  159.   /**
  160.    * Parses an attribute by its name.
  161.    * @param {!Element} elem The XML element.
  162.    * @param {string} name The attribute name.
  163.    * @param {function(string): (T|null)} parseFunction A function that parses
  164.    *   the attribute.
  165.    * @param {(T|null)=} defaultValue The attribute's default value, if not
  166.    *   specified, the attibute's default value is null.
  167.    * @return {(T|null)} The parsed attribute on success, or the attribute's
  168.    *   default value if the attribute does not exist or could not be parsed.
  169.    * @template T
  170.    */
  171.   static parseAttr(
  172.       elem, name, parseFunction, defaultValue = null) {
  173.     let parsedValue = null;
  175.     const value = elem.getAttribute(name);
  176.     if (value != null) {
  177.       parsedValue = parseFunction(value);
  178.     }
  179.     return parsedValue == null ? defaultValue : parsedValue;
  180.   }
  183.   /**
  184.    * Parses an XML date string.
  185.    * @param {string} dateString
  186.    * @return {?number} The parsed date in seconds on success; otherwise, return
  187.    *   null.
  188.    */
  189.   static parseDate(dateString) {
  190.     if (!dateString) {
  191.       return null;
  192.     }
  194.     // Times in the manifest should be in UTC. If they don't specify a timezone,
  195.     // Date.parse() will use the local timezone instead of UTC.  So manually add
  196.     // the timezone if missing ('Z' indicates the UTC timezone).
  197.     // Format: YYYY-MM-DDThh:mm:ss.ssssss
  198.     if (/^\d+-\d+-\d+T\d+:\d+:\d+(\.\d+)?$/.test(dateString)) {
  199.       dateString += 'Z';
  200.     }
  202.     const result = Date.parse(dateString);
  203.     return isNaN(result) ? null : (result / 1000.0);
  204.   }
  207.   /**
  208.    * Parses an XML duration string.
  209.    * Negative values are not supported. Years and months are treated as exactly
  210.    * 365 and 30 days respectively.
  211.    * @param {string} durationString The duration string, e.g., "PT1H3M43.2S",
  212.    *   which means 1 hour, 3 minutes, and 43.2 seconds.
  213.    * @return {?number} The parsed duration in seconds on success; otherwise,
  214.    *   return null.
  215.    * @see {@link http://www.datypic.com/sc/xsd/t-xsd_duration.html}
  216.    */
  217.   static parseDuration(durationString) {
  218.     if (!durationString) {
  219.       return null;
  220.     }
  222.     const re = '^P(?:([0-9]*)Y)?(?:([0-9]*)M)?(?:([0-9]*)D)?' +
  223.              '(?:T(?:([0-9]*)H)?(?:([0-9]*)M)?(?:([0-9.]*)S)?)?$';
  224.     const matches = new RegExp(re).exec(durationString);
  226.     if (!matches) {
  227.       shaka.log.warning('Invalid duration string:', durationString);
  228.       return null;
  229.     }
  231.     // Note: Number(null) == 0 but Number(undefined) == NaN.
  232.     const years = Number(matches[1] || null);
  233.     const months = Number(matches[2] || null);
  234.     const days = Number(matches[3] || null);
  235.     const hours = Number(matches[4] || null);
  236.     const minutes = Number(matches[5] || null);
  237.     const seconds = Number(matches[6] || null);
  239.     // Assume a year always has 365 days and a month always has 30 days.
  240.     const d = (60 * 60 * 24 * 365) * years +
  241.             (60 * 60 * 24 * 30) * months +
  242.             (60 * 60 * 24) * days +
  243.             (60 * 60) * hours +
  244.             60 * minutes +
  245.             seconds;
  246.     return isFinite(d) ? d : null;
  247.   }
  250.   /**
  251.    * Parses a range string.
  252.    * @param {string} rangeString The range string, e.g., "101-9213".
  253.    * @return {?{start: number, end: number}} The parsed range on success;
  254.    *   otherwise, return null.
  255.    */
  256.   static parseRange(rangeString) {
  257.     const matches = /([0-9]+)-([0-9]+)/.exec(rangeString);
  259.     if (!matches) {
  260.       return null;
  261.     }
  263.     const start = Number(matches[1]);
  264.     if (!isFinite(start)) {
  265.       return null;
  266.     }
  268.     const end = Number(matches[2]);
  269.     if (!isFinite(end)) {
  270.       return null;
  271.     }
  273.     return {start: start, end: end};
  274.   }
  277.   /**
  278.    * Parses an integer.
  279.    * @param {string} intString The integer string.
  280.    * @return {?number} The parsed integer on success; otherwise, return null.
  281.    */
  282.   static parseInt(intString) {
  283.     const n = Number(intString);
  284.     return (n % 1 === 0) ? n : null;
  285.   }
  288.   /**
  289.    * Parses a positive integer.
  290.    * @param {string} intString The integer string.
  291.    * @return {?number} The parsed positive integer on success; otherwise,
  292.    *   return null.
  293.    */
  294.   static parsePositiveInt(intString) {
  295.     const n = Number(intString);
  296.     return (n % 1 === 0) && (n > 0) ? n : null;
  297.   }
  300.   /**
  301.    * Parses a non-negative integer.
  302.    * @param {string} intString The integer string.
  303.    * @return {?number} The parsed non-negative integer on success; otherwise,
  304.    *   return null.
  305.    */
  306.   static parseNonNegativeInt(intString) {
  307.     const n = Number(intString);
  308.     return (n % 1 === 0) && (n >= 0) ? n : null;
  309.   }
  312.   /**
  313.    * Parses a floating point number.
  314.    * @param {string} floatString The floating point number string.
  315.    * @return {?number} The parsed floating point number on success; otherwise,
  316.    *   return null. May return -Infinity or Infinity.
  317.    */
  318.   static parseFloat(floatString) {
  319.     const n = Number(floatString);
  320.     return !isNaN(n) ? n : null;
  321.   }
  324.   /**
  325.    * Parses a boolean.
  326.    * @param {string} booleanString The boolean string.
  327.    * @return {boolean} The boolean
  328.    */
  329.   static parseBoolean(booleanString) {
  330.     if (!booleanString) {
  331.       return false;
  332.     }
  333.     return booleanString.toLowerCase() === 'true';
  334.   }
  337.   /**
  338.    * Evaluate a division expressed as a string.
  339.    * @param {string} exprString
  340.    *   The expression to evaluate, e.g. "200/2". Can also be a single number.
  341.    * @return {?number} The evaluated expression as floating point number on
  342.    *   success; otherwise return null.
  343.    */
  344.   static evalDivision(exprString) {
  345.     let res;
  346.     let n;
  347.     if ((res = exprString.match(/^(\d+)\/(\d+)$/))) {
  348.       n = Number(res[1]) / Number(res[2]);
  349.     } else {
  350.       n = Number(exprString);
  351.     }
  352.     return !isNaN(n) ? n : null;
  353.   }
  356.   /**
  357.    * Parse a string and return the resulting root element if it was valid XML.
  358.    *
  359.    * @param {string} xmlString
  360.    * @param {string} expectedRootElemName
  361.    * @return {Element}
  362.    */
  363.   static parseXmlString(xmlString, expectedRootElemName) {
  364.     const parser = new DOMParser();
  365.     const unsafeXmlString =
  366.         shaka.util.XmlUtils.trustedHTMLFromString_.value()(xmlString);
  367.     let unsafeXml = null;
  368.     try {
  369.       unsafeXml = parser.parseFromString(unsafeXmlString, 'text/xml');
  370.     } catch (exception) {
  371.       shaka.log.error('XML parsing exception:', exception);
  372.       return null;
  373.     }
  375.     // According to MDN, parseFromString never returns null.
  376.     goog.asserts.assert(unsafeXml, 'Parsed XML document cannot be null!');
  378.     // Check for empty documents.
  379.     const rootElem = unsafeXml.documentElement;
  380.     if (!rootElem) {
  381.       shaka.log.error('XML document was empty!');
  382.       return null;
  383.     }
  385.     // Check for parser errors.
  386.     const parserErrorElements = rootElem.getElementsByTagName('parsererror');
  387.     if (parserErrorElements.length) {
  388.       shaka.log.error('XML parser error found:', parserErrorElements[0]);
  389.       return null;
  390.     }
  392.     // The top-level element in the loaded XML should have the name we expect.
  393.     if (rootElem.tagName != expectedRootElemName) {
  394.       shaka.log.error(
  395.           `XML tag name does not match expected "${expectedRootElemName}":`,
  396.           rootElem.tagName);
  397.       return null;
  398.     }
  400.     // SECURITY: Verify that the document does not contain elements from the
  401.     // HTML or SVG namespaces, which could trigger script execution and XSS.
  402.     const iterator = document.createNodeIterator(
  403.         unsafeXml,
  404.         NodeFilter.SHOW_ALL,
  405.     );
  406.     let currentNode;
  407.     while (currentNode = iterator.nextNode()) {
  408.       if (currentNode instanceof HTMLElement ||
  409.           currentNode instanceof SVGElement) {
  410.         shaka.log.error('XML document embeds unsafe content!');
  411.         return null;
  412.       }
  413.     }
  415.     return rootElem;
  416.   }
  419.   /**
  420.    * Parse some data (auto-detecting the encoding) and return the resulting
  421.    * root element if it was valid XML.
  422.    * @param {BufferSource} data
  423.    * @param {string} expectedRootElemName
  424.    * @return {Element}
  425.    */
  426.   static parseXml(data, expectedRootElemName) {
  427.     try {
  428.       const string = shaka.util.StringUtils.fromBytesAutoDetect(data);
  429.       return shaka.util.XmlUtils.parseXmlString(string, expectedRootElemName);
  430.     } catch (exception) {
  431.       shaka.log.error('parseXmlString threw!', exception);
  432.       return null;
  433.     }
  434.   }
  435. };
  437. /**
  438.  * Promote a string to TrustedHTML. This function is security-sensitive and
  439.  * should only be used with security approval where the string is guaranteed not
  440.  * to cause an XSS vulnerability.
  441.  *
  442.  * @private {!shaka.util.Lazy.<function(!string): (!TrustedHTML|!string)>}
  443.  */
  444. shaka.util.XmlUtils.trustedHTMLFromString_ = new shaka.util.Lazy(() => {
  445.   if (typeof trustedTypes !== 'undefined') {
  446.     // Create a Trusted Types policy for promoting the string to TrustedHTML.
  447.     // The Lazy wrapper ensures this policy is only created once.
  448.     const policy = trustedTypes.createPolicy('shaka-player#xml', {
  449.       createHTML: (s) => s,
  450.     });
  451.     return (s) => policy.createHTML(s);
  452.   }
  453.   // Fall back to strings in environments that don't support Trusted Types.
  454.   return (s) => s;
  455. });