Debian Codegraph @

closure-library/closure/goog/html/sanitizer/unsafe.js

raw
1 // Copyright 2016 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 Potentially unsafe API for the HTML sanitizer.
17 *
18 * The HTML sanitizer enforces a default a safe policy, and also limits how the
19 * policy can be relaxed, so that developers cannot misconfigure it and
20 * introduce vulnerabilities.
21 *
22 * This file extends the HTML sanitizer's capabilities with potentially unsafe
23 * configuration options, such as the ability to extend the tag whitelist (e.g.
24 * to support web components).
25 *
26 * @supported IE 10+, Chrome 26+, Firefox 22+, Safari 7.1+, Opera 15+
27 * @visibility {//closure/goog/html/sanitizer:approved_for_unsafe_config}
28 */
29
30 goog.provide('goog.html.sanitizer.unsafe');
31
32 goog.require('goog.asserts');
33 goog.require('goog.html.sanitizer.HtmlSanitizer.Builder');
34 goog.require('goog.string');
35 goog.require('goog.string.Const');
36
37
38 /**
39 * Extends the tag whitelist with the list of tags provided.
40 *
41 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
42 * that the new tags do not introduce untrusted code execution or unsanctioned
43 * network activity.
44 *
45 * @param {!goog.string.Const} justification A constant string explaining why
46 * the addition of these tags to the whitelist is safe. May include a
47 * security review ticket number.
48 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
49 * whose tag whitelist should be extended.
50 * @param {!Array<string>} tags A list of additional tags to allow through the
51 * sanitizer. Note that if the tag is also present in the blacklist,
52 * its addition to the whitelist has no effect. The tag names are
53 * case-insensitive.
54 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
55 */
56 goog.html.sanitizer.unsafe.alsoAllowTags = function(
57 justification, builder, tags) {
58 goog.asserts.assertString(
59 goog.string.Const.unwrap(justification), 'must provide justification');
60 goog.asserts.assert(
61 !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
62 'must provide non-empty justification');
63 return builder.alsoAllowTagsPrivateDoNotAccessOrElse(tags);
64 };
65
66 /**
67 * Installs custom attribute policies for the attributes provided in the list.
68 * This can be used either on non-whitelisted attributes, effectively extending
69 * the attribute whitelist, or on attributes that are whitelisted and already
70 * have a policy, to override their policies.
71 *
72 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
73 * that the new tags do not introduce untrusted code execution or unsanctioned
74 * network activity.
75 *
76 * @param {!goog.string.Const} justification A constant string explaining why
77 * the addition of these attributes to the whitelist is safe. May include a
78 * security review ticket number.
79 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
80 * whose attribute whitelist should be extended.
81 * @param {!Array<(string|!goog.html.sanitizer.HtmlSanitizerAttributePolicy)>}
82 * attrs A list of attributes whose policy should be overridden. Attributes
83 * can come in of two forms:
84 * - string: allow all values and just trim whitespaces for this attribute
85 * on all tags.
86 * - HtmlSanitizerAttributePolicy: allows specifying a policy for a
87 * particular tag. The tagName can be '*', which means all tags. If no
88 * policy is passed, the default is allow all values and just trim
89 * whitespaces.
90 * The tag and attribute names are case-insensitive.
91 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
92 */
93 goog.html.sanitizer.unsafe.alsoAllowAttributes = function(
94 justification, builder, attrs) {
95 goog.asserts.assertString(
96 goog.string.Const.unwrap(justification), 'must provide justification');
97 goog.asserts.assert(
98 !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
99 'must provide non-empty justification');
100 return builder.alsoAllowAttributesPrivateDoNotAccessOrElse(attrs);
101 };
102
103
104 /**
105 * Turns off sanitization of TEMPLATE tag descendants. The output is still
106 * safe to consume as a whole, but clients need to handle the contents of
107 * TEMPLATE nodes carefully, hence its definition in the unsafe package.
108 *
109 * Note that this only applies to descendants of unsanitized template tags, not
110 * to the tag itself, which must be manually added to the whitelist and removed
111 * from the blacklist.
112 *
113 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
114 * that the new tags do not introduce untrusted code execution or unsanctioned
115 * network activity.
116 *
117 * @param {!goog.string.Const} justification A constant string explaining why
118 * the templates should not be sanitized, and why this is safe. May include
119 * a security review ticket number.
120 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
121 * whose template tag descendants should not be sanitized.
122 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
123 * @throws {Error} Thrown if the browser does not support TEMPLATE tags.
124 * In this case, careful post-sanitization handling wouldn't matter.
125 */
126 goog.html.sanitizer.unsafe.keepUnsanitizedTemplateContents = function(
127 justification, builder) {
128 goog.asserts.assertString(
129 goog.string.Const.unwrap(justification), 'must provide justification');
130 goog.asserts.assert(
131 !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
132 'must provide non-empty justification');
133 return builder.keepUnsanitizedTemplateContentsPrivateDoNotAccessOrElse();
134 };