text: // Copyright 2013 The Closure Library Authors. All Rights Reserved.
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //      http://www.apache.org/licenses/LICENSE-2.0
  //
  // Unless required by applicable law or agreed to in writing, software
  // distributed under the License is distributed on an "AS-IS" BASIS,
  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  // See the License for the specific language governing permissions and
  // limitations under the License.
  
  /**
   * @fileoverview The TrustedResourceUrl type and its builders.
   *
   * TODO(user): Link to document stating type contract.
   */
  
  goog.provide('goog.html.TrustedResourceUrl');
  
  goog.require('goog.asserts');
  goog.require('goog.i18n.bidi.Dir');
  goog.require('goog.i18n.bidi.DirectionalString');
  goog.require('goog.string.Const');
  goog.require('goog.string.TypedString');
  
  
  
  /**
   * A URL which is under application control and from which script, CSS, and
   * other resources that represent executable code, can be fetched.
   *
   * Given that the URL can only be constructed from strings under application
   * control and is used to load resources, bugs resulting in a malformed URL
   * should not have a security impact and are likely to be easily detectable
   * during testing. Given the wide number of non-RFC compliant URLs in use,
   * stricter validation could prevent some applications from being able to use
   * this type.
   *
   * Instances of this type must be created via the factory method,
   * ({@code goog.html.TrustedResourceUrl.fromConstant}), and not by invoking its
   * constructor. The constructor intentionally takes no parameters and the type
   * is immutable; hence only a default instance corresponding to the empty
   * string can be obtained via constructor invocation.
   *
   * @see goog.html.TrustedResourceUrl#fromConstant
   * @constructor
   * @final
   * @struct
   * @implements {goog.i18n.bidi.DirectionalString}
   * @implements {goog.string.TypedString}
   */
  goog.html.TrustedResourceUrl = function() {
    /**
     * The contained value of this TrustedResourceUrl.  The field has a purposely
     * ugly name to make (non-compiled) code that attempts to directly access this
     * field stand out.
     * @private {string}
     */
    this.privateDoNotAccessOrElseTrustedResourceUrlWrappedValue_ = '';
  
    /**
     * A type marker used to implement additional run-time type checking.
     * @see goog.html.TrustedResourceUrl#unwrap
     * @const
     * @private
     */
    this.TRUSTED_RESOURCE_URL_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ =
        goog.html.TrustedResourceUrl.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_;
  };
  
  
  /**
   * @override
   * @const
   */
  goog.html.TrustedResourceUrl.prototype.implementsGoogStringTypedString = true;
  
  
  /**
   * Returns this TrustedResourceUrl's value as a string.
   *
   * IMPORTANT: In code where it is security relevant that an object's type is
   * indeed {@code TrustedResourceUrl}, use
   * {@code goog.html.TrustedResourceUrl.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 that
   * 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 goog.html.TrustedResourceUrl#unwrap
   * @override
   */
  goog.html.TrustedResourceUrl.prototype.getTypedStringValue = function() {
    return this.privateDoNotAccessOrElseTrustedResourceUrlWrappedValue_;
  };
  
  
  /**
   * @override
   * @const
   */
  goog.html.TrustedResourceUrl.prototype.implementsGoogI18nBidiDirectionalString =
      true;
  
  
  /**
   * Returns this URLs directionality, which is always {@code LTR}.
   * @override
   */
  goog.html.TrustedResourceUrl.prototype.getDirection = function() {
    return goog.i18n.bidi.Dir.LTR;
  };
  
  
  if (goog.DEBUG) {
    /**
     * Returns a debug string-representation of this value.
     *
     * To obtain the actual string value wrapped in a TrustedResourceUrl, use
     * {@code goog.html.TrustedResourceUrl.unwrap}.
     *
     * @see goog.html.TrustedResourceUrl#unwrap
     * @override
     */
    goog.html.TrustedResourceUrl.prototype.toString = function() {
      return 'TrustedResourceUrl{' +
          this.privateDoNotAccessOrElseTrustedResourceUrlWrappedValue_ + '}';
    };
  }
  
  
  /**
   * Performs a runtime check that the provided object is indeed a
   * TrustedResourceUrl object, and returns its value.
   *
   * @param {!goog.html.TrustedResourceUrl} trustedResourceUrl The object to
   *     extract from.
   * @return {string} The trustedResourceUrl object's contained string, unless
   *     the run-time type check fails. In that case, {@code unwrap} returns an
   *     innocuous string, or, if assertions are enabled, throws
   *     {@code goog.asserts.AssertionError}.
   */
  goog.html.TrustedResourceUrl.unwrap = function(trustedResourceUrl) {
    // Perform additional Run-time type-checking to ensure that
    // trustedResourceUrl 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.
    // 3. The object carries a type marker for the expected type. "Faking" an
    // object requires a reference to the type marker, which has names intended
    // to stand out in code reviews.
    if (trustedResourceUrl instanceof goog.html.TrustedResourceUrl &&
        trustedResourceUrl.constructor === goog.html.TrustedResourceUrl &&
        trustedResourceUrl
            .TRUSTED_RESOURCE_URL_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ ===
                goog.html.TrustedResourceUrl
                    .TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_) {
      return trustedResourceUrl
          .privateDoNotAccessOrElseTrustedResourceUrlWrappedValue_;
    } else {
      goog.asserts.fail('expected object of type TrustedResourceUrl, got \'' +
                        trustedResourceUrl + '\'');
      return 'type_error:TrustedResourceUrl';
  
    }
  };
  
  
  /**
   * Creates a TrustedResourceUrl object from a compile-time constant string.
   *
   * Compile-time constant strings are inherently program-controlled and hence
   * trusted.
   *
   * @param {!goog.string.Const} url A compile-time-constant string from which to
   *     create a TrustedResourceUrl.
   * @return {!goog.html.TrustedResourceUrl} A TrustedResourceUrl object
   *     initialized to {@code url}.
   */
  goog.html.TrustedResourceUrl.fromConstant = function(url) {
    return goog.html.TrustedResourceUrl
        .createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse(
            goog.string.Const.unwrap(url));
  };
  
  
  /**
   * Type marker for the TrustedResourceUrl type, used to implement additional
   * run-time type checking.
   * @const
   * @private
   */
  goog.html.TrustedResourceUrl.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ = {};
  
  
  /**
   * Package-internal utility method to create TrustedResourceUrl instances.
   *
   * @param {string} url The string to initialize the TrustedResourceUrl object
   *     with.
   * @return {!goog.html.TrustedResourceUrl} The initialized TrustedResourceUrl
   *     object.
   * @package
   */
  goog.html.TrustedResourceUrl.
      createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse = function(url) {
    var trustedResourceUrl = new goog.html.TrustedResourceUrl();
    trustedResourceUrl.privateDoNotAccessOrElseTrustedResourceUrlWrappedValue_ =
        url;
    return trustedResourceUrl;
  };
  