Debian Codegraph @

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

raw
1 // Copyright 2013 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 /**
17 * @fileoverview The SafeHtml type and its builders.
18 *
19 * TODO(xtof): Link to document stating type contract.
20 */
21
22 goog.provide('goog.html.SafeHtml');
23
24 goog.require('goog.array');
25 goog.require('goog.asserts');
26 goog.require('goog.dom.TagName');
27 goog.require('goog.dom.tags');
28 goog.require('goog.html.SafeScript');
29 goog.require('goog.html.SafeStyle');
30 goog.require('goog.html.SafeStyleSheet');
31 goog.require('goog.html.SafeUrl');
32 goog.require('goog.html.TrustedResourceUrl');
33 goog.require('goog.i18n.bidi.Dir');
34 goog.require('goog.i18n.bidi.DirectionalString');
35 goog.require('goog.labs.userAgent.browser');
36 goog.require('goog.object');
37 goog.require('goog.string');
38 goog.require('goog.string.Const');
39 goog.require('goog.string.TypedString');
40
41
42
43 /**
44 * A string that is safe to use in HTML context in DOM APIs and HTML documents.
45 *
46 * A SafeHtml is a string-like object that carries the security type contract
47 * that its value as a string will not cause untrusted script execution when
48 * evaluated as HTML in a browser.
49 *
50 * Values of this type are guaranteed to be safe to use in HTML contexts,
51 * such as, assignment to the innerHTML DOM property, or interpolation into
52 * a HTML template in HTML PC_DATA context, in the sense that the use will not
53 * result in a Cross-Site-Scripting vulnerability.
54 *
55 * Instances of this type must be created via the factory methods
56 * ({@code goog.html.SafeHtml.create}, {@code goog.html.SafeHtml.htmlEscape}),
57 * etc and not by invoking its constructor. The constructor intentionally
58 * takes no parameters and the type is immutable; hence only a default instance
59 * corresponding to the empty string can be obtained via constructor invocation.
60 *
61 * @see goog.html.SafeHtml#create
62 * @see goog.html.SafeHtml#htmlEscape
63 * @constructor
64 * @final
65 * @struct
66 * @implements {goog.i18n.bidi.DirectionalString}
67 * @implements {goog.string.TypedString}
68 */
69 goog.html.SafeHtml = function() {
70 /**
71 * The contained value of this SafeHtml. The field has a purposely ugly
72 * name to make (non-compiled) code that attempts to directly access this
73 * field stand out.
74 * @private {string}
75 */
76 this.privateDoNotAccessOrElseSafeHtmlWrappedValue_ = '';
77
78 /**
79 * A type marker used to implement additional run-time type checking.
80 * @see goog.html.SafeHtml#unwrap
81 * @const {!Object}
82 * @private
83 */
84 this.SAFE_HTML_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ =
85 goog.html.SafeHtml.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_;
86
87 /**
88 * This SafeHtml's directionality, or null if unknown.
89 * @private {?goog.i18n.bidi.Dir}
90 */
91 this.dir_ = null;
92 };
93
94
95 /**
96 * @override
97 * @const
98 */
99 goog.html.SafeHtml.prototype.implementsGoogI18nBidiDirectionalString = true;
100
101
102 /** @override */
103 goog.html.SafeHtml.prototype.getDirection = function() {
104 return this.dir_;
105 };
106
107
108 /**
109 * @override
110 * @const
111 */
112 goog.html.SafeHtml.prototype.implementsGoogStringTypedString = true;
113
114
115 /**
116 * Returns this SafeHtml's value as string.
117 *
118 * IMPORTANT: In code where it is security relevant that an object's type is
119 * indeed {@code SafeHtml}, use {@code goog.html.SafeHtml.unwrap} instead of
120 * this method. If in doubt, assume that it's security relevant. In particular,
121 * note that goog.html functions which return a goog.html type do not guarantee
122 * that the returned instance is of the right type. For example:
123 *
124 * <pre>
125 * var fakeSafeHtml = new String('fake');
126 * fakeSafeHtml.__proto__ = goog.html.SafeHtml.prototype;
127 * var newSafeHtml = goog.html.SafeHtml.htmlEscape(fakeSafeHtml);
128 * // newSafeHtml is just an alias for fakeSafeHtml, it's passed through by
129 * // goog.html.SafeHtml.htmlEscape() as fakeSafeHtml
130 * // instanceof goog.html.SafeHtml.
131 * </pre>
132 *
133 * @see goog.html.SafeHtml#unwrap
134 * @override
135 */
136 goog.html.SafeHtml.prototype.getTypedStringValue = function() {
137 return this.privateDoNotAccessOrElseSafeHtmlWrappedValue_;
138 };
139
140
141 if (goog.DEBUG) {
142 /**
143 * Returns a debug string-representation of this value.
144 *
145 * To obtain the actual string value wrapped in a SafeHtml, use
146 * {@code goog.html.SafeHtml.unwrap}.
147 *
148 * @see goog.html.SafeHtml#unwrap
149 * @override
150 */
151 goog.html.SafeHtml.prototype.toString = function() {
152 return 'SafeHtml{' + this.privateDoNotAccessOrElseSafeHtmlWrappedValue_ +
153 '}';
154 };
155 }
156
157
158 /**
159 * Performs a runtime check that the provided object is indeed a SafeHtml
160 * object, and returns its value.
161 * @param {!goog.html.SafeHtml} safeHtml The object to extract from.
162 * @return {string} The SafeHtml object's contained string, unless the run-time
163 * type check fails. In that case, {@code unwrap} returns an innocuous
164 * string, or, if assertions are enabled, throws
165 * {@code goog.asserts.AssertionError}.
166 */
167 goog.html.SafeHtml.unwrap = function(safeHtml) {
168 // Perform additional run-time type-checking to ensure that safeHtml is indeed
169 // an instance of the expected type. This provides some additional protection
170 // against security bugs due to application code that disables type checks.
171 // Specifically, the following checks are performed:
172 // 1. The object is an instance of the expected type.
173 // 2. The object is not an instance of a subclass.
174 // 3. The object carries a type marker for the expected type. "Faking" an
175 // object requires a reference to the type marker, which has names intended
176 // to stand out in code reviews.
177 if (safeHtml instanceof goog.html.SafeHtml &&
178 safeHtml.constructor === goog.html.SafeHtml &&
179 safeHtml.SAFE_HTML_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ ===
180 goog.html.SafeHtml.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_) {
181 return safeHtml.privateDoNotAccessOrElseSafeHtmlWrappedValue_;
182 } else {
183 goog.asserts.fail('expected object of type SafeHtml, got \'' +
184 safeHtml + '\' of type ' + goog.typeOf(safeHtml));
185 return 'type_error:SafeHtml';
186 }
187 };
188
189
190 /**
191 * Shorthand for union of types that can sensibly be converted to strings
192 * or might already be SafeHtml (as SafeHtml is a goog.string.TypedString).
193 * @private
194 * @typedef {string|number|boolean|!goog.string.TypedString|
195 * !goog.i18n.bidi.DirectionalString}
196 */
197 goog.html.SafeHtml.TextOrHtml_;
198
199
200 /**
201 * Returns HTML-escaped text as a SafeHtml object.
202 *
203 * If text is of a type that implements
204 * {@code goog.i18n.bidi.DirectionalString}, the directionality of the new
205 * {@code SafeHtml} object is set to {@code text}'s directionality, if known.
206 * Otherwise, the directionality of the resulting SafeHtml is unknown (i.e.,
207 * {@code null}).
208 *
209 * @param {!goog.html.SafeHtml.TextOrHtml_} textOrHtml The text to escape. If
210 * the parameter is of type SafeHtml it is returned directly (no escaping
211 * is done).
212 * @return {!goog.html.SafeHtml} The escaped text, wrapped as a SafeHtml.
213 */
214 goog.html.SafeHtml.htmlEscape = function(textOrHtml) {
215 if (textOrHtml instanceof goog.html.SafeHtml) {
216 return textOrHtml;
217 }
218 var dir = null;
219 if (textOrHtml.implementsGoogI18nBidiDirectionalString) {
220 dir = textOrHtml.getDirection();
221 }
222 var textAsString;
223 if (textOrHtml.implementsGoogStringTypedString) {
224 textAsString = textOrHtml.getTypedStringValue();
225 } else {
226 textAsString = String(textOrHtml);
227 }
228 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
229 goog.string.htmlEscape(textAsString), dir);
230 };
231
232
233 /**
234 * Returns HTML-escaped text as a SafeHtml object, with newlines changed to
235 * &lt;br&gt;.
236 * @param {!goog.html.SafeHtml.TextOrHtml_} textOrHtml The text to escape. If
237 * the parameter is of type SafeHtml it is returned directly (no escaping
238 * is done).
239 * @return {!goog.html.SafeHtml} The escaped text, wrapped as a SafeHtml.
240 */
241 goog.html.SafeHtml.htmlEscapePreservingNewlines = function(textOrHtml) {
242 if (textOrHtml instanceof goog.html.SafeHtml) {
243 return textOrHtml;
244 }
245 var html = goog.html.SafeHtml.htmlEscape(textOrHtml);
246 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
247 goog.string.newLineToBr(goog.html.SafeHtml.unwrap(html)),
248 html.getDirection());
249 };
250
251
252 /**
253 * Returns HTML-escaped text as a SafeHtml object, with newlines changed to
254 * &lt;br&gt; and escaping whitespace to preserve spatial formatting. Character
255 * entity #160 is used to make it safer for XML.
256 * @param {!goog.html.SafeHtml.TextOrHtml_} textOrHtml The text to escape. If
257 * the parameter is of type SafeHtml it is returned directly (no escaping
258 * is done).
259 * @return {!goog.html.SafeHtml} The escaped text, wrapped as a SafeHtml.
260 */
261 goog.html.SafeHtml.htmlEscapePreservingNewlinesAndSpaces = function(
262 textOrHtml) {
263 if (textOrHtml instanceof goog.html.SafeHtml) {
264 return textOrHtml;
265 }
266 var html = goog.html.SafeHtml.htmlEscape(textOrHtml);
267 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
268 goog.string.whitespaceEscape(goog.html.SafeHtml.unwrap(html)),
269 html.getDirection());
270 };
271
272
273 /**
274 * Coerces an arbitrary object into a SafeHtml object.
275 *
276 * If {@code textOrHtml} is already of type {@code goog.html.SafeHtml}, the same
277 * object is returned. Otherwise, {@code textOrHtml} is coerced to string, and
278 * HTML-escaped. If {@code textOrHtml} is of a type that implements
279 * {@code goog.i18n.bidi.DirectionalString}, its directionality, if known, is
280 * preserved.
281 *
282 * @param {!goog.html.SafeHtml.TextOrHtml_} textOrHtml The text or SafeHtml to
283 * coerce.
284 * @return {!goog.html.SafeHtml} The resulting SafeHtml object.
285 * @deprecated Use goog.html.SafeHtml.htmlEscape.
286 */
287 goog.html.SafeHtml.from = goog.html.SafeHtml.htmlEscape;
288
289
290 /**
291 * @const
292 * @private
293 */
294 goog.html.SafeHtml.VALID_NAMES_IN_TAG_ = /^[a-zA-Z0-9-]+$/;
295
296
297 /**
298 * Set of attributes containing URL as defined at
299 * http://www.w3.org/TR/html5/index.html#attributes-1.
300 * @private @const {!Object<string,boolean>}
301 */
302 goog.html.SafeHtml.URL_ATTRIBUTES_ = goog.object.createSet(
303 'action', 'cite', 'data', 'formaction', 'href', 'manifest', 'poster',
304 'src');
305
306
307 /**
308 * Tags which are unsupported via create(). They might be supported via a
309 * tag-specific create method. These are tags which might require a
310 * TrustedResourceUrl in one of their attributes or a restricted type for
311 * their content.
312 * @private @const {!Object<string,boolean>}
313 */
314 goog.html.SafeHtml.NOT_ALLOWED_TAG_NAMES_ = goog.object.createSet(
315 goog.dom.TagName.APPLET, goog.dom.TagName.BASE, goog.dom.TagName.EMBED,
316 goog.dom.TagName.IFRAME, goog.dom.TagName.LINK, goog.dom.TagName.MATH,
317 goog.dom.TagName.META, goog.dom.TagName.OBJECT, goog.dom.TagName.SCRIPT,
318 goog.dom.TagName.STYLE, goog.dom.TagName.SVG, goog.dom.TagName.TEMPLATE);
319
320
321 /**
322 * @typedef {string|number|goog.string.TypedString|
323 * goog.html.SafeStyle.PropertyMap|undefined}
324 */
325 goog.html.SafeHtml.AttributeValue;
326
327
328 /**
329 * Creates a SafeHtml content consisting of a tag with optional attributes and
330 * optional content.
331 *
332 * For convenience tag names and attribute names are accepted as regular
333 * strings, instead of goog.string.Const. Nevertheless, you should not pass
334 * user-controlled values to these parameters. Note that these parameters are
335 * syntactically validated at runtime, and invalid values will result in
336 * an exception.
337 *
338 * Example usage:
339 *
340 * goog.html.SafeHtml.create('br');
341 * goog.html.SafeHtml.create('div', {'class': 'a'});
342 * goog.html.SafeHtml.create('p', {}, 'a');
343 * goog.html.SafeHtml.create('p', {}, goog.html.SafeHtml.create('br'));
344 *
345 * goog.html.SafeHtml.create('span', {
346 * 'style': {'margin': '0'}
347 * });
348 *
349 * To guarantee SafeHtml's type contract is upheld there are restrictions on
350 * attribute values and tag names.
351 *
352 * - For attributes which contain script code (on*), a goog.string.Const is
353 * required.
354 * - For attributes which contain style (style), a goog.html.SafeStyle or a
355 * goog.html.SafeStyle.PropertyMap is required.
356 * - For attributes which are interpreted as URLs (e.g. src, href) a
357 * goog.html.SafeUrl, goog.string.Const or string is required. If a string
358 * is passed, it will be sanitized with SafeUrl.sanitize().
359 * - For tags which can load code or set security relevant page metadata,
360 * more specific goog.html.SafeHtml.create*() functions must be used. Tags
361 * which are not supported by this function are applet, base, embed, iframe,
362 * link, math, object, script, style, svg, and template.
363 *
364 * @param {!goog.dom.TagName|string} tagName The name of the tag. Only tag names
365 * consisting of [a-zA-Z0-9-] are allowed. Tag names documented above are
366 * disallowed.
367 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
368 * Mapping from attribute names to their values. Only attribute names
369 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined causes
370 * the attribute to be omitted.
371 * @param {!goog.html.SafeHtml.TextOrHtml_|
372 * !Array<!goog.html.SafeHtml.TextOrHtml_>=} opt_content Content to
373 * HTML-escape and put inside the tag. This must be empty for void tags
374 * like <br>. Array elements are concatenated.
375 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
376 * @throws {Error} If invalid tag name, attribute name, or attribute value is
377 * provided.
378 * @throws {goog.asserts.AssertionError} If content for void tag is provided.
379 */
380 goog.html.SafeHtml.create = function(tagName, opt_attributes, opt_content) {
381 goog.html.SafeHtml.verifyTagName(String(tagName));
382 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
383 String(tagName), opt_attributes, opt_content);
384 };
385
386
387 /**
388 * Verifies if the tag name is valid and if it doesn't change the context.
389 * E.g. STRONG is fine but SCRIPT throws because it changes context. See
390 * goog.html.SafeHtml.create for an explanation of allowed tags.
391 * @param {string} tagName
392 * @throws {Error} If invalid tag name is provided.
393 * @package
394 */
395 goog.html.SafeHtml.verifyTagName = function(tagName) {
396 if (!goog.html.SafeHtml.VALID_NAMES_IN_TAG_.test(tagName)) {
397 throw new Error('Invalid tag name <' + tagName + '>.');
398 }
399 if (tagName.toUpperCase() in goog.html.SafeHtml.NOT_ALLOWED_TAG_NAMES_) {
400 throw new Error('Tag name <' + tagName + '> is not allowed for SafeHtml.');
401 }
402 };
403
404
405 /**
406 * Creates a SafeHtml representing an iframe tag.
407 *
408 * This by default restricts the iframe as much as possible by setting the
409 * sandbox attribute to the empty string. If the iframe requires less
410 * restrictions, set the sandbox attribute as tight as possible, but do not rely
411 * on the sandbox as a security feature because it is not supported by older
412 * browsers. If a sandbox is essential to security (e.g. for third-party
413 * frames), use createSandboxIframe which checks for browser support.
414 *
415 * @see https://developer.mozilla.org/en/docs/Web/HTML/Element/iframe#attr-sandbox
416 *
417 * @param {?goog.html.TrustedResourceUrl=} opt_src The value of the src
418 * attribute. If null or undefined src will not be set.
419 * @param {?goog.html.SafeHtml=} opt_srcdoc The value of the srcdoc attribute.
420 * If null or undefined srcdoc will not be set.
421 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
422 * Mapping from attribute names to their values. Only attribute names
423 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined causes
424 * the attribute to be omitted.
425 * @param {!goog.html.SafeHtml.TextOrHtml_|
426 * !Array<!goog.html.SafeHtml.TextOrHtml_>=} opt_content Content to
427 * HTML-escape and put inside the tag. Array elements are concatenated.
428 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
429 * @throws {Error} If invalid tag name, attribute name, or attribute value is
430 * provided. If opt_attributes contains the src or srcdoc attributes.
431 */
432 goog.html.SafeHtml.createIframe = function(
433 opt_src, opt_srcdoc, opt_attributes, opt_content) {
434 if (opt_src) {
435 // Check whether this is really TrustedResourceUrl.
436 goog.html.TrustedResourceUrl.unwrap(opt_src);
437 }
438
439 var fixedAttributes = {};
440 fixedAttributes['src'] = opt_src || null;
441 fixedAttributes['srcdoc'] =
442 opt_srcdoc && goog.html.SafeHtml.unwrap(opt_srcdoc);
443 var defaultAttributes = {'sandbox': ''};
444 var attributes = goog.html.SafeHtml.combineAttributes(
445 fixedAttributes, defaultAttributes, opt_attributes);
446 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
447 'iframe', attributes, opt_content);
448 };
449
450
451 /**
452 * Creates a SafeHtml representing a sandboxed iframe tag.
453 *
454 * The sandbox attribute is enforced in its most restrictive mode, an empty
455 * string. Consequently, the security requirements for the src and srcdoc
456 * attributes are relaxed compared to SafeHtml.createIframe. This function
457 * will throw on browsers that do not support the sandbox attribute, as
458 * determined by SafeHtml.canUseSandboxIframe.
459 *
460 * The SafeHtml returned by this function can trigger downloads with no
461 * user interaction on Chrome (though only a few, further attempts are blocked).
462 * Firefox and IE will block all downloads from the sandbox.
463 *
464 * @see https://developer.mozilla.org/en/docs/Web/HTML/Element/iframe#attr-sandbox
465 * @see https://lists.w3.org/Archives/Public/public-whatwg-archive/2013Feb/0112.html
466 *
467 * @param {string|!goog.html.SafeUrl=} opt_src The value of the src
468 * attribute. If null or undefined src will not be set.
469 * @param {string=} opt_srcdoc The value of the srcdoc attribute.
470 * If null or undefined srcdoc will not be set. Will not be sanitized.
471 * @param {!Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
472 * Mapping from attribute names to their values. Only attribute names
473 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined causes
474 * the attribute to be omitted.
475 * @param {!goog.html.SafeHtml.TextOrHtml_|
476 * !Array<!goog.html.SafeHtml.TextOrHtml_>=} opt_content Content to
477 * HTML-escape and put inside the tag. Array elements are concatenated.
478 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
479 * @throws {Error} If invalid tag name, attribute name, or attribute value is
480 * provided. If opt_attributes contains the src, srcdoc or sandbox
481 * attributes. If browser does not support the sandbox attribute on iframe.
482 */
483 goog.html.SafeHtml.createSandboxIframe = function(
484 opt_src, opt_srcdoc, opt_attributes, opt_content) {
485 if (!goog.html.SafeHtml.canUseSandboxIframe()) {
486 throw new Error('The browser does not support sandboxed iframes.');
487 }
488
489 var fixedAttributes = {};
490 if (opt_src) {
491 // Note that sanitize is a no-op on SafeUrl.
492 fixedAttributes['src'] =
493 goog.html.SafeUrl.unwrap(goog.html.SafeUrl.sanitize(opt_src));
494 } else {
495 fixedAttributes['src'] = null;
496 }
497 fixedAttributes['srcdoc'] = opt_srcdoc || null;
498 fixedAttributes['sandbox'] = '';
499 var attributes =
500 goog.html.SafeHtml.combineAttributes(fixedAttributes, {}, opt_attributes);
501 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
502 'iframe', attributes, opt_content);
503 };
504
505
506 /**
507 * Checks if the user agent supports sandboxed iframes.
508 * @return {boolean}
509 */
510 goog.html.SafeHtml.canUseSandboxIframe = function() {
511 return goog.global['HTMLIFrameElement'] &&
512 ('sandbox' in goog.global['HTMLIFrameElement'].prototype);
513 };
514
515
516 /**
517 * Creates a SafeHtml representing a script tag with the src attribute.
518 * @param {!goog.html.TrustedResourceUrl} src The value of the src
519 * attribute.
520 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=}
521 * opt_attributes
522 * Mapping from attribute names to their values. Only attribute names
523 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined
524 * causes the attribute to be omitted.
525 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
526 * @throws {Error} If invalid attribute name or value is provided. If
527 * opt_attributes contains the src attribute.
528 */
529 goog.html.SafeHtml.createScriptSrc = function(src, opt_attributes) {
530 // TODO(mlourenco): The charset attribute should probably be blocked. If
531 // its value is attacker controlled, the script contains attacker controlled
532 // sub-strings (even if properly escaped) and the server does not set charset
533 // then XSS is likely possible.
534 // https://html.spec.whatwg.org/multipage/scripting.html#dom-script-charset
535
536 // Check whether this is really TrustedResourceUrl.
537 goog.html.TrustedResourceUrl.unwrap(src);
538
539 var fixedAttributes = {'src': src};
540 var defaultAttributes = {};
541 var attributes = goog.html.SafeHtml.combineAttributes(
542 fixedAttributes, defaultAttributes, opt_attributes);
543 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
544 'script', attributes);
545 };
546
547
548 /**
549 * Creates a SafeHtml representing a script tag. Does not allow the language,
550 * src, text or type attributes to be set.
551 * @param {!goog.html.SafeScript|!Array<!goog.html.SafeScript>}
552 * script Content to put inside the tag. Array elements are
553 * concatenated.
554 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
555 * Mapping from attribute names to their values. Only attribute names
556 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined causes
557 * the attribute to be omitted.
558 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
559 * @throws {Error} If invalid attribute name or attribute value is provided. If
560 * opt_attributes contains the language, src, text or type attribute.
561 */
562 goog.html.SafeHtml.createScript = function(script, opt_attributes) {
563 for (var attr in opt_attributes) {
564 var attrLower = attr.toLowerCase();
565 if (attrLower == 'language' || attrLower == 'src' || attrLower == 'text' ||
566 attrLower == 'type') {
567 throw new Error('Cannot set "' + attrLower + '" attribute');
568 }
569 }
570
571 var content = '';
572 script = goog.array.concat(script);
573 for (var i = 0; i < script.length; i++) {
574 content += goog.html.SafeScript.unwrap(script[i]);
575 }
576 // Convert to SafeHtml so that it's not HTML-escaped. This is safe because
577 // as part of its contract, SafeScript should have no dangerous '<'.
578 var htmlContent =
579 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
580 content, goog.i18n.bidi.Dir.NEUTRAL);
581 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
582 'script', opt_attributes, htmlContent);
583 };
584
585
586 /**
587 * Creates a SafeHtml representing a style tag. The type attribute is set
588 * to "text/css".
589 * @param {!goog.html.SafeStyleSheet|!Array<!goog.html.SafeStyleSheet>}
590 * styleSheet Content to put inside the tag. Array elements are
591 * concatenated.
592 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
593 * Mapping from attribute names to their values. Only attribute names
594 * consisting of [a-zA-Z0-9-] are allowed. Value of null or undefined causes
595 * the attribute to be omitted.
596 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
597 * @throws {Error} If invalid attribute name or attribute value is provided. If
598 * opt_attributes contains the type attribute.
599 */
600 goog.html.SafeHtml.createStyle = function(styleSheet, opt_attributes) {
601 var fixedAttributes = {'type': 'text/css'};
602 var defaultAttributes = {};
603 var attributes = goog.html.SafeHtml.combineAttributes(
604 fixedAttributes, defaultAttributes, opt_attributes);
605
606 var content = '';
607 styleSheet = goog.array.concat(styleSheet);
608 for (var i = 0; i < styleSheet.length; i++) {
609 content += goog.html.SafeStyleSheet.unwrap(styleSheet[i]);
610 }
611 // Convert to SafeHtml so that it's not HTML-escaped. This is safe because
612 // as part of its contract, SafeStyleSheet should have no dangerous '<'.
613 var htmlContent =
614 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
615 content, goog.i18n.bidi.Dir.NEUTRAL);
616 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
617 'style', attributes, htmlContent);
618 };
619
620
621 /**
622 * Creates a SafeHtml representing a meta refresh tag.
623 * @param {!goog.html.SafeUrl|string} url Where to redirect. If a string is
624 * passed, it will be sanitized with SafeUrl.sanitize().
625 * @param {number=} opt_secs Number of seconds until the page should be
626 * reloaded. Will be set to 0 if unspecified.
627 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
628 */
629 goog.html.SafeHtml.createMetaRefresh = function(url, opt_secs) {
630
631 // Note that sanitize is a no-op on SafeUrl.
632 var unwrappedUrl = goog.html.SafeUrl.unwrap(goog.html.SafeUrl.sanitize(url));
633
634 if (goog.labs.userAgent.browser.isIE() ||
635 goog.labs.userAgent.browser.isEdge()) {
636 // IE/EDGE can't parse the content attribute if the url contains a
637 // semicolon. We can fix this by adding quotes around the url, but then we
638 // can't parse quotes in the URL correctly. Also, it seems that IE/EDGE
639 // did not unescape semicolons in these URLs at some point in the past. We
640 // take a best-effort approach.
641 //
642 // If the URL has semicolons (which may happen in some cases, see
643 // http://www.w3.org/TR/1999/REC-html401-19991224/appendix/notes.html#h-B.2
644 // for instance), wrap it in single quotes to protect the semicolons.
645 // If the URL has semicolons and single quotes, url-encode the single quotes
646 // as well.
647 //
648 // This is imperfect. Notice that both ' and ; are reserved characters in
649 // URIs, so this could do the wrong thing, but at least it will do the wrong
650 // thing in only rare cases.
651 if (goog.string.contains(unwrappedUrl, ';')) {
652 unwrappedUrl = "'" + unwrappedUrl.replace(/'/g, '%27') + "'";
653 }
654 }
655 var attributes = {
656 'http-equiv': 'refresh',
657 'content': (opt_secs || 0) + '; url=' + unwrappedUrl
658 };
659
660 // This function will handle the HTML escaping for attributes.
661 return goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse(
662 'meta', attributes);
663 };
664
665
666 /**
667 * @param {string} tagName The tag name.
668 * @param {string} name The attribute name.
669 * @param {!goog.html.SafeHtml.AttributeValue} value The attribute value.
670 * @return {string} A "name=value" string.
671 * @throws {Error} If attribute value is unsafe for the given tag and attribute.
672 * @private
673 */
674 goog.html.SafeHtml.getAttrNameAndValue_ = function(tagName, name, value) {
675 // If it's goog.string.Const, allow any valid attribute name.
676 if (value instanceof goog.string.Const) {
677 value = goog.string.Const.unwrap(value);
678 } else if (name.toLowerCase() == 'style') {
679 value = goog.html.SafeHtml.getStyleValue_(value);
680 } else if (/^on/i.test(name)) {
681 // TODO(jakubvrana): Disallow more attributes with a special meaning.
682 throw new Error(
683 'Attribute "' + name + '" requires goog.string.Const value, "' + value +
684 '" given.');
685 // URL attributes handled differently according to tag.
686 } else if (name.toLowerCase() in goog.html.SafeHtml.URL_ATTRIBUTES_) {
687 if (value instanceof goog.html.TrustedResourceUrl) {
688 value = goog.html.TrustedResourceUrl.unwrap(value);
689 } else if (value instanceof goog.html.SafeUrl) {
690 value = goog.html.SafeUrl.unwrap(value);
691 } else if (goog.isString(value)) {
692 value = goog.html.SafeUrl.sanitize(value).getTypedStringValue();
693 } else {
694 throw new Error(
695 'Attribute "' + name + '" on tag "' + tagName +
696 '" requires goog.html.SafeUrl, goog.string.Const, or string,' +
697 ' value "' + value + '" given.');
698 }
699 }
700
701 // Accept SafeUrl, TrustedResourceUrl, etc. for attributes which only require
702 // HTML-escaping.
703 if (value.implementsGoogStringTypedString) {
704 // Ok to call getTypedStringValue() since there's no reliance on the type
705 // contract for security here.
706 value = value.getTypedStringValue();
707 }
708
709 goog.asserts.assert(
710 goog.isString(value) || goog.isNumber(value),
711 'String or number value expected, got ' + (typeof value) +
712 ' with value: ' + value);
713 return name + '="' + goog.string.htmlEscape(String(value)) + '"';
714 };
715
716
717 /**
718 * Gets value allowed in "style" attribute.
719 * @param {!goog.html.SafeHtml.AttributeValue} value It could be SafeStyle or a
720 * map which will be passed to goog.html.SafeStyle.create.
721 * @return {string} Unwrapped value.
722 * @throws {Error} If string value is given.
723 * @private
724 */
725 goog.html.SafeHtml.getStyleValue_ = function(value) {
726 if (!goog.isObject(value)) {
727 throw new Error(
728 'The "style" attribute requires goog.html.SafeStyle or map ' +
729 'of style properties, ' + (typeof value) + ' given: ' + value);
730 }
731 if (!(value instanceof goog.html.SafeStyle)) {
732 // Process the property bag into a style object.
733 value = goog.html.SafeStyle.create(value);
734 }
735 return goog.html.SafeStyle.unwrap(value);
736 };
737
738
739 /**
740 * Creates a SafeHtml content with known directionality consisting of a tag with
741 * optional attributes and optional content.
742 * @param {!goog.i18n.bidi.Dir} dir Directionality.
743 * @param {string} tagName
744 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
745 * @param {!goog.html.SafeHtml.TextOrHtml_|
746 * !Array<!goog.html.SafeHtml.TextOrHtml_>=} opt_content
747 * @return {!goog.html.SafeHtml} The SafeHtml content with the tag.
748 */
749 goog.html.SafeHtml.createWithDir = function(
750 dir, tagName, opt_attributes, opt_content) {
751 var html = goog.html.SafeHtml.create(tagName, opt_attributes, opt_content);
752 html.dir_ = dir;
753 return html;
754 };
755
756
757 /**
758 * Creates a new SafeHtml object by concatenating values.
759 * @param {...(!goog.html.SafeHtml.TextOrHtml_|
760 * !Array<!goog.html.SafeHtml.TextOrHtml_>)} var_args Values to concatenate.
761 * @return {!goog.html.SafeHtml}
762 */
763 goog.html.SafeHtml.concat = function(var_args) {
764 var dir = goog.i18n.bidi.Dir.NEUTRAL;
765 var content = '';
766
767 /**
768 * @param {!goog.html.SafeHtml.TextOrHtml_|
769 * !Array<!goog.html.SafeHtml.TextOrHtml_>} argument
770 */
771 var addArgument = function(argument) {
772 if (goog.isArray(argument)) {
773 goog.array.forEach(argument, addArgument);
774 } else {
775 var html = goog.html.SafeHtml.htmlEscape(argument);
776 content += goog.html.SafeHtml.unwrap(html);
777 var htmlDir = html.getDirection();
778 if (dir == goog.i18n.bidi.Dir.NEUTRAL) {
779 dir = htmlDir;
780 } else if (htmlDir != goog.i18n.bidi.Dir.NEUTRAL && dir != htmlDir) {
781 dir = null;
782 }
783 }
784 };
785
786 goog.array.forEach(arguments, addArgument);
787 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
788 content, dir);
789 };
790
791
792 /**
793 * Creates a new SafeHtml object with known directionality by concatenating the
794 * values.
795 * @param {!goog.i18n.bidi.Dir} dir Directionality.
796 * @param {...(!goog.html.SafeHtml.TextOrHtml_|
797 * !Array<!goog.html.SafeHtml.TextOrHtml_>)} var_args Elements of array
798 * arguments would be processed recursively.
799 * @return {!goog.html.SafeHtml}
800 */
801 goog.html.SafeHtml.concatWithDir = function(dir, var_args) {
802 var html = goog.html.SafeHtml.concat(goog.array.slice(arguments, 1));
803 html.dir_ = dir;
804 return html;
805 };
806
807
808 /**
809 * Type marker for the SafeHtml type, used to implement additional run-time
810 * type checking.
811 * @const {!Object}
812 * @private
813 */
814 goog.html.SafeHtml.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ = {};
815
816
817 /**
818 * Package-internal utility method to create SafeHtml instances.
819 *
820 * @param {string} html The string to initialize the SafeHtml object with.
821 * @param {?goog.i18n.bidi.Dir} dir The directionality of the SafeHtml to be
822 * constructed, or null if unknown.
823 * @return {!goog.html.SafeHtml} The initialized SafeHtml object.
824 * @package
825 */
826 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse = function(
827 html, dir) {
828 return new goog.html.SafeHtml().initSecurityPrivateDoNotAccessOrElse_(
829 html, dir);
830 };
831
832
833 /**
834 * Called from createSafeHtmlSecurityPrivateDoNotAccessOrElse(). This
835 * method exists only so that the compiler can dead code eliminate static
836 * fields (like EMPTY) when they're not accessed.
837 * @param {string} html
838 * @param {?goog.i18n.bidi.Dir} dir
839 * @return {!goog.html.SafeHtml}
840 * @private
841 */
842 goog.html.SafeHtml.prototype.initSecurityPrivateDoNotAccessOrElse_ = function(
843 html, dir) {
844 this.privateDoNotAccessOrElseSafeHtmlWrappedValue_ = html;
845 this.dir_ = dir;
846 return this;
847 };
848
849
850 /**
851 * Like create() but does not restrict which tags can be constructed.
852 *
853 * @param {string} tagName Tag name. Set or validated by caller.
854 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
855 * @param {(!goog.html.SafeHtml.TextOrHtml_|
856 * !Array<!goog.html.SafeHtml.TextOrHtml_>)=} opt_content
857 * @return {!goog.html.SafeHtml}
858 * @throws {Error} If invalid or unsafe attribute name or value is provided.
859 * @throws {goog.asserts.AssertionError} If content for void tag is provided.
860 * @package
861 */
862 goog.html.SafeHtml.createSafeHtmlTagSecurityPrivateDoNotAccessOrElse = function(
863 tagName, opt_attributes, opt_content) {
864 var dir = null;
865 var result = '<' + tagName;
866 result += goog.html.SafeHtml.stringifyAttributes(tagName, opt_attributes);
867
868 var content = opt_content;
869 if (!goog.isDefAndNotNull(content)) {
870 content = [];
871 } else if (!goog.isArray(content)) {
872 content = [content];
873 }
874
875 if (goog.dom.tags.isVoidTag(tagName.toLowerCase())) {
876 goog.asserts.assert(
877 !content.length, 'Void tag <' + tagName + '> does not allow content.');
878 result += '>';
879 } else {
880 var html = goog.html.SafeHtml.concat(content);
881 result += '>' + goog.html.SafeHtml.unwrap(html) + '</' + tagName + '>';
882 dir = html.getDirection();
883 }
884
885 var dirAttribute = opt_attributes && opt_attributes['dir'];
886 if (dirAttribute) {
887 if (/^(ltr|rtl|auto)$/i.test(dirAttribute)) {
888 // If the tag has the "dir" attribute specified then its direction is
889 // neutral because it can be safely used in any context.
890 dir = goog.i18n.bidi.Dir.NEUTRAL;
891 } else {
892 dir = null;
893 }
894 }
895
896 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
897 result, dir);
898 };
899
900
901 /**
902 * Creates a string with attributes to insert after tagName.
903 * @param {string} tagName
904 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
905 * @return {string} Returns an empty string if there are no attributes, returns
906 * a string starting with a space otherwise.
907 * @throws {Error} If attribute value is unsafe for the given tag and attribute.
908 * @package
909 */
910 goog.html.SafeHtml.stringifyAttributes = function(tagName, opt_attributes) {
911 var result = '';
912 if (opt_attributes) {
913 for (var name in opt_attributes) {
914 if (!goog.html.SafeHtml.VALID_NAMES_IN_TAG_.test(name)) {
915 throw new Error('Invalid attribute name "' + name + '".');
916 }
917 var value = opt_attributes[name];
918 if (!goog.isDefAndNotNull(value)) {
919 continue;
920 }
921 result +=
922 ' ' + goog.html.SafeHtml.getAttrNameAndValue_(tagName, name, value);
923 }
924 }
925 return result;
926 };
927
928
929 /**
930 * @param {!Object<string, ?goog.html.SafeHtml.AttributeValue>} fixedAttributes
931 * @param {!Object<string, string>} defaultAttributes
932 * @param {?Object<string, ?goog.html.SafeHtml.AttributeValue>=} opt_attributes
933 * Optional attributes passed to create*().
934 * @return {!Object<string, ?goog.html.SafeHtml.AttributeValue>}
935 * @throws {Error} If opt_attributes contains an attribute with the same name
936 * as an attribute in fixedAttributes.
937 * @package
938 */
939 goog.html.SafeHtml.combineAttributes = function(
940 fixedAttributes, defaultAttributes, opt_attributes) {
941 var combinedAttributes = {};
942 var name;
943
944 for (name in fixedAttributes) {
945 goog.asserts.assert(name.toLowerCase() == name, 'Must be lower case');
946 combinedAttributes[name] = fixedAttributes[name];
947 }
948 for (name in defaultAttributes) {
949 goog.asserts.assert(name.toLowerCase() == name, 'Must be lower case');
950 combinedAttributes[name] = defaultAttributes[name];
951 }
952
953 for (name in opt_attributes) {
954 var nameLower = name.toLowerCase();
955 if (nameLower in fixedAttributes) {
956 throw new Error(
957 'Cannot override "' + nameLower + '" attribute, got "' + name +
958 '" with value "' + opt_attributes[name] + '"');
959 }
960 if (nameLower in defaultAttributes) {
961 delete combinedAttributes[nameLower];
962 }
963 combinedAttributes[name] = opt_attributes[name];
964 }
965
966 return combinedAttributes;
967 };
968
969
970 /**
971 * A SafeHtml instance corresponding to the HTML doctype: "<!DOCTYPE html>".
972 * @const {!goog.html.SafeHtml}
973 */
974 goog.html.SafeHtml.DOCTYPE_HTML =
975 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
976 '<!DOCTYPE html>', goog.i18n.bidi.Dir.NEUTRAL);
977
978
979 /**
980 * A SafeHtml instance corresponding to the empty string.
981 * @const {!goog.html.SafeHtml}
982 */
983 goog.html.SafeHtml.EMPTY =
984 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
985 '', goog.i18n.bidi.Dir.NEUTRAL);
986
987
988 /**
989 * A SafeHtml instance corresponding to the <br> tag.
990 * @const {!goog.html.SafeHtml}
991 */
992 goog.html.SafeHtml.BR =
993 goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
994 '<br>', goog.i18n.bidi.Dir.NEUTRAL);