| 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 |
*/ |
| 66 |
goog.html.uncheckedconversions.safeHtmlFromStringKnownToSatisfyTypeContract = |
| 67 |
function(justification, html, opt_dir) { |
| 68 |
// unwrap() called inside an assert so that justification can be optimized |
| 69 |
// away in production code. |
| 70 |
goog.asserts.assertString( |
| 71 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 72 |
goog.asserts.assert( |
| 73 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 74 |
'must provide non-empty justification'); |
| 75 |
return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse( |
| 76 |
html, opt_dir || null); |
| 77 |
}; |
| 78 |
|
| 79 |
|
| 80 |
/** |
| 81 |
* Performs an "unchecked conversion" to SafeScript from a plain string that is |
| 82 |
* known to satisfy the SafeScript type contract. |
| 83 |
* |
| 84 |
* IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 85 |
* that the value of {@code script} satisfies the SafeScript type contract in |
| 86 |
* all possible program states. |
| 87 |
* |
| 88 |
* |
| 89 |
* @param {!goog.string.Const} justification A constant string explaining why |
| 90 |
* this use of this method is safe. May include a security review ticket |
| 91 |
* number. |
| 92 |
* @param {string} script The string to wrap as a SafeScript. |
| 93 |
* @return {!goog.html.SafeScript} The value of {@code script}, wrapped in a |
| 94 |
* SafeScript object. |
| 95 |
*/ |
| 96 |
goog.html.uncheckedconversions.safeScriptFromStringKnownToSatisfyTypeContract = |
| 97 |
function(justification, script) { |
| 98 |
// unwrap() called inside an assert so that justification can be optimized |
| 99 |
// away in production code. |
| 100 |
goog.asserts.assertString( |
| 101 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 102 |
goog.asserts.assert( |
| 103 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 104 |
'must provide non-empty justification'); |
| 105 |
return goog.html.SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse( |
| 106 |
script); |
| 107 |
}; |
| 108 |
|
| 109 |
|
| 110 |
/** |
| 111 |
* Performs an "unchecked conversion" to SafeStyle from a plain string that is |
| 112 |
* known to satisfy the SafeStyle type contract. |
| 113 |
* |
| 114 |
* IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 115 |
* that the value of {@code style} satisfies the SafeStyle type contract in all |
| 116 |
* possible program states. |
| 117 |
* |
| 118 |
* |
| 119 |
* @param {!goog.string.Const} justification A constant string explaining why |
| 120 |
* this use of this method is safe. May include a security review ticket |
| 121 |
* number. |
| 122 |
* @param {string} style The string to wrap as a SafeStyle. |
| 123 |
* @return {!goog.html.SafeStyle} The value of {@code style}, wrapped in a |
| 124 |
* SafeStyle object. |
| 125 |
*/ |
| 126 |
goog.html.uncheckedconversions.safeStyleFromStringKnownToSatisfyTypeContract = |
| 127 |
function(justification, style) { |
| 128 |
// unwrap() called inside an assert so that justification can be optimized |
| 129 |
// away in production code. |
| 130 |
goog.asserts.assertString( |
| 131 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 132 |
goog.asserts.assert( |
| 133 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 134 |
'must provide non-empty justification'); |
| 135 |
return goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse( |
| 136 |
style); |
| 137 |
}; |
| 138 |
|
| 139 |
|
| 140 |
/** |
| 141 |
* Performs an "unchecked conversion" to SafeStyleSheet from a plain string |
| 142 |
* that is known to satisfy the SafeStyleSheet type contract. |
| 143 |
* |
| 144 |
* IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 145 |
* that the value of {@code styleSheet} satisfies the SafeStyleSheet type |
| 146 |
* contract in all possible program states. |
| 147 |
* |
| 148 |
* |
| 149 |
* @param {!goog.string.Const} justification A constant string explaining why |
| 150 |
* this use of this method is safe. May include a security review ticket |
| 151 |
* number. |
| 152 |
* @param {string} styleSheet The string to wrap as a SafeStyleSheet. |
| 153 |
* @return {!goog.html.SafeStyleSheet} The value of {@code styleSheet}, wrapped |
| 154 |
* in a SafeStyleSheet object. |
| 155 |
*/ |
| 156 |
goog.html.uncheckedconversions |
| 157 |
.safeStyleSheetFromStringKnownToSatisfyTypeContract = function( |
| 158 |
justification, styleSheet) { |
| 159 |
// unwrap() called inside an assert so that justification can be optimized |
| 160 |
// away in production code. |
| 161 |
goog.asserts.assertString( |
| 162 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 163 |
goog.asserts.assert( |
| 164 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 165 |
'must provide non-empty justification'); |
| 166 |
return goog.html.SafeStyleSheet |
| 167 |
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheet); |
| 168 |
}; |
| 169 |
|
| 170 |
|
| 171 |
/** |
| 172 |
* Performs an "unchecked conversion" to SafeUrl from a plain string that is |
| 173 |
* known to satisfy the SafeUrl type contract. |
| 174 |
* |
| 175 |
* IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 176 |
* that the value of {@code url} satisfies the SafeUrl type contract in all |
| 177 |
* possible program states. |
| 178 |
* |
| 179 |
* |
| 180 |
* @param {!goog.string.Const} justification A constant string explaining why |
| 181 |
* this use of this method is safe. May include a security review ticket |
| 182 |
* number. |
| 183 |
* @param {string} url The string to wrap as a SafeUrl. |
| 184 |
* @return {!goog.html.SafeUrl} The value of {@code url}, wrapped in a SafeUrl |
| 185 |
* object. |
| 186 |
*/ |
| 187 |
goog.html.uncheckedconversions.safeUrlFromStringKnownToSatisfyTypeContract = |
| 188 |
function(justification, url) { |
| 189 |
// unwrap() called inside an assert so that justification can be optimized |
| 190 |
// away in production code. |
| 191 |
goog.asserts.assertString( |
| 192 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 193 |
goog.asserts.assert( |
| 194 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 195 |
'must provide non-empty justification'); |
| 196 |
return goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse(url); |
| 197 |
}; |
| 198 |
|
| 199 |
|
| 200 |
/** |
| 201 |
* Performs an "unchecked conversion" to TrustedResourceUrl from a plain string |
| 202 |
* that is known to satisfy the TrustedResourceUrl type contract. |
| 203 |
* |
| 204 |
* IMPORTANT: Uses of this method must be carefully security-reviewed to ensure |
| 205 |
* that the value of {@code url} satisfies the TrustedResourceUrl type contract |
| 206 |
* in all possible program states. |
| 207 |
* |
| 208 |
* |
| 209 |
* @param {!goog.string.Const} justification A constant string explaining why |
| 210 |
* this use of this method is safe. May include a security review ticket |
| 211 |
* number. |
| 212 |
* @param {string} url The string to wrap as a TrustedResourceUrl. |
| 213 |
* @return {!goog.html.TrustedResourceUrl} The value of {@code url}, wrapped in |
| 214 |
* a TrustedResourceUrl object. |
| 215 |
*/ |
| 216 |
goog.html.uncheckedconversions |
| 217 |
.trustedResourceUrlFromStringKnownToSatisfyTypeContract = function( |
| 218 |
justification, url) { |
| 219 |
// unwrap() called inside an assert so that justification can be optimized |
| 220 |
// away in production code. |
| 221 |
goog.asserts.assertString( |
| 222 |
goog.string.Const.unwrap(justification), 'must provide justification'); |
| 223 |
goog.asserts.assert( |
| 224 |
!goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)), |
| 225 |
'must provide non-empty justification'); |
| 226 |
return goog.html.TrustedResourceUrl |
| 227 |
.createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse(url); |
| 228 |
}; |