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
 * @fileoverview Type-safe wrappers for unsafe DOM APIs.
17
 *
18
 * This file provides type-safe wrappers for DOM APIs that can result in
19
 * cross-site scripting (XSS) vulnerabilities, if the API is supplied with
20
 * untrusted (attacker-controlled) input.  Instead of plain strings, the type
21
 * safe wrappers consume values of types from the goog.html package whose
22
 * contract promises that values are safe to use in the corresponding context.
23
 *
24
 * Hence, a program that exclusively uses the wrappers in this file (i.e., whose
25
 * only reference to security-sensitive raw DOM APIs are in this file) is
26
 * guaranteed to be free of XSS due to incorrect use of such DOM APIs (modulo
27
 * correctness of code that produces values of the respective goog.html types,
28
 * and absent code that violates type safety).
29
 *
30
 * For example, assigning to an element's .innerHTML property a string that is
31
 * derived (even partially) from untrusted input typically results in an XSS
32
 * vulnerability. The type-safe wrapper goog.dom.safe.setInnerHtml consumes a
33
 * value of type goog.html.SafeHtml, whose contract states that using its values
34
 * in a HTML context will not result in XSS. Hence a program that is free of
35
 * direct assignments to any element's innerHTML property (with the exception of
36
 * the assignment to .innerHTML in this file) is guaranteed to be free of XSS
37
 * due to assignment of untrusted strings to the innerHTML property.
38
 */
39

40
goog.provide('goog.dom.safe');
41
goog.provide('goog.dom.safe.InsertAdjacentHtmlPosition');
42

43
goog.require('goog.asserts');
44
goog.require('goog.html.SafeHtml');
45
goog.require('goog.html.SafeScript');
46
goog.require('goog.html.SafeStyle');
47
goog.require('goog.html.SafeUrl');
48
goog.require('goog.html.TrustedResourceUrl');
49
goog.require('goog.string');
50
goog.require('goog.string.Const');
51

52

53
/** @enum {string} */
54
goog.dom.safe.InsertAdjacentHtmlPosition = {
55
  AFTERBEGIN: 'afterbegin',
56
  AFTEREND: 'afterend',
57
  BEFOREBEGIN: 'beforebegin',
58
  BEFOREEND: 'beforeend'
59
};
60

61

62
/**
63
 * Inserts known-safe HTML into a Node, at the specified position.
64
 * @param {!Node} node The node on which to call insertAdjacentHTML.
65
 * @param {!goog.dom.safe.InsertAdjacentHtmlPosition} position Position where
66
 *     to insert the HTML.
67
 * @param {!goog.html.SafeHtml} html The known-safe HTML to insert.
68
 */
69
goog.dom.safe.insertAdjacentHtml = function(node, position, html) {
70
  node.insertAdjacentHTML(position, goog.html.SafeHtml.unwrap(html));
71
};
72

73

74
/**
75
 * Tags not allowed in goog.dom.safe.setInnerHtml.
76
 * @private @const {!Object<string, boolean>}
77
 */
78
goog.dom.safe.SET_INNER_HTML_DISALLOWED_TAGS_ = {
79
  'MATH': true,
80
  'SCRIPT': true,
81
  'STYLE': true,
82
  'SVG': true,
83
  'TEMPLATE': true
84
};
85

86

87
/**
88
 * Assigns known-safe HTML to an element's innerHTML property.
89
 * @param {!Element} elem The element whose innerHTML is to be assigned to.
90
 * @param {!goog.html.SafeHtml} html The known-safe HTML to assign.
91
 * @throws {Error} If called with one of these tags: math, script, style, svg,
92
 *     template.
93
 */
94
goog.dom.safe.setInnerHtml = function(elem, html) {
95
  if (goog.asserts.ENABLE_ASSERTS) {
96
    var tagName = elem.tagName.toUpperCase();
97
    if (goog.dom.safe.SET_INNER_HTML_DISALLOWED_TAGS_[tagName]) {
98
      throw Error(
99
          'goog.dom.safe.setInnerHtml cannot be used to set content of ' +
100
          elem.tagName + '.');
101
    }
102
  }
103
  elem.innerHTML = goog.html.SafeHtml.unwrap(html);
104
};
105

106

107
/**
108
 * Assigns known-safe HTML to an element's outerHTML property.
109
 * @param {!Element} elem The element whose outerHTML is to be assigned to.
110
 * @param {!goog.html.SafeHtml} html The known-safe HTML to assign.
111
 */
112
goog.dom.safe.setOuterHtml = function(elem, html) {
113
  elem.outerHTML = goog.html.SafeHtml.unwrap(html);
114
};
115

116

117
/**
118
 * Sets the given element's style property to the contents of the provided
119
 * SafeStyle object.
120
 * @param {!Element} elem
121
 * @param {!goog.html.SafeStyle} style
122
 */
123
goog.dom.safe.setStyle = function(elem, style) {
124
  elem.style.cssText = goog.html.SafeStyle.unwrap(style);
125
};
126

127

128
/**
129
 * Writes known-safe HTML to a document.
130
 * @param {!Document} doc The document to be written to.
131
 * @param {!goog.html.SafeHtml} html The known-safe HTML to assign.
132
 */
133
goog.dom.safe.documentWrite = function(doc, html) {
134
  doc.write(goog.html.SafeHtml.unwrap(html));
135
};
136

137

138
/**
139
 * Safely assigns a URL to an anchor element's href property.
140
 *
141
 * If url is of type goog.html.SafeUrl, its value is unwrapped and assigned to
142
 * anchor's href property.  If url is of type string however, it is first
143
 * sanitized using goog.html.SafeUrl.sanitize.
144
 *
145
 * Example usage:
146
 *   goog.dom.safe.setAnchorHref(anchorEl, url);
147
 * which is a safe alternative to
148
 *   anchorEl.href = url;
149
 * The latter can result in XSS vulnerabilities if url is a
150
 * user-/attacker-controlled value.
151
 *
152
 * @param {!HTMLAnchorElement} anchor The anchor element whose href property
153
 *     is to be assigned to.
154
 * @param {string|!goog.html.SafeUrl} url The URL to assign.
155
 * @see goog.html.SafeUrl#sanitize
156
 */
157
goog.dom.safe.setAnchorHref = function(anchor, url) {
158
  goog.dom.safe.assertIsHTMLAnchorElement_(anchor);
159
  /** @type {!goog.html.SafeUrl} */
160
  var safeUrl;
161
  if (url instanceof goog.html.SafeUrl) {
162
    safeUrl = url;
163
  } else {
164
    safeUrl = goog.html.SafeUrl.sanitize(url);
165
  }
166
  anchor.href = goog.html.SafeUrl.unwrap(safeUrl);
167
};
168

169

170
/**
171
 * Safely assigns a URL to an image element's src property.
172
 *
173
 * If url is of type goog.html.SafeUrl, its value is unwrapped and assigned to
174
 * image's src property.  If url is of type string however, it is first
175
 * sanitized using goog.html.SafeUrl.sanitize.
176
 *
177
 * @param {!HTMLImageElement} imageElement The image element whose src property
178
 *     is to be assigned to.
179
 * @param {string|!goog.html.SafeUrl} url The URL to assign.
180
 * @see goog.html.SafeUrl#sanitize
181
 */
182
goog.dom.safe.setImageSrc = function(imageElement, url) {
183
  goog.dom.safe.assertIsHTMLImageElement_(imageElement);
184
  /** @type {!goog.html.SafeUrl} */
185
  var safeUrl;
186
  if (url instanceof goog.html.SafeUrl) {
187
    safeUrl = url;
188
  } else {
189
    safeUrl = goog.html.SafeUrl.sanitize(url);
190
  }
191
  imageElement.src = goog.html.SafeUrl.unwrap(safeUrl);
192
};
193

194

195
/**
196
 * Safely assigns a URL to an embed element's src property.
197
 *
198
 * Example usage:
199
 *   goog.dom.safe.setEmbedSrc(embedEl, url);
200
 * which is a safe alternative to
201
 *   embedEl.src = url;
202
 * The latter can result in loading untrusted code unless it is ensured that
203
 * the URL refers to a trustworthy resource.
204
 *
205
 * @param {!HTMLEmbedElement} embed The embed element whose src property
206
 *     is to be assigned to.
207
 * @param {!goog.html.TrustedResourceUrl} url The URL to assign.
208
 */
209
goog.dom.safe.setEmbedSrc = function(embed, url) {
210
  goog.dom.safe.assertIsHTMLEmbedElement_(embed);
211
  embed.src = goog.html.TrustedResourceUrl.unwrap(url);
212
};
213

214

215
/**
216
 * Safely assigns a URL to a frame element's src property.
217
 *
218
 * Example usage:
219
 *   goog.dom.safe.setFrameSrc(frameEl, url);
220
 * which is a safe alternative to
221
 *   frameEl.src = url;
222
 * The latter can result in loading untrusted code unless it is ensured that
223
 * the URL refers to a trustworthy resource.
224
 *
225
 * @param {!HTMLFrameElement} frame The frame element whose src property
226
 *     is to be assigned to.
227
 * @param {!goog.html.TrustedResourceUrl} url The URL to assign.
228
 */
229
goog.dom.safe.setFrameSrc = function(frame, url) {
230
  goog.dom.safe.assertIsHTMLFrameElement_(frame);
231
  frame.src = goog.html.TrustedResourceUrl.unwrap(url);
232
};
233

234

235
/**
236
 * Safely assigns a URL to an iframe element's src property.
237
 *
238
 * Example usage:
239
 *   goog.dom.safe.setIframeSrc(iframeEl, url);
240
 * which is a safe alternative to
241
 *   iframeEl.src = url;
242
 * The latter can result in loading untrusted code unless it is ensured that
243
 * the URL refers to a trustworthy resource.
244
 *
245
 * @param {!HTMLIFrameElement} iframe The iframe element whose src property
246
 *     is to be assigned to.
247
 * @param {!goog.html.TrustedResourceUrl} url The URL to assign.
248
 */
249
goog.dom.safe.setIframeSrc = function(iframe, url) {
250
  goog.dom.safe.assertIsHTMLIFrameElement_(iframe);
251
  iframe.src = goog.html.TrustedResourceUrl.unwrap(url);
252
};
253

254

255
/**
256
 * Safely assigns HTML to an iframe element's srcdoc property.
257
 *
258
 * Example usage:
259
 *   goog.dom.safe.setIframeSrcdoc(iframeEl, safeHtml);
260
 * which is a safe alternative to
261
 *   iframeEl.srcdoc = html;
262
 * The latter can result in loading untrusted code.
263
 *
264
 * @param {!HTMLIFrameElement} iframe The iframe element whose srcdoc property
265
 *     is to be assigned to.
266
 * @param {!goog.html.SafeHtml} html The HTML to assign.
267
 */
268
goog.dom.safe.setIframeSrcdoc = function(iframe, html) {
269
  goog.dom.safe.assertIsHTMLIFrameElement_(iframe);
270
  iframe.srcdoc = goog.html.SafeHtml.unwrap(html);
271
};
272

273

274
/**
275
 * Safely sets a link element's href and rel properties. Whether or not
276
 * the URL assigned to href has to be a goog.html.TrustedResourceUrl
277
 * depends on the value of the rel property. If rel contains "stylesheet"
278
 * then a TrustedResourceUrl is required.
279
 *
280
 * Example usage:
281
 *   goog.dom.safe.setLinkHrefAndRel(linkEl, url, 'stylesheet');
282
 * which is a safe alternative to
283
 *   linkEl.rel = 'stylesheet';
284
 *   linkEl.href = url;
285
 * The latter can result in loading untrusted code unless it is ensured that
286
 * the URL refers to a trustworthy resource.
287
 *
288
 * @param {!HTMLLinkElement} link The link element whose href property
289
 *     is to be assigned to.
290
 * @param {string|!goog.html.SafeUrl|!goog.html.TrustedResourceUrl} url The URL
291
 *     to assign to the href property. Must be a TrustedResourceUrl if the
292
 *     value assigned to rel contains "stylesheet". A string value is
293
 *     sanitized with goog.html.SafeUrl.sanitize.
294
 * @param {string} rel The value to assign to the rel property.
295
 * @throws {Error} if rel contains "stylesheet" and url is not a
296
 *     TrustedResourceUrl
297
 * @see goog.html.SafeUrl#sanitize
298
 */
299
goog.dom.safe.setLinkHrefAndRel = function(link, url, rel) {
300
  goog.dom.safe.assertIsHTMLLinkElement_(link);
301
  link.rel = rel;
302
  if (goog.string.caseInsensitiveContains(rel, 'stylesheet')) {
303
    goog.asserts.assert(
304
        url instanceof goog.html.TrustedResourceUrl,
305
        'URL must be TrustedResourceUrl because "rel" contains "stylesheet"');
306
    link.href = goog.html.TrustedResourceUrl.unwrap(url);
307
  } else if (url instanceof goog.html.TrustedResourceUrl) {
308
    link.href = goog.html.TrustedResourceUrl.unwrap(url);
309
  } else if (url instanceof goog.html.SafeUrl) {
310
    link.href = goog.html.SafeUrl.unwrap(url);
311
  } else {  // string
312
    // SafeUrl.sanitize must return legitimate SafeUrl when passed a string.
313
    link.href = goog.html.SafeUrl.sanitize(url).getTypedStringValue();
314
  }
315
};
316

317

318
/**
319
 * Safely assigns a URL to an object element's data property.
320
 *
321
 * Example usage:
322
 *   goog.dom.safe.setObjectData(objectEl, url);
323
 * which is a safe alternative to
324
 *   objectEl.data = url;
325
 * The latter can result in loading untrusted code unless setit is ensured that
326
 * the URL refers to a trustworthy resource.
327
 *
328
 * @param {!HTMLObjectElement} object The object element whose data property
329
 *     is to be assigned to.
330
 * @param {!goog.html.TrustedResourceUrl} url The URL to assign.
331
 */
332
goog.dom.safe.setObjectData = function(object, url) {
333
  goog.dom.safe.assertIsHTMLObjectElement_(object);
334
  object.data = goog.html.TrustedResourceUrl.unwrap(url);
335
};
336

337

338
/**
339
 * Safely assigns a URL to a script element's src property.
340
 *
341
 * Example usage:
342
 *   goog.dom.safe.setScriptSrc(scriptEl, url);
343
 * which is a safe alternative to
344
 *   scriptEl.src = url;
345
 * The latter can result in loading untrusted code unless it is ensured that
346
 * the URL refers to a trustworthy resource.
347
 *
348
 * @param {!HTMLScriptElement} script The script element whose src property
349
 *     is to be assigned to.
350
 * @param {!goog.html.TrustedResourceUrl} url The URL to assign.
351
 */
352
goog.dom.safe.setScriptSrc = function(script, url) {
353
  goog.dom.safe.assertIsHTMLScriptElement_(script);
354
  script.src = goog.html.TrustedResourceUrl.unwrap(url);
355
};
356

357

358
/**
359
 * Safely assigns a value to a script element's content.
360
 *
361
 * Example usage:
362
 *   goog.dom.safe.setScriptContent(scriptEl, content);
363
 * which is a safe alternative to
364
 *   scriptEl.text = content;
365
 * The latter can result in executing untrusted code unless it is ensured that
366
 * the code is loaded from a trustworthy resource.
367
 *
368
 * @param {!HTMLScriptElement} script The script element whose content is being
369
 *     set.
370
 * @param {!goog.html.SafeScript} content The content to assign.
371
 */
372
goog.dom.safe.setScriptContent = function(script, content) {
373
  goog.dom.safe.assertIsHTMLScriptElement_(script);
374
  script.text = goog.html.SafeScript.unwrap(content);
375
};
376

377

378
/**
379
 * Safely assigns a URL to a Location object's href property.
380
 *
381
 * If url is of type goog.html.SafeUrl, its value is unwrapped and assigned to
382
 * loc's href property.  If url is of type string however, it is first sanitized
383
 * using goog.html.SafeUrl.sanitize.
384
 *
385
 * Example usage:
386
 *   goog.dom.safe.setLocationHref(document.location, redirectUrl);
387
 * which is a safe alternative to
388
 *   document.location.href = redirectUrl;
389
 * The latter can result in XSS vulnerabilities if redirectUrl is a
390
 * user-/attacker-controlled value.
391
 *
392
 * @param {!Location} loc The Location object whose href property is to be
393
 *     assigned to.
394
 * @param {string|!goog.html.SafeUrl} url The URL to assign.
395
 * @see goog.html.SafeUrl#sanitize
396
 */
397
goog.dom.safe.setLocationHref = function(loc, url) {
398
  goog.dom.safe.assertIsLocation_(loc);
399
  /** @type {!goog.html.SafeUrl} */
400
  var safeUrl;
401
  if (url instanceof goog.html.SafeUrl) {
402
    safeUrl = url;
403
  } else {
404
    safeUrl = goog.html.SafeUrl.sanitize(url);
405
  }
406
  loc.href = goog.html.SafeUrl.unwrap(safeUrl);
407
};
408

409

410
/**
411
 * Safely opens a URL in a new window (via window.open).
412
 *
413
 * If url is of type goog.html.SafeUrl, its value is unwrapped and passed in to
414
 * window.open.  If url is of type string however, it is first sanitized
415
 * using goog.html.SafeUrl.sanitize.
416
 *
417
 * Note that this function does not prevent leakages via the referer that is
418
 * sent by window.open. It is advised to only use this to open 1st party URLs.
419
 *
420
 * Example usage:
421
 *   goog.dom.safe.openInWindow(url);
422
 * which is a safe alternative to
423
 *   window.open(url);
424
 * The latter can result in XSS vulnerabilities if redirectUrl is a
425
 * user-/attacker-controlled value.
426
 *
427
 * @param {string|!goog.html.SafeUrl} url The URL to open.
428
 * @param {Window=} opt_openerWin Window of which to call the .open() method.
429
 *     Defaults to the global window.
430
 * @param {!goog.string.Const=} opt_name Name of the window to open in. Can be
431
 *     _top, etc as allowed by window.open().
432
 * @param {string=} opt_specs Comma-separated list of specifications, same as
433
 *     in window.open().
434
 * @param {boolean=} opt_replace Whether to replace the current entry in browser
435
 *     history, same as in window.open().
436
 * @return {Window} Window the url was opened in.
437
 */
438
goog.dom.safe.openInWindow = function(
439
    url, opt_openerWin, opt_name, opt_specs, opt_replace) {
440
  /** @type {!goog.html.SafeUrl} */
441
  var safeUrl;
442
  if (url instanceof goog.html.SafeUrl) {
443
    safeUrl = url;
444
  } else {
445
    safeUrl = goog.html.SafeUrl.sanitize(url);
446
  }
447
  var win = opt_openerWin || window;
448
  return win.open(
449
      goog.html.SafeUrl.unwrap(safeUrl),
450
      // If opt_name is undefined, simply passing that in to open() causes IE to
451
      // reuse the current window instead of opening a new one. Thus we pass ''
452
      // in instead, which according to spec opens a new window. See
453
      // https://html.spec.whatwg.org/multipage/browsers.html#dom-open .
454
      opt_name ? goog.string.Const.unwrap(opt_name) : '', opt_specs,
455
      opt_replace);
456
};
457

458

459
/*
460
 * Custom assertions for use in the above wrapper methods to ensure that they
461
 * are indeed invoked on an element of the appropriate type.
462
 *
463
 * Using a goog.dom.safe wrapper on an object on the incorrect type (via an
464
 * incorrect static type cast) can result in security bugs: For instance,
465
 * g.d.s.setAnchorHref ensures that the URL assigned to the .href attribute
466
 * satisfies the SafeUrl contract, i.e., is safe to dereference as a hyperlink.
467
 * However, the value assigned to a HTMLLinkElement's .href property requires
468
 * the stronger TrustedResourceUrl contract, since it can refer to a stylesheet.
469
 * Thus, using g.d.s.setAnchorHref on an (incorrectly statically typed) object
470
 * of type HTMLLinkElement can result in a security vulnerability.
471
 * Assertions of the correct run-time type help prevent such incorrect use.
472
 *
473
 * In some cases, code using the DOM API is tested using mock objects (e.g., a
474
 * plain object such as {'href': url} instead of an actual Location object).
475
 * To allow such mocking, the assertions permit objects of types that are not
476
 * relevant DOM API objects at all (for instance, not Element or Location).
477
 *
478
 * Note that instanceof checks don't work straightforwardly in older versions of
479
 * IE, or across frames (see,
480
 * http://stackoverflow.com/questions/384286/javascript-isdom-how-do-you-check-if-a-javascript-object-is-a-dom-object,
481
 * http://stackoverflow.com/questions/26248599/instanceof-htmlelement-in-iframe-is-not-element-or-object).
482
 *
483
 * Hence, these assertions may pass vacuously in such scenarios. The resulting
484
 * risk of security bugs is limited by the following factors:
485
 *  - A bug can only arise in scenarios involving incorrect static typing (the
486
 *    wrapper methods are statically typed to demand objects of the appropriate,
487
 *    precise type).
488
 *  - Operations on elements across frames are relatively rare.
489
 *  - Typically, code is tested and exercised in multiple browsers.
490
 */
491

492
/**
493
 * Asserts that a given object is a Location.
494
 *
495
 * To permit this assertion to pass in the context of tests where DOM APIs might
496
 * be mocked, also accepts any other type except for subtypes of {!Element}.
497
 * This is to ensure that, for instance, HTMLLinkElement is not being used in
498
 * place of a Location, since this could result in security bugs due to stronger
499
 * contracts required for assignments to the href property of the latter.
500
 *
501
 * @param {?Object} o The object whose type to assert.
502
 * @return {!Location}
503
 * @private
504
 */
505
goog.dom.safe.assertIsLocation_ = function(o) {
506
  if (goog.asserts.ENABLE_ASSERTS && typeof Location != 'undefined' &&
507
      typeof Element != 'undefined') {
508
    goog.asserts.assert(
509
        o && (o instanceof Location || !(o instanceof Element)),
510
        'Argument is not a Location (or a non-Element mock); got: %s',
511
        goog.dom.safe.debugStringForType_(o));
512
  }
513
  return /** @type {!Location} */ (o);
514
};
515

516
/**
517
 * Asserts that a given object is a HTMLAnchorElement.
518
 *
519
 * To permit this assertion to pass in the context of tests where elements might
520
 * be mocked, also accepts objects that are not of type Location nor a subtype
521
 * of Element.
522
 *
523
 * @param {?Object} o The object whose type to assert.
524
 * @return {!HTMLAnchorElement}
525
 * @private
526
 */
527
goog.dom.safe.assertIsHTMLAnchorElement_ = function(o) {
528
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLAnchorElement != 'undefined' &&
529
      typeof Location != 'undefined' && typeof Element != 'undefined') {
530
    goog.asserts.assert(
531
        o && (o instanceof HTMLAnchorElement ||
532
              !((o instanceof Location) || (o instanceof Element))),
533
        'Argument is not a HTMLAnchorElement (or a non-Element mock); got: %s',
534
        goog.dom.safe.debugStringForType_(o));
535
  }
536
  return /** @type {!HTMLAnchorElement} */ (o);
537
};
538

539
/**
540
 * Asserts that a given object is a HTMLLinkElement.
541
 *
542
 * To permit this assertion to pass in the context of tests where elements might
543
 * be mocked, also accepts objects that are not a subtype of Element.
544
 *
545
 * @param {?Object} o The object whose type to assert.
546
 * @return {!HTMLLinkElement}
547
 * @private
548
 */
549
goog.dom.safe.assertIsHTMLLinkElement_ = function(o) {
550
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLLinkElement != 'undefined' &&
551
      typeof Location != 'undefined' && typeof Element != 'undefined') {
552
    goog.asserts.assert(
553
        o && (o instanceof HTMLLinkElement ||
554
              !((o instanceof Location) || (o instanceof Element))),
555
        'Argument is not a HTMLLinkElement (or a non-Element mock); got: %s',
556
        goog.dom.safe.debugStringForType_(o));
557
  }
558
  return /** @type {!HTMLLinkElement} */ (o);
559
};
560

561
/**
562
 * Asserts that a given object is a HTMLImageElement.
563
 *
564
 * To permit this assertion to pass in the context of tests where elements might
565
 * be mocked, also accepts objects that are not a subtype of Element.
566
 *
567
 * @param {?Object} o The object whose type to assert.
568
 * @return {!HTMLImageElement}
569
 * @private
570
 */
571
goog.dom.safe.assertIsHTMLImageElement_ = function(o) {
572
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLImageElement != 'undefined' &&
573
      typeof Element != 'undefined') {
574
    goog.asserts.assert(
575
        o && (o instanceof HTMLImageElement || !(o instanceof Element)),
576
        'Argument is not a HTMLImageElement (or a non-Element mock); got: %s',
577
        goog.dom.safe.debugStringForType_(o));
578
  }
579
  return /** @type {!HTMLImageElement} */ (o);
580
};
581

582
/**
583
 * Asserts that a given object is a HTMLEmbedElement.
584
 *
585
 * To permit this assertion to pass in the context of tests where elements might
586
 * be mocked, also accepts objects that are not a subtype of Element.
587
 *
588
 * @param {?Object} o The object whose type to assert.
589
 * @return {!HTMLEmbedElement}
590
 * @private
591
 */
592
goog.dom.safe.assertIsHTMLEmbedElement_ = function(o) {
593
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLEmbedElement != 'undefined' &&
594
      typeof Element != 'undefined') {
595
    goog.asserts.assert(
596
        o && (o instanceof HTMLEmbedElement || !(o instanceof Element)),
597
        'Argument is not a HTMLEmbedElement (or a non-Element mock); got: %s',
598
        goog.dom.safe.debugStringForType_(o));
599
  }
600
  return /** @type {!HTMLEmbedElement} */ (o);
601
};
602

603
/**
604
 * Asserts that a given object is a HTMLFrameElement.
605
 *
606
 * To permit this assertion to pass in the context of tests where elements might
607
 * be mocked, also accepts objects that are not a subtype of Element.
608
 *
609
 * @param {?Object} o The object whose type to assert.
610
 * @return {!HTMLFrameElement}
611
 * @private
612
 */
613
goog.dom.safe.assertIsHTMLFrameElement_ = function(o) {
614
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLFrameElement != 'undefined' &&
615
      typeof Element != 'undefined') {
616
    goog.asserts.assert(
617
        o && (o instanceof HTMLFrameElement || !(o instanceof Element)),
618
        'Argument is not a HTMLFrameElement (or a non-Element mock); got: %s',
619
        goog.dom.safe.debugStringForType_(o));
620
  }
621
  return /** @type {!HTMLFrameElement} */ (o);
622
};
623

624
/**
625
 * Asserts that a given object is a HTMLIFrameElement.
626
 *
627
 * To permit this assertion to pass in the context of tests where elements might
628
 * be mocked, also accepts objects that are not a subtype of Element.
629
 *
630
 * @param {?Object} o The object whose type to assert.
631
 * @return {!HTMLIFrameElement}
632
 * @private
633
 */
634
goog.dom.safe.assertIsHTMLIFrameElement_ = function(o) {
635
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLIFrameElement != 'undefined' &&
636
      typeof Element != 'undefined') {
637
    goog.asserts.assert(
638
        o && (o instanceof HTMLIFrameElement || !(o instanceof Element)),
639
        'Argument is not a HTMLIFrameElement (or a non-Element mock); got: %s',
640
        goog.dom.safe.debugStringForType_(o));
641
  }
642
  return /** @type {!HTMLIFrameElement} */ (o);
643
};
644

645
/**
646
 * Asserts that a given object is a HTMLObjectElement.
647
 *
648
 * To permit this assertion to pass in the context of tests where elements might
649
 * be mocked, also accepts objects that are not a subtype of Element.
650
 *
651
 * @param {?Object} o The object whose type to assert.
652
 * @return {!HTMLObjectElement}
653
 * @private
654
 */
655
goog.dom.safe.assertIsHTMLObjectElement_ = function(o) {
656
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLObjectElement != 'undefined' &&
657
      typeof Element != 'undefined') {
658
    goog.asserts.assert(
659
        o && (o instanceof HTMLObjectElement || !(o instanceof Element)),
660
        'Argument is not a HTMLObjectElement (or a non-Element mock); got: %s',
661
        goog.dom.safe.debugStringForType_(o));
662
  }
663
  return /** @type {!HTMLObjectElement} */ (o);
664
};
665

666
/**
667
 * Asserts that a given object is a HTMLScriptElement.
668
 *
669
 * To permit this assertion to pass in the context of tests where elements might
670
 * be mocked, also accepts objects that are not a subtype of Element.
671
 *
672
 * @param {?Object} o The object whose type to assert.
673
 * @return {!HTMLScriptElement}
674
 * @private
675
 */
676
goog.dom.safe.assertIsHTMLScriptElement_ = function(o) {
677
  if (goog.asserts.ENABLE_ASSERTS && typeof HTMLScriptElement != 'undefined' &&
678
      typeof Element != 'undefined') {
679
    goog.asserts.assert(
680
        o && (o instanceof HTMLScriptElement || !(o instanceof Element)),
681
        'Argument is not a HTMLScriptElement (or a non-Element mock); got: %s',
682
        goog.dom.safe.debugStringForType_(o));
683
  }
684
  return /** @type {!HTMLScriptElement} */ (o);
685
};
686

687
/**
688
 * Returns a string representation of a value's type.
689
 *
690
 * @param {*} value An object, or primitive.
691
 * @return {string} The best display name for the value.
692
 * @private
693
 */
694
goog.dom.safe.debugStringForType_ = function(value) {
695
  if (goog.isObject(value)) {
696
    return value.constructor.displayName || value.constructor.name ||
697
        Object.prototype.toString.call(value);
698
  } else {
699
    return value === undefined ? 'undefined' :
700
                                 value === null ? 'null' : typeof value;
701
  }
702
};
703

704