goog.html.SafeStyle

Module ID	`goog.html.SafeStyle`
All Implemented Interfaces	`goog.string.TypedString`

A string-like object which represents a sequence of CSS declarations (propertyName1: propertyvalue1; propertyName2: propertyValue2; ...) and that carries the security type contract that its value, as a string, will not cause untrusted script execution (XSS) when evaluated as CSS in a browser.

Instances of this type must be created via the factory methods (SafeStyle.create or SafeStyle.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.

SafeStyle's string representation can safely be:

Interpolated as the content of a *quoted* HTML style attribute. However, the SafeStyle string *must be HTML-attribute-escaped* before interpolation.
Interpolated as the content of a {}-wrapped block within a stylesheet. '<' characters in the SafeStyle string *must be CSS-escaped* before interpolation. The SafeStyle string is also guaranteed not to be able to introduce new properties or elide existing ones.
Interpolated as the content of a {}-wrapped block within an HTML <style> element. '<' characters in the SafeStyle string * must be CSS-escaped* before interpolation.
Assigned to the style property of a DOM node. The SafeStyle string should not be escaped before being assigned to the property.

A SafeStyle may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyle into a <style> tag (where it can't be HTML escaped). For example, if the SafeStyle containing font: 'foo <style/><script>evil</script>' were interpolated within a <style> tag, this would then break out of the style context into HTML.

A SafeStyle may contain literal single or double quotes, and as such the entire style string must be escaped when used in a style attribute (if this were not the case, the string could contain a matching quote that would escape from the style attribute).

Values of this type must be composable, i.e. for any two values style1 and style2 of this type, SafeStyle.unwrap(style1) + SafeStyle.unwrap(style2) must itself be a value that satisfies the SafeStyle type constraint. This requirement implies that for any value style of this type, SafeStyle.unwrap(style) must not end in a "property value" or "property name" context. For example, a value of background:url(" or font- would not satisfy the SafeStyle contract. This is because concatenating such strings with a second value that itself does not contain unsafe CSS can result in an overall string that does. For example, if javascript:evil())" is appended to `background:url("}, the resulting string may result in the execution of a malicious script.

TODO(mlourenco): Consider whether we should implement UTF-8 interchange validity checks and blacklisting of newlines (including Unicode ones) and other whitespace characters (\t, \f). Document here if so and also update SafeStyle.fromConstant().

The following example values comply with this type's contract:

```
width: 1em;
```
```
height:1em;
```
```
width: 1em;height: 1em;
```
```
background:url('http://url');
```

In addition, the empty string is safe for use in a CSS attribute.

The following example values do NOT comply with this type's contract:

```
background: red
```
(missing a trailing semi-colon)
```
background:
```
(missing a value and a trailing semi-colon)
```
1em
```
(missing an attribute name, which provides context for the value)

new SafeStyle( `arg0`, `arg1` )

Parameters

`arg0`	`string`

`arg1`	`Object`

Instance Methods

Returns this SafeStyle's value as a string.

IMPORTANT: In code where it is security relevant that an object's type is indeed SafeStyle, use SafeStyle.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:

 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.

Specified by

goog.string.TypedString

Parameters

None.

Returns

string

Instance Properties

Interface 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	`goog.string.TypedString`

VIEW SOURCE

Exported Functions

Creates a new SafeStyle object by concatenating the values.

Parameters

`var_args`	`...(goog.html.SafeStyle\|Array<goog.html.SafeStyle>)`
	SafeStyles to concatenate.

Returns

goog.html.SafeStyle

VIEW SOURCE

Creates a new SafeStyle object from the properties specified in the map.

Parameters

Mapping of property names to their values, for example {'margin': '1px'}. Names must consist of [-a-zA-Z0-9]. Values might be strings consisting of [-,.'"%!# a-zA-Z0-9[]], where ", ', and [] must be properly balanced. We also allow simple functions like rgb() and url() which sanitizes its contents. Other values must be wrapped in Const. URLs might be passed as SafeUrl which will be wrapped into url(""). We also support array whose elements are joined with ' '. Null value causes skipping the property.

Returns

goog.html.SafeStyle

Throws

{!Error} If invalid name is provided.

{!AssertionError} If invalid value is provided. With disabled assertions, invalid value is replaced by SafeStyle.INNOCUOUS_STRING.

VIEW SOURCE

Package-internal utility method to create SafeStyle instances.

Parameters

`style`	`string`
	The string to initialize the SafeStyle object with.

Returns

goog.html.SafeStyle

The initialized SafeStyle object.

VIEW SOURCE

Creates a SafeStyle object from a compile-time constant string.

style should be in the format name: value; [name: value; ...] and must not have any < or > characters in it. This is so that SafeStyle's contract is preserved, allowing the SafeStyle to correctly be interpreted as a sequence of CSS declarations and without affecting the syntactic structure of any surrounding CSS and HTML.

This method performs basic sanity checks on the format of style but does not constrain the format of name and value, except for disallowing tag characters.

Parameters

`style`	`goog.string.Const`
	A compile-time-constant string from which to create a SafeStyle.

Returns

goog.html.SafeStyle

A SafeStyle object initialized to style.

VIEW SOURCE

Performs a runtime check that the provided object is indeed a SafeStyle object, and returns its value.

Parameters

`safeStyle`	`goog.html.SafeStyle`
	The object to extract from.

Returns

string

The safeStyle 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 AssertionError.

VIEW SOURCE

Exported Properties

A SafeStyle instance corresponding to the empty string.

VIEW SOURCE

The innocuous string generated by SafeStyle.create when passed an unsafe value.

VIEW SOURCE

Mapping of property names to their values. We don't support numbers even though some values might be numbers (e.g. line-height or 0 for any length). The reason is that most numeric values need units (e.g. '1px') and allowing numbers could cause users forgetting about them.

VIEW SOURCE

A single property value.

VIEW SOURCE

goog.html.SafeStyle

new SafeStyle( `arg0`, `arg1` )

Instance Methods

`this.`getTypedStringValue() `→` `string`

`this.`toString() `→` `string`

Instance Properties

`this.`implementsGoogStringTypedString `→` `boolean`

Exported Functions

concat( `...var_args` ) `→` `goog.html.SafeStyle`

create( `map` ) `→` `goog.html.SafeStyle`

createSafeStyleSecurityPrivateDoNotAccessOrElse( `style` ) `→` `goog.html.SafeStyle`

fromConstant( `style` ) `→` `goog.html.SafeStyle`

unwrap( `safeStyle` ) `→` `string`

Exported Properties

EMPTY `→` `goog.html.SafeStyle`

INNOCUOUS_STRING `→` `string`

PropertyMap `→` `Object<string, (string|goog.string.Const|goog.html.SafeUrl|Array<(string|goog.string.Const|goog.html.SafeUrl)>|null)>`

PropertyValue `→` `(string|goog.string.Const|goog.html.SafeUrl)`

goog.html.SafeStyle

new SafeStyle( arg0, arg1 )

Instance Methods

this.getTypedStringValue() → string

this.toString() → string

Instance Properties

this.implementsGoogStringTypedString → boolean

Exported Functions

concat( ...var_args ) → goog.html.SafeStyle

create( map ) → goog.html.SafeStyle

createSafeStyleSecurityPrivateDoNotAccessOrElse( style ) → goog.html.SafeStyle

fromConstant( style ) → goog.html.SafeStyle

unwrap( safeStyle ) → string

Exported Properties

EMPTY → goog.html.SafeStyle

INNOCUOUS_STRING → string

PropertyMap → Object<string, (string|goog.string.Const|goog.html.SafeUrl|Array<(string|goog.string.Const|goog.html.SafeUrl)>|null)>

PropertyValue → (string|goog.string.Const|goog.html.SafeUrl)

new SafeStyle( `arg0`, `arg1` )

`this.`getTypedStringValue() `→` `string`

`this.`toString() `→` `string`

`this.`implementsGoogStringTypedString `→` `boolean`

concat( `...var_args` ) `→` `goog.html.SafeStyle`

create( `map` ) `→` `goog.html.SafeStyle`

createSafeStyleSecurityPrivateDoNotAccessOrElse( `style` ) `→` `goog.html.SafeStyle`

fromConstant( `style` ) `→` `goog.html.SafeStyle`

unwrap( `safeStyle` ) `→` `string`

EMPTY `→` `goog.html.SafeStyle`

INNOCUOUS_STRING `→` `string`

PropertyMap `→` `Object<string, (string|goog.string.Const|goog.html.SafeUrl|Array<(string|goog.string.Const|goog.html.SafeUrl)>|null)>`

PropertyValue `→` `(string|goog.string.Const|goog.html.SafeUrl)`