// 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(xtof): 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 fromConstant}, {@code fromConstants}, {@code format} or {@code * formatWithParams}), 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 {!Object} * @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: * *
 * 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.
 * 
* * @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 + '\' of type ' + goog.typeOf(trustedResourceUrl)); return 'type_error:TrustedResourceUrl'; } }; /** * Creates a TrustedResourceUrl from a format string and arguments. * * The arguments for interpolation into the format string map labels to values. * Values of type `goog.string.Const` are interpolated without modifcation. * Values of other types are cast to string and encoded with * encodeURIComponent. * * `%{