html.SafeUrl Extends
A string that is safe to use in URL context in DOM APIs and HTML documents. A SafeUrl is a string-like object that carries the security type contract that its value as a string will not cause untrusted script execution when evaluated as a hyperlink URL in a browser. Values of this type are guaranteed to be safe to use in URL/hyperlink contexts, such as, assignment to URL-valued DOM properties, or interpolation into a HTML template in URL context (e.g., inside a href attribute), in the sense that the use will not result in a Cross-Site-Scripting vulnerability. Note that, as documented in goog.html.SafeUrl.unwrap, this type's contract does not guarantee that instances are safe to interpolate into HTML without appropriate escaping. Note also that this type's contract does not imply any guarantees regarding the resource the URL refers to. In particular, SafeUrls are not safe to use in a context where the referred-to resource is interpreted as trusted code, e.g., as the src of a script tag. Instances of this type must be created via the factory methods ( goog.html.SafeUrl.from, goog.html.SafeUrl.sanitize), etc 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.

Inheritance

Constructor

goog.html.SafeUrl()

Instance Methods

Public Protected Private
getDirection()
Returns this URLs directionality, which is always LTR.
code »
getTypedStringValue()
Returns this SafeUrl's value a string. IMPORTANT: In code where it is security relevant that an object's type is indeed SafeUrl, use goog.html.SafeUrl.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.
IMPORTANT: The guarantees of the SafeUrl type contract only extend to the behavior of browsers when interpreting URLs. Values of SafeUrl objects MUST be appropriately escaped before embedding in a HTML document. Note that the required escaping is context-sensitive (e.g. a different escaping is required for embedding a URL in a style property within a style attribute, as opposed to embedding in a href attribute).
code »
toString()
Returns a debug string-representation of this value. To obtain the actual string value wrapped in a SafeUrl, use goog.html.SafeUrl.unwrap.
code »

Instance Properties

SAFE_URL_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ :
A type marker used to implement additional run-time type checking.
Code »
implementsGoogI18nBidiDirectionalString :
No description.
Code »
implementsGoogStringTypedString :
No description.
Code »
privateDoNotAccessOrElseSafeHtmlWrappedValue_ :
The contained value of this SafeUrl. The field has a purposely ugly name to make (non-compiled) code that attempts to directly access this field stand out.
Code »

Static Methods

goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse_(url) !goog.html.SafeUrl
Utility method to create SafeUrl instances. This function is considered "package private", i.e. calls (using "suppress visibility") from other files within this package are considered acceptable. DO NOT call this function from outside the goog.html package; use appropriate wrappers instead.
Arguments:
url : string
The string to initialize the SafeUrl object with.
Returns: !goog.html.SafeUrl  The initialized SafeUrl object.
code »
goog.html.SafeUrl.fromConstant(url) !goog.html.SafeUrl
Creates a SafeUrl object from a compile-time constant string. Compile-time constant strings are inherently program-controlled and hence trusted.
Arguments:
url : !goog.string.Const
A compile-time-constant string from which to create a SafeUrl.
Returns: !goog.html.SafeUrl  A SafeUrl object initialized to url.
code »
goog.html.SafeUrl.normalize_(url) string
Normalizes url the UTF-8 encoding of url, using a whitelist of characters. Whitelisted characters are not percent-encoded.
Arguments:
url : string
The URL to normalize.
Returns: string  The normalized URL.
code »
goog.html.SafeUrl.sanitize(url) !goog.html.SafeUrl
Creates a SafeUrl object from url. If url is a goog.html.SafeUrl then it is simply returned. Otherwise the input string is validated to match a pattern of commonly used safe URLs. The string is converted to UTF-8 and non-whitelisted characters are percent-encoded. The string wrapped by the created SafeUrl will thus contain only ASCII printable characters. url may be a URL with the http, https, or mailto scheme, or a relative URL (i.e., a URL without a scheme; specifically, a scheme-relative, absolute-path-relative, or path-relative URL). url is converted to UTF-8 and non-whitelisted characters are percent-encoded. Whitelisted characters are '%' and, from RFC 3986, unreserved characters and reserved characters, with the exception of '\'', '(' and ')'. This ensures the the SafeUrl contains only ASCII-printable characters and reduces the chance of security bugs were it to be interpolated into a specific context without the necessary escaping. If url fails validation or does not UTF-16 decode correctly (JavaScript strings are UTF-16 encoded), this function returns a SafeUrl object containing an innocuous string, goog.html.SafeUrl.INNOCUOUS_STRING.
Arguments:
url : string | !goog.string.TypedString
The URL to validate.
Returns: !goog.html.SafeUrl  The validated URL, wrapped as a SafeUrl.
code »
goog.html.SafeUrl.unwrap(safeUrl) string
Performs a runtime check that the provided object is indeed a SafeUrl object, and returns its value. IMPORTANT: The guarantees of the SafeUrl type contract only extend to the behavior of browsers when interpreting URLs. Values of SafeUrl objects MUST be appropriately escaped before embedding in a HTML document. Note that the required escaping is context-sensitive (e.g. a different escaping is required for embedding a URL in a style property within a style attribute, as opposed to embedding in a href attribute). Note that the returned value does not necessarily correspond to the string with which the SafeUrl was constructed, since goog.html.SafeUrl.sanitize will percent-encode many characters.
Arguments:
safeUrl : !goog.html.SafeUrl
The object to extract from.
Returns: string  The SafeUrl 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 goog.asserts.AssertionError.
code »

Static Properties

goog.html.SafeUrl.INNOCUOUS_STRING :
The innocuous string generated by goog.html.SafeUrl.sanitize when passed an unsafe URL. about:invalid is registered in http://www.w3.org/TR/css3-values/#about-invalid. http://tools.ietf.org/html/rfc6694#section-2.2.1 permits about URLs to contain a fragment, which is not to be considered when determining if an about URL is well-known. Using about:invalid seems preferable to using a fixed data URL, since browsers might choose to not report CSP violations on it, as legitimate CSS function calls to attr() can result in this URL being produced. It is also a standard URL which matches exactly the semantics we need: "The about:invalid URI references a non-existent document with a generic error condition. It can be used when a URI is necessary, but the default value shouldn't be resolveable as any type of document".
Code »
goog.html.SafeUrl.NORMALIZE_MATCHER_ :
Matches characters and strings which need to be replaced in the string generated by encodeURI. Specifically: - '\'', '(' and ')' are not encoded. They are part of the reserved characters group in RFC 3986 but only appear in the obsolete mark production in Appendix D.2 of RFC 3986, so they can be encoded without changing semantics. - '[' and ']' are encoded by encodeURI, despite being reserved characters which can be used to represent IPv6 addresses. So they need to be decoded. - '%' is encoded by encodeURI. However, encoding '%' characters that are already part of a valid percent-encoded sequence changes the semantics of a URL, and hence we need to preserve them. Note that this may allow non-encoded '%' characters to remain in the URL (i.e., occurrences of '%' that are not part of a valid percent-encoded sequence, for example, 'ab%xy').
Code »
goog.html.SafeUrl.NORMALIZE_REPLACER_MAP_ :
Map of replacements to be done in string generated by encodeURI.
Code »
goog.html.SafeUrl.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ :
Type marker for the SafeUrl type, used to implement additional run-time type checking.
Code »

Package html

Package Reference