| 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 Unchecked conversions to create values of goog.html types from |
| 17 | * plain strings. Use of these functions could potentially result in instances |
| 18 | * of goog.html types that violate their type contracts, and hence result in |
| 19 | * security vulnerabilties. |
| 20 | * |
| 21 | * Therefore, all uses of the methods herein must be carefully security |
| 22 | * reviewed. Avoid use of the methods in this file whenever possible; instead |
| 23 | * prefer to create instances of goog.html types using inherently safe builders |
| 24 | * or template systems. |
| 25 | * |
| 26 | * |
| 27 | * |
| 28 | * @visibility {//closure/goog/html:approved_for_unchecked_conversion} |
| 29 | * @visibility {//closure/goog/bin/sizetests:__pkg__} |
| 30 | */ |
| 31 | |
| 32 | |
| 33 | goog.provide('goog.html.uncheckedconversions'); |
| 34 | |
| 35 | goog.require('goog.asserts'); |
| 36 | goog.require('goog.html.SafeHtml'); |
| 37 | goog.require('goog.html.SafeScript'); |
| 38 | goog.require('goog.html.SafeStyle'); |
| 39 | goog.require('goog.html.SafeStyleSheet'); |
| 40 | goog.require('goog.html.SafeUrl'); |
| 41 | goog.require('goog.html.TrustedResourceUrl'); |
| 42 | goog.require('goog.string'); |
| 43 | goog.require('goog.string.Const'); |
| 44 | |
| 45 | |
| 46 | /** |
| 47 | * Performs an "unchecked conversion" to SafeHtml from a plain string that is |
| 48 | * known to satisfy the SafeHtml type contract. |
| 49 | * |
| 50 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 51 | * that the value of {@code html} satisfies the SafeHtml type contract in all |
| 52 | * possible program states. |
| 53 | * |
| 54 | * |
| 55 | * @param {!goog.string.Const} justification A constant string explaining why |
| 56 | * this use of this method is safe. May include a security review ticket |
| 57 | * number. |
| 58 | * @param {string} html A string that is claimed to adhere to the SafeHtml |
| 59 | * contract. |
| 60 | * @param {?goog.i18n.bidi.Dir=} opt_dir The optional directionality of the |
| 61 | * SafeHtml to be constructed. A null or undefined value signifies an |
| 62 | * unknown directionality. |
| 63 | * @return {!goog.html.SafeHtml} The value of html, wrapped in a SafeHtml |
| 64 | * object. |
| 65 | * @suppress {visibility} For access to SafeHtml.create... Note that this |
| 66 | * use is appropriate since this method is intended to be "package private" |
| 67 | * withing goog.html. DO NOT call SafeHtml.create... from outside this |
| 68 | * package; use appropriate wrappers instead. |
| 69 | */ |
| 70 | goog.html.uncheckedconversions.safeHtmlFromStringKnownToSatisfyTypeContract = |
| 71 | function(justification, html, opt_dir) { |
| 72 | // unwrap() called inside an assert so that justification can be optimized |
| 73 | // away in production code. |
| 74 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 75 | 'must provide justification'); |
| 76 | goog.asserts.assert( |
| 77 | !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 78 | 'must provide non-empty justification'); |
| 79 | return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse( |
| 80 | html, opt_dir || null); |
| 81 | }; |
| 82 | |
| 83 | |
| 84 | /** |
| 85 | * Performs an "unchecked conversion" to SafeScript from a plain string that is |
| 86 | * known to satisfy the SafeScript type contract. |
| 87 | * |
| 88 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 89 | * that the value of {@code script} satisfies the SafeScript type contract in |
| 90 | * all possible program states. |
| 91 | * |
| 92 | * |
| 93 | * @param {!goog.string.Const} justification A constant string explaining why |
| 94 | * this use of this method is safe. May include a security review ticket |
| 95 | * number. |
| 96 | * @param {string} script The string to wrap as a SafeScript. |
| 97 | * @return {!goog.html.SafeScript} The value of {@code script}, wrapped in a |
| 98 | * SafeScript object. |
| 99 | */ |
| 100 | goog.html.uncheckedconversions.safeScriptFromStringKnownToSatisfyTypeContract = |
| 101 | function(justification, script) { |
| 102 | // unwrap() called inside an assert so that justification can be optimized |
| 103 | // away in production code. |
| 104 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 105 | 'must provide justification'); |
| 106 | goog.asserts.assert( |
| 107 | !goog.string.isEmpty(goog.string.Const.unwrap(justification)), |
| 108 | 'must provide non-empty justification'); |
| 109 | return goog.html.SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse( |
| 110 | script); |
| 111 | }; |
| 112 | |
| 113 | |
| 114 | /** |
| 115 | * Performs an "unchecked conversion" to SafeStyle from a plain string that is |
| 116 | * known to satisfy the SafeStyle type contract. |
| 117 | * |
| 118 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 119 | * that the value of {@code style} satisfies the SafeUrl type contract in all |
| 120 | * possible program states. |
| 121 | * |
| 122 | * |
| 123 | * @param {!goog.string.Const} justification A constant string explaining why |
| 124 | * this use of this method is safe. May include a security review ticket |
| 125 | * number. |
| 126 | * @param {string} style The string to wrap as a SafeStyle. |
| 127 | * @return {!goog.html.SafeStyle} The value of {@code style}, wrapped in a |
| 128 | * SafeStyle object. |
| 129 | */ |
| 130 | goog.html.uncheckedconversions.safeStyleFromStringKnownToSatisfyTypeContract = |
| 131 | function(justification, style) { |
| 132 | // unwrap() called inside an assert so that justification can be optimized |
| 133 | // away in production code. |
| 134 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 135 | 'must provide justification'); |
| 136 | goog.asserts.assert( |
| 137 | !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 138 | 'must provide non-empty justification'); |
| 139 | return goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse( |
| 140 | style); |
| 141 | }; |
| 142 | |
| 143 | |
| 144 | /** |
| 145 | * Performs an "unchecked conversion" to SafeStyleSheet from a plain string |
| 146 | * that is known to satisfy the SafeStyleSheet type contract. |
| 147 | * |
| 148 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 149 | * that the value of {@code styleSheet} satisfies the SafeUrl type contract in |
| 150 | * all possible program states. |
| 151 | * |
| 152 | * |
| 153 | * @param {!goog.string.Const} justification A constant string explaining why |
| 154 | * this use of this method is safe. May include a security review ticket |
| 155 | * number. |
| 156 | * @param {string} styleSheet The string to wrap as a SafeStyleSheet. |
| 157 | * @return {!goog.html.SafeStyleSheet} The value of {@code styleSheet}, wrapped |
| 158 | * in a SafeStyleSheet object. |
| 159 | */ |
| 160 | goog.html.uncheckedconversions. |
| 161 | safeStyleSheetFromStringKnownToSatisfyTypeContract = |
| 162 | function(justification, styleSheet) { |
| 163 | // unwrap() called inside an assert so that justification can be optimized |
| 164 | // away in production code. |
| 165 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 166 | 'must provide justification'); |
| 167 | goog.asserts.assert( |
| 168 | !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 169 | 'must provide non-empty justification'); |
| 170 | return goog.html.SafeStyleSheet. |
| 171 | createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheet); |
| 172 | }; |
| 173 | |
| 174 | |
| 175 | /** |
| 176 | * Performs an "unchecked conversion" to SafeUrl from a plain string that is |
| 177 | * known to satisfy the SafeUrl type contract. |
| 178 | * |
| 179 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 180 | * that the value of {@code url} satisfies the SafeUrl type contract in all |
| 181 | * possible program states. |
| 182 | * |
| 183 | * |
| 184 | * @param {!goog.string.Const} justification A constant string explaining why |
| 185 | * this use of this method is safe. May include a security review ticket |
| 186 | * number. |
| 187 | * @param {string} url The string to wrap as a SafeUrl. |
| 188 | * @return {!goog.html.SafeUrl} The value of {@code url}, wrapped in a SafeUrl |
| 189 | * object. |
| 190 | */ |
| 191 | goog.html.uncheckedconversions.safeUrlFromStringKnownToSatisfyTypeContract = |
| 192 | function(justification, url) { |
| 193 | // unwrap() called inside an assert so that justification can be optimized |
| 194 | // away in production code. |
| 195 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 196 | 'must provide justification'); |
| 197 | goog.asserts.assert( |
| 198 | !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 199 | 'must provide non-empty justification'); |
| 200 | return goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse(url); |
| 201 | }; |
| 202 | |
| 203 | |
| 204 | /** |
| 205 | * Performs an "unchecked conversion" to TrustedResourceUrl from a plain string |
| 206 | * that is known to satisfy the TrustedResourceUrl type contract. |
| 207 | * |
| 208 | * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 209 | * that the value of {@code url} satisfies the TrustedResourceUrl type contract |
| 210 | * in all possible program states. |
| 211 | * |
| 212 | * |
| 213 | * @param {!goog.string.Const} justification A constant string explaining why |
| 214 | * this use of this method is safe. May include a security review ticket |
| 215 | * number. |
| 216 | * @param {string} url The string to wrap as a TrustedResourceUrl. |
| 217 | * @return {!goog.html.TrustedResourceUrl} The value of {@code url}, wrapped in |
| 218 | * a TrustedResourceUrl object. |
| 219 | */ |
| 220 | goog.html.uncheckedconversions. |
| 221 | trustedResourceUrlFromStringKnownToSatisfyTypeContract = |
| 222 | function(justification, url) { |
| 223 | // unwrap() called inside an assert so that justification can be optimized |
| 224 | // away in production code. |
| 225 | goog.asserts.assertString(goog.string.Const.unwrap(justification), |
| 226 | 'must provide justification'); |
| 227 | goog.asserts.assert( |
| 228 | !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 229 | 'must provide non-empty justification'); |
| 230 | return goog.html.TrustedResourceUrl. |
| 231 | createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse(url); |
| 232 | }; |