goog.html.SafeUrl
| Provided By | |
|---|---|
| All Implemented Interfaces |
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, in the sense that the use will not result in a Cross-Site-Scripting vulnerability. Similarly, SafeUrls can be interpolated into the URL context of an HTML template (e.g., inside a href attribute). However, appropriate HTML-escaping must still be applied.
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.fromConstant, goog.html.SafeUrl.sanitize),
etc 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.
new SafeUrl( value, token )
| Parameters |
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| See Also | |||||||||
Instance Methods
this.getTypedStringValue() → string
stringReturns this SafeUrl's value as 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.
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).
| Specified by | |||
|---|---|---|---|
| Parameters | None. | ||
| Returns |
| ||
| See Also |
this.toString() → string
stringReturns a string-representation of this value.
To obtain the actual string value wrapped in a SafeUrl, use
goog.html.SafeUrl.unwrap.
| Parameters | None. | |
|---|---|---|
| Returns |
| |
| See Also |
Instance Properties
this.implementsGoogStringTypedString → boolean
booleanInterface marker of the TypedString interface.
This property can be used to determine at runtime whether or not an object
implements this interface. All implementations of this interface set this
property to true.
| Specified by |
|---|
Static Functions
SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse( url ) → goog.html.SafeUrl
goog.html.SafeUrlPackage-internal utility method to create SafeUrl instances.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.extractScheme( url ) → (string|undefined)
(string|undefined)SafeUrl.fromBlob( blob ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a blob URL for the given blob.
The blob URL is created with URL.createObjectURL. If the MIME type
for blob is not of a known safe audio, image or video MIME type,
then the SafeUrl will wrap #INNOCUOUS_STRING.
Note: Call revokeObjectUrl on the URL after it's used
to prevent memory leaks.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
| See Also | |||||
SafeUrl.fromConstant( url ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl object from a compile-time constant string.
Compile-time constant strings are inherently program-controlled and hence trusted.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromDataUrl( dataUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a data: URL, after validating it matches a
known-safe media MIME type. If it doesn't match, return
goog.html.SafeUrl.INNOCUOUS_URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromFacebookMessengerUrl( facebookMessengerUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a fb-messenger://share URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromMediaSource( mediaSource ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a blob URL created for a MediaSource.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
SafeUrl.fromSipUrl( sipUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a sip: URL. We only allow urls that consist of an email address. The characters '?' and '#' are not allowed in the local part of the email address.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromSmsUrl( smsUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a sms: URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromSshUrl( sshUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a ssh: URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromTelUrl( telUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a tel: URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.fromTrustedResourceUrl( trustedResourceUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl from TrustedResourceUrl. This is safe because TrustedResourceUrl is more tightly restricted than SafeUrl.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
SafeUrl.fromWhatsAppUrl( whatsAppUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl wrapping a whatsapp://send URL.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.isSafeMimeType( mimeType ) → boolean
booleanSafeUrl.revokeObjectUrl( safeUrl ) → void
voidRevokes an object URL created for a safe URL created fromBlob().
| Parameters |
|
|---|
SafeUrl.sanitize( url ) → goog.html.SafeUrl
goog.html.SafeUrlCreates 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. If validation fails,
goog.html.SafeUrl.INNOCUOUS_URL is returned.
url may be a URL with the http:, https:, mailto:, ftp: or data
scheme, or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
| See Also |
SafeUrl.sanitizeAssertUnchanged( url, opt_allowDataUrl ) → goog.html.SafeUrl
goog.html.SafeUrlCreates 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.
url may be a URL with the http, https, mailto or ftp scheme,
or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).
This function asserts (using goog.asserts) that the URL matches this pattern. If it does not, in addition to failing the assert, an innocuous URL will be returned.
| Parameters |
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Returns |
| ||||||||
| See Also |
SafeUrl.sanitizeChromeExtensionUrl( url, extensionId ) → goog.html.SafeUrl
goog.html.SafeUrlSanitizes a Chrome extension URL to SafeUrl, given a compile-time-constant extension identifier. Can also be restricted to chrome extensions.
| Parameters |
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Returns |
|
SafeUrl.sanitizeEdgeExtensionUrl( url, extensionId ) → goog.html.SafeUrl
goog.html.SafeUrlSanitizes a Edge extension URL to SafeUrl, given a compile-time-constant extension identifier. Can also be restricted to chrome extensions.
| Parameters |
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Returns |
|
SafeUrl.sanitizeFirefoxExtensionUrl( url, extensionId ) → goog.html.SafeUrl
goog.html.SafeUrlSanitizes a Firefox extension URL to SafeUrl, given a compile-time-constant extension identifier. Can also be restricted to chrome extensions.
| Parameters |
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Returns |
|
SafeUrl.sanitizeJavascriptUrlAssertUnchanged( url ) → goog.html.SafeUrl
goog.html.SafeUrlCreates a SafeUrl object from url. If url is a
goog.html.SafeUrl then it is simply returned. Otherwise javascript: URLs
are rejected.
This function asserts (using goog.asserts) that the URL scheme is not javascript. If it is, in addition to failing the assert, an innocuous URL will be returned.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
| See Also |
SafeUrl.tryFromDataUrl( dataUrl ) → (goog.html.SafeUrl|null)
(goog.html.SafeUrl|null)Attempts to create a SafeUrl wrapping a data: URL, after validating it
matches a known-safe media MIME type. If it doesn't match, return null.
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
SafeUrl.trySanitize( url ) → (goog.html.SafeUrl|null)
(goog.html.SafeUrl|null)Attempts to create a SafeUrl object from url. The input string is validated
to match a pattern of commonly used safe URLs. If validation fails, null is
returned.
url may be a URL with the http:, https:, mailto:, ftp: or data
scheme, or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
| ||||
| See Also |
SafeUrl.unwrap( safeUrl ) → string
stringPerforms 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).
| Parameters |
| ||||
|---|---|---|---|---|---|
| Returns |
|
Static Properties
SafeUrl.INNOCUOUS_STRING → string
stringThe 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".
SafeUrl.SAFE_URL_PATTERN → RegExp
RegExpPublic version of goog.html.SAFE_URL_PATTERN_. Updating goog.html.SAFE_URL_PATTERN_ doesn't seem to be backward compatible. Namespace is also changed to goog.html.SafeUrl so it can be imported using goog.require('goog.dom.SafeUrl').
TODO(bangert): Remove SAFE_URL_PATTERN_