Debian Codegraph @

closure-library/closure/goog/html/safestylesheet.js

raw
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 <}, 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 &lt; 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('');