| 1 |
// Copyright 2014 The Closure Library Authors. All Rights Reserved. |
| 2 |
// |
| 3 |
// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 |
// you may not use this file except in compliance with the License. |
| 5 |
// You may obtain a copy of the License at |
| 6 |
// |
| 7 |
// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 |
// |
| 9 |
// Unless required by applicable law or agreed to in writing, software |
| 10 |
// distributed under the License is distributed on an "AS-IS" BASIS, |
| 11 |
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 |
// See the License for the specific language governing permissions and |
| 13 |
// limitations under the License. |
| 14 |
|
| 15 |
/** |
| 16 |
* @fileoverview The SafeStyleSheet type and its builders. |
| 17 |
* |
| 18 |
* TODO(xtof): Link to document stating type contract. |
| 19 |
*/ |
| 20 |
|
| 21 |
goog.provide('goog.html.SafeStyleSheet'); |
| 22 |
|
| 23 |
goog.require('goog.array'); |
| 24 |
goog.require('goog.asserts'); |
| 25 |
goog.require('goog.html.SafeStyle'); |
| 26 |
goog.require('goog.object'); |
| 27 |
goog.require('goog.string'); |
| 28 |
goog.require('goog.string.Const'); |
| 29 |
goog.require('goog.string.TypedString'); |
| 30 |
|
| 31 |
|
| 32 |
|
| 33 |
/** |
| 34 |
* A string-like object which represents a CSS style sheet and that carries the |
| 35 |
* security type contract that its value, as a string, will not cause untrusted |
| 36 |
* script execution (XSS) when evaluated as CSS in a browser. |
| 37 |
* |
| 38 |
* Instances of this type must be created via the factory method |
| 39 |
* {@code goog.html.SafeStyleSheet.fromConstant} and not by invoking its |
| 40 |
* constructor. The constructor intentionally takes no parameters and the type |
| 41 |
* is immutable; hence only a default instance corresponding to the empty string |
| 42 |
* can be obtained via constructor invocation. |
| 43 |
* |
| 44 |
* A SafeStyleSheet's string representation can safely be interpolated as the |
| 45 |
* content of a style element within HTML. The SafeStyleSheet string should |
| 46 |
* not be escaped before interpolation. |
| 47 |
* |
| 48 |
* Values of this type must be composable, i.e. for any two values |
| 49 |
* {@code styleSheet1} and {@code styleSheet2} of this type, |
| 50 |
* {@code goog.html.SafeStyleSheet.unwrap(styleSheet1) + |
| 51 |
* goog.html.SafeStyleSheet.unwrap(styleSheet2)} must itself be a value that |
| 52 |
* satisfies the SafeStyleSheet type constraint. This requirement implies that |
| 53 |
* for any value {@code styleSheet} of this type, |
| 54 |
* {@code goog.html.SafeStyleSheet.unwrap(styleSheet1)} must end in |
| 55 |
* "beginning of rule" context. |
| 56 |
|
| 57 |
* A SafeStyleSheet can be constructed via security-reviewed unchecked |
| 58 |
* conversions. In this case producers of SafeStyleSheet must ensure themselves |
| 59 |
* that the SafeStyleSheet does not contain unsafe script. Note in particular |
| 60 |
* that {@code <} is dangerous, even when inside CSS strings, and so should |
| 61 |
* always be forbidden or CSS-escaped in user controlled input. For example, if |
| 62 |
* {@code </style><script>evil</script>"} were interpolated |
| 63 |
* inside a CSS string, it would break out of the context of the original |
| 64 |
* style element and {@code evil} would execute. Also note that within an HTML |
| 65 |
* style (raw text) element, HTML character references, such as |
| 66 |
* {@code &lt;}, are not allowed. See |
| 67 |
* |
| 68 |
http://www.w3.org/TR/html5/scripting-1.html#restrictions-for-contents-of-script-elements |
| 69 |
* (similar considerations apply to the style element). |
| 70 |
* |
| 71 |
* @see goog.html.SafeStyleSheet#fromConstant |
| 72 |
* @constructor |
| 73 |
* @final |
| 74 |
* @struct |
| 75 |
* @implements {goog.string.TypedString} |
| 76 |
*/ |
| 77 |
goog.html.SafeStyleSheet = function() { |
| 78 |
/** |
| 79 |
* The contained value of this SafeStyleSheet. The field has a purposely |
| 80 |
* ugly name to make (non-compiled) code that attempts to directly access this |
| 81 |
* field stand out. |
| 82 |
* @private {string} |
| 83 |
*/ |
| 84 |
this.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_ = ''; |
| 85 |
|
| 86 |
/** |
| 87 |
* A type marker used to implement additional run-time type checking. |
| 88 |
* @see goog.html.SafeStyleSheet#unwrap |
| 89 |
* @const {!Object} |
| 90 |
* @private |
| 91 |
*/ |
| 92 |
this.SAFE_STYLE_SHEET_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ = |
| 93 |
goog.html.SafeStyleSheet.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_; |
| 94 |
}; |
| 95 |
|
| 96 |
|
| 97 |
/** |
| 98 |
* @override |
| 99 |
* @const |
| 100 |
*/ |
| 101 |
goog.html.SafeStyleSheet.prototype.implementsGoogStringTypedString = true; |
| 102 |
|
| 103 |
|
| 104 |
/** |
| 105 |
* Type marker for the SafeStyleSheet type, used to implement additional |
| 106 |
* run-time type checking. |
| 107 |
* @const {!Object} |
| 108 |
* @private |
| 109 |
*/ |
| 110 |
goog.html.SafeStyleSheet.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ = {}; |
| 111 |
|
| 112 |
|
| 113 |
/** |
| 114 |
* Creates a style sheet consisting of one selector and one style definition. |
| 115 |
* Use {@link goog.html.SafeStyleSheet.concat} to create longer style sheets. |
| 116 |
* This function doesn't support @import, @media and similar constructs. |
| 117 |
* @param {string} selector CSS selector, e.g. '#id' or 'tag .class, #id'. We |
| 118 |
* support CSS3 selectors: https://w3.org/TR/css3-selectors/#selectors. |
| 119 |
* @param {!goog.html.SafeStyle.PropertyMap|!goog.html.SafeStyle} style Style |
| 120 |
* definition associated with the selector. |
| 121 |
* @return {!goog.html.SafeStyleSheet} |
| 122 |
* @throws {Error} If invalid selector is provided. |
| 123 |
*/ |
| 124 |
goog.html.SafeStyleSheet.createRule = function(selector, style) { |
| 125 |
if (goog.string.contains(selector, '<')) { |
| 126 |
throw new Error('Selector does not allow \'<\', got: ' + selector); |
| 127 |
} |
| 128 |
|
| 129 |
// Remove strings. |
| 130 |
var selectorToCheck = |
| 131 |
selector.replace(/('|")((?!\1)[^\r\n\f\\]|\\[\s\S])*\1/g, ''); |
| 132 |
|
| 133 |
// Check characters allowed in CSS3 selectors. |
| 134 |
if (!/^[-_a-zA-Z0-9#.:* ,>+~[\]()=^$|]+$/.test(selectorToCheck)) { |
| 135 |
throw new Error( |
| 136 |
'Selector allows only [-_a-zA-Z0-9#.:* ,>+~[\\]()=^$|] and ' + |
| 137 |
'strings, got: ' + selector); |
| 138 |
} |
| 139 |
|
| 140 |
// Check balanced () and []. |
| 141 |
if (!goog.html.SafeStyleSheet.hasBalancedBrackets_(selectorToCheck)) { |
| 142 |
throw new Error('() and [] in selector must be balanced, got: ' + selector); |
| 143 |
} |
| 144 |
|
| 145 |
if (!(style instanceof goog.html.SafeStyle)) { |
| 146 |
style = goog.html.SafeStyle.create(style); |
| 147 |
} |
| 148 |
var styleSheet = selector + '{' + goog.html.SafeStyle.unwrap(style) + '}'; |
| 149 |
return goog.html.SafeStyleSheet |
| 150 |
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheet); |
| 151 |
}; |
| 152 |
|
| 153 |
|
| 154 |
/** |
| 155 |
* Checks if a string has balanced () and [] brackets. |
| 156 |
* @param {string} s String to check. |
| 157 |
* @return {boolean} |
| 158 |
* @private |
| 159 |
*/ |
| 160 |
goog.html.SafeStyleSheet.hasBalancedBrackets_ = function(s) { |
| 161 |
var brackets = {'(': ')', '[': ']'}; |
| 162 |
var expectedBrackets = []; |
| 163 |
for (var i = 0; i < s.length; i++) { |
| 164 |
var ch = s[i]; |
| 165 |
if (brackets[ch]) { |
| 166 |
expectedBrackets.push(brackets[ch]); |
| 167 |
} else if (goog.object.contains(brackets, ch)) { |
| 168 |
if (expectedBrackets.pop() != ch) { |
| 169 |
return false; |
| 170 |
} |
| 171 |
} |
| 172 |
} |
| 173 |
return expectedBrackets.length == 0; |
| 174 |
}; |
| 175 |
|
| 176 |
|
| 177 |
/** |
| 178 |
* Creates a new SafeStyleSheet object by concatenating values. |
| 179 |
* @param {...(!goog.html.SafeStyleSheet|!Array<!goog.html.SafeStyleSheet>)} |
| 180 |
* var_args Values to concatenate. |
| 181 |
* @return {!goog.html.SafeStyleSheet} |
| 182 |
*/ |
| 183 |
goog.html.SafeStyleSheet.concat = function(var_args) { |
| 184 |
var result = ''; |
| 185 |
|
| 186 |
/** |
| 187 |
* @param {!goog.html.SafeStyleSheet|!Array<!goog.html.SafeStyleSheet>} |
| 188 |
* argument |
| 189 |
*/ |
| 190 |
var addArgument = function(argument) { |
| 191 |
if (goog.isArray(argument)) { |
| 192 |
goog.array.forEach(argument, addArgument); |
| 193 |
} else { |
| 194 |
result += goog.html.SafeStyleSheet.unwrap(argument); |
| 195 |
} |
| 196 |
}; |
| 197 |
|
| 198 |
goog.array.forEach(arguments, addArgument); |
| 199 |
return goog.html.SafeStyleSheet |
| 200 |
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(result); |
| 201 |
}; |
| 202 |
|
| 203 |
|
| 204 |
/** |
| 205 |
* Creates a SafeStyleSheet object from a compile-time constant string. |
| 206 |
* |
| 207 |
* {@code styleSheet} must not have any < characters in it, so that |
| 208 |
* the syntactic structure of the surrounding HTML is not affected. |
| 209 |
* |
| 210 |
* @param {!goog.string.Const} styleSheet A compile-time-constant string from |
| 211 |
* which to create a SafeStyleSheet. |
| 212 |
* @return {!goog.html.SafeStyleSheet} A SafeStyleSheet object initialized to |
| 213 |
* {@code styleSheet}. |
| 214 |
*/ |
| 215 |
goog.html.SafeStyleSheet.fromConstant = function(styleSheet) { |
| 216 |
var styleSheetString = goog.string.Const.unwrap(styleSheet); |
| 217 |
if (styleSheetString.length === 0) { |
| 218 |
return goog.html.SafeStyleSheet.EMPTY; |
| 219 |
} |
| 220 |
// > is a valid character in CSS selectors and there's no strict need to |
| 221 |
// block it if we already block <. |
| 222 |
goog.asserts.assert( |
| 223 |
!goog.string.contains(styleSheetString, '<'), |
| 224 |
"Forbidden '<' character in style sheet string: " + styleSheetString); |
| 225 |
return goog.html.SafeStyleSheet |
| 226 |
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheetString); |
| 227 |
}; |
| 228 |
|
| 229 |
|
| 230 |
/** |
| 231 |
* Returns this SafeStyleSheet's value as a string. |
| 232 |
* |
| 233 |
* IMPORTANT: In code where it is security relevant that an object's type is |
| 234 |
* indeed {@code SafeStyleSheet}, use {@code goog.html.SafeStyleSheet.unwrap} |
| 235 |
* instead of this method. If in doubt, assume that it's security relevant. In |
| 236 |
* particular, note that goog.html functions which return a goog.html type do |
| 237 |
* not guarantee the returned instance is of the right type. For example: |
| 238 |
* |
| 239 |
* <pre> |
| 240 |
* var fakeSafeHtml = new String('fake'); |
| 241 |
* fakeSafeHtml.__proto__ = goog.html.SafeHtml.prototype; |
| 242 |
* var newSafeHtml = goog.html.SafeHtml.htmlEscape(fakeSafeHtml); |
| 243 |
* // newSafeHtml is just an alias for fakeSafeHtml, it's passed through by |
| 244 |
* // goog.html.SafeHtml.htmlEscape() as fakeSafeHtml |
| 245 |
* // instanceof goog.html.SafeHtml. |
| 246 |
* </pre> |
| 247 |
* |
| 248 |
* @see goog.html.SafeStyleSheet#unwrap |
| 249 |
* @override |
| 250 |
*/ |
| 251 |
goog.html.SafeStyleSheet.prototype.getTypedStringValue = function() { |
| 252 |
return this.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_; |
| 253 |
}; |
| 254 |
|
| 255 |
|
| 256 |
if (goog.DEBUG) { |
| 257 |
/** |
| 258 |
* Returns a debug string-representation of this value. |
| 259 |
* |
| 260 |
* To obtain the actual string value wrapped in a SafeStyleSheet, use |
| 261 |
* {@code goog.html.SafeStyleSheet.unwrap}. |
| 262 |
* |
| 263 |
* @see goog.html.SafeStyleSheet#unwrap |
| 264 |
* @override |
| 265 |
*/ |
| 266 |
goog.html.SafeStyleSheet.prototype.toString = function() { |
| 267 |
return 'SafeStyleSheet{' + |
| 268 |
this.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_ + '}'; |
| 269 |
}; |
| 270 |
} |
| 271 |
|
| 272 |
|
| 273 |
/** |
| 274 |
* Performs a runtime check that the provided object is indeed a |
| 275 |
* SafeStyleSheet object, and returns its value. |
| 276 |
* |
| 277 |
* @param {!goog.html.SafeStyleSheet} safeStyleSheet The object to extract from. |
| 278 |
* @return {string} The safeStyleSheet object's contained string, unless |
| 279 |
* the run-time type check fails. In that case, {@code unwrap} returns an |
| 280 |
* innocuous string, or, if assertions are enabled, throws |
| 281 |
* {@code goog.asserts.AssertionError}. |
| 282 |
*/ |
| 283 |
goog.html.SafeStyleSheet.unwrap = function(safeStyleSheet) { |
| 284 |
// Perform additional Run-time type-checking to ensure that |
| 285 |
// safeStyleSheet is indeed an instance of the expected type. This |
| 286 |
// provides some additional protection against security bugs due to |
| 287 |
// application code that disables type checks. |
| 288 |
// Specifically, the following checks are performed: |
| 289 |
// 1. The object is an instance of the expected type. |
| 290 |
// 2. The object is not an instance of a subclass. |
| 291 |
// 3. The object carries a type marker for the expected type. "Faking" an |
| 292 |
// object requires a reference to the type marker, which has names intended |
| 293 |
// to stand out in code reviews. |
| 294 |
if (safeStyleSheet instanceof goog.html.SafeStyleSheet && |
| 295 |
safeStyleSheet.constructor === goog.html.SafeStyleSheet && |
| 296 |
safeStyleSheet |
| 297 |
.SAFE_STYLE_SHEET_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ === |
| 298 |
goog.html.SafeStyleSheet.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_) { |
| 299 |
return safeStyleSheet.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_; |
| 300 |
} else { |
| 301 |
goog.asserts.fail('expected object of type SafeStyleSheet, got \'' + |
| 302 |
safeStyleSheet + '\' of type ' + goog.typeOf(safeStyleSheet)); |
| 303 |
return 'type_error:SafeStyleSheet'; |
| 304 |
} |
| 305 |
}; |
| 306 |
|
| 307 |
|
| 308 |
/** |
| 309 |
* Package-internal utility method to create SafeStyleSheet instances. |
| 310 |
* |
| 311 |
* @param {string} styleSheet The string to initialize the SafeStyleSheet |
| 312 |
* object with. |
| 313 |
* @return {!goog.html.SafeStyleSheet} The initialized SafeStyleSheet object. |
| 314 |
* @package |
| 315 |
*/ |
| 316 |
goog.html.SafeStyleSheet.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse = |
| 317 |
function(styleSheet) { |
| 318 |
return new goog.html.SafeStyleSheet().initSecurityPrivateDoNotAccessOrElse_( |
| 319 |
styleSheet); |
| 320 |
}; |
| 321 |
|
| 322 |
|
| 323 |
/** |
| 324 |
* Called from createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(). This |
| 325 |
* method exists only so that the compiler can dead code eliminate static |
| 326 |
* fields (like EMPTY) when they're not accessed. |
| 327 |
* @param {string} styleSheet |
| 328 |
* @return {!goog.html.SafeStyleSheet} |
| 329 |
* @private |
| 330 |
*/ |
| 331 |
goog.html.SafeStyleSheet.prototype.initSecurityPrivateDoNotAccessOrElse_ = |
| 332 |
function(styleSheet) { |
| 333 |
this.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_ = styleSheet; |
| 334 |
return this; |
| 335 |
}; |
| 336 |
|
| 337 |
|
| 338 |
/** |
| 339 |
* A SafeStyleSheet instance corresponding to the empty string. |
| 340 |
* @const {!goog.html.SafeStyleSheet} |
| 341 |
*/ |
| 342 |
goog.html.SafeStyleSheet.EMPTY = |
| 343 |
goog.html.SafeStyleSheet |
| 344 |
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(''); |