initial commit

js/goog/html/safescript.js

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * Copyright The Closure Library Authors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The SafeScript type and its builders.
+ *
+ * TODO(xtof): Link to document stating type contract.
+ */
+
+goog.module('goog.html.SafeScript');
+goog.module.declareLegacyNamespace();
+
+const Const = goog.require('goog.string.Const');
+const TypedString = goog.require('goog.string.TypedString');
+const trustedtypes = goog.require('goog.html.trustedtypes');
+const {fail} = goog.require('goog.asserts');
+
+/**
+ * Token used to ensure that object is created only from this file. No code
+ * outside of this file can access this token.
+ * @const {!Object}
+ */
+const CONSTRUCTOR_TOKEN_PRIVATE = {};
+
+/**
+ * A string-like object which represents JavaScript code and that carries the
+ * security type contract that its value, as a string, will not cause execution
+ * of unconstrained attacker controlled code (XSS) when evaluated as JavaScript
+ * in a browser.
+ *
+ * Instances of this type must be created via the factory method
+ * `SafeScript.fromConstant` and not by invoking its constructor. The
+ * constructor intentionally takes an extra parameter that cannot be constructed
+ * outside of this file and the type is immutable; hence only a default instance
+ * corresponding to the empty string can be obtained via constructor invocation.
+ *
+ * A SafeScript's string representation can safely be interpolated as the
+ * content of a script element within HTML. The SafeScript string should not be
+ * escaped before interpolation.
+ *
+ * Note that the SafeScript might contain text that is attacker-controlled but
+ * that text should have been interpolated with appropriate escaping,
+ * sanitization and/or validation into the right location in the script, such
+ * that it is highly constrained in its effect (for example, it had to match a
+ * set of whitelisted words).
+ *
+ * A SafeScript can be constructed via security-reviewed unchecked
+ * conversions. In this case producers of SafeScript must ensure themselves that
+ * the SafeScript does not contain unsafe script. Note in particular that
+ * `<` is dangerous, even when inside JavaScript strings, and so should
+ * always be forbidden or JavaScript escaped in user controlled input. For
+ * example, if `</script><script>evil</script>"` were
+ * interpolated inside a JavaScript string, it would break out of the context
+ * of the original script element and `evil` would execute. Also note
+ * that within an HTML script (raw text) element, HTML character references,
+ * such as "<" are not allowed. See
+ * http://www.w3.org/TR/html5/scripting-1.html#restrictions-for-contents-of-script-elements.
+ * Creating SafeScript objects HAS SIDE-EFFECTS due to calling Trusted Types Web
+ * API.
+ *
+ * @see SafeScript#fromConstant
+ * @final
+ * @implements {TypedString}
+ */
+class SafeScript {
+  /**
+   * @param {!TrustedScript|string} value
+   * @param {!Object} token package-internal implementation detail.
+   */
+  constructor(value, token) {
+    /**
+     * The contained value of this SafeScript.  The field has a purposely ugly
+     * name to make (non-compiled) code that attempts to directly access this
+     * field stand out.
+     * @private {!TrustedScript|string}
+     */
+    this.privateDoNotAccessOrElseSafeScriptWrappedValue_ =
+        (token === CONSTRUCTOR_TOKEN_PRIVATE) ? value : '';
+
+    /**
+     * @override
+     * @const
+     */
+    this.implementsGoogStringTypedString = true;
+  }
+
+  /**
+   * Creates a SafeScript object from a compile-time constant string.
+   *
+   * @param {!Const} script A compile-time-constant string from which to create
+   *     a SafeScript.
+   * @return {!SafeScript} A SafeScript object initialized to `script`.
+   */
+  static fromConstant(script) {
+    const scriptString = Const.unwrap(script);
+    if (scriptString.length === 0) {
+      return SafeScript.EMPTY;
+    }
+    return SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse(
+        scriptString);
+  }
+
+  /**
+   * Creates a SafeScript JSON representation from anything that could be passed
+   * to JSON.stringify.
+   * @param {*} val
+   * @return {!SafeScript}
+   */
+  static fromJson(val) {
+    return SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse(
+        SafeScript.stringify_(val));
+  }
+
+  /**
+   * Returns this SafeScript's value as a string.
+   *
+   * IMPORTANT: In code where it is security relevant that an object's type is
+   * indeed `SafeScript`, use `SafeScript.unwrap` instead of
+   * this method. If in doubt, assume that it's security relevant. In
+   * particular, note that goog.html functions which return a goog.html type do
+   * not guarantee the returned instance is of the right type. For example:
+   *
+   * <pre>
+   * var fakeSafeHtml = new String('fake');
+   * fakeSafeHtml.__proto__ = goog.html.SafeHtml.prototype;
+   * var newSafeHtml = goog.html.SafeHtml.htmlEscape(fakeSafeHtml);
+   * // newSafeHtml is just an alias for fakeSafeHtml, it's passed through by
+   * // goog.html.SafeHtml.htmlEscape() as fakeSafeHtml
+   * // instanceof goog.html.SafeHtml.
+   * </pre>
+   *
+   * @see SafeScript#unwrap
+   * @override
+   */
+  getTypedStringValue() {
+    return this.privateDoNotAccessOrElseSafeScriptWrappedValue_.toString();
+  }
+
+  /**
+   * Performs a runtime check that the provided object is indeed a
+   * SafeScript object, and returns its value.
+   *
+   * @param {!SafeScript} safeScript The object to extract from.
+   * @return {string} The safeScript object's contained string, unless
+   *     the run-time type check fails. In that case, `unwrap` returns an
+   *     innocuous string, or, if assertions are enabled, throws
+   *     `asserts.AssertionError`.
+   */
+  static unwrap(safeScript) {
+    return SafeScript.unwrapTrustedScript(safeScript).toString();
+  }
+
+  /**
+   * Unwraps value as TrustedScript if supported or as a string if not.
+   * @param {!SafeScript} safeScript
+   * @return {!TrustedScript|string}
+   * @see SafeScript.unwrap
+   */
+  static unwrapTrustedScript(safeScript) {
+    // Perform additional Run-time type-checking to ensure that
+    // safeScript is indeed an instance of the expected type.  This
+    // provides some additional protection against security bugs due to
+    // application code that disables type checks.
+    // Specifically, the following checks are performed:
+    // 1. The object is an instance of the expected type.
+    // 2. The object is not an instance of a subclass.
+    if (safeScript instanceof SafeScript &&
+        safeScript.constructor === SafeScript) {
+      return safeScript.privateDoNotAccessOrElseSafeScriptWrappedValue_;
+    } else {
+      fail(
+          'expected object of type SafeScript, got \'' + safeScript +
+          '\' of type ' + goog.typeOf(safeScript));
+      return 'type_error:SafeScript';
+    }
+  }
+
+  /**
+   * Converts the given value to an embeddable JSON string and returns it. The
+   * resulting string can be embedded in HTML because the '<' character is
+   * encoded.
+   *
+   * @param {*} val
+   * @return {string}
+   * @private
+   */
+  static stringify_(val) {
+    const json = JSON.stringify(val);
+    return json.replace(/</g, '\\x3c');
+  }
+
+  /**
+   * Package-internal utility method to create SafeScript instances.
+   *
+   * @param {string} script The string to initialize the SafeScript object with.
+   * @return {!SafeScript} The initialized SafeScript object.
+   * @package
+   */
+  static createSafeScriptSecurityPrivateDoNotAccessOrElse(script) {
+    const policy = trustedtypes.getPolicyPrivateDoNotAccessOrElse();
+    const trustedScript = policy ? policy.createScript(script) : script;
+    return new SafeScript(trustedScript, CONSTRUCTOR_TOKEN_PRIVATE);
+  }
+}
+
+/**
+ * Returns a string-representation of this value.
+ *
+ * To obtain the actual string value wrapped in a SafeScript, use
+ * `SafeScript.unwrap`.
+ *
+ * @return {string}
+ * @see SafeScript#unwrap
+ * @override
+ */
+SafeScript.prototype.toString = function() {
+  return this.privateDoNotAccessOrElseSafeScriptWrappedValue_.toString();
+};
+
+
+/**
+ * A SafeScript instance corresponding to the empty string.
+ * @const {!SafeScript}
+ */
+SafeScript.EMPTY = /** @type {!SafeScript} */ ({
+  // NOTE: this compiles to nothing, but hides the possible side effect of
+  // SafeScript creation (due to calling trustedTypes.createPolicy) from the
+  // compiler so that the entire call can be removed if the result is not used.
+  valueOf: function() {
+    return SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse('');
+  },
+}.valueOf());
+
+
+exports = SafeScript;