Debian Codegraph @

closure-library/closure/goog/soy/data.js

raw
1 // Copyright 2012 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 Soy data primitives.
17 *
18 * The goal is to encompass data types used by Soy, especially to mark content
19 * as known to be "safe".
20 *
21 * @author [email protected] (Garrett Boyer)
22 */
23
24 goog.provide('goog.soy.data.SanitizedContent');
25 goog.provide('goog.soy.data.SanitizedContentKind');
26 goog.provide('goog.soy.data.SanitizedCss');
27 goog.provide('goog.soy.data.SanitizedHtml');
28 goog.provide('goog.soy.data.SanitizedHtmlAttribute');
29 goog.provide('goog.soy.data.SanitizedJs');
30 goog.provide('goog.soy.data.SanitizedStyle');
31 goog.provide('goog.soy.data.SanitizedTrustedResourceUri');
32 goog.provide('goog.soy.data.SanitizedUri');
33 goog.provide('goog.soy.data.UnsanitizedText');
34
35 goog.require('goog.Uri');
36 goog.require('goog.asserts');
37 goog.require('goog.html.SafeHtml');
38 goog.require('goog.html.SafeScript');
39 goog.require('goog.html.SafeStyle');
40 goog.require('goog.html.SafeStyleSheet');
41 goog.require('goog.html.SafeUrl');
42 goog.require('goog.html.TrustedResourceUrl');
43 goog.require('goog.html.uncheckedconversions');
44 goog.require('goog.i18n.bidi.Dir');
45 goog.require('goog.string.Const');
46
47
48 /**
49 * A type of textual content.
50 *
51 * This is an enum of type Object so that these values are unforgeable.
52 *
53 * @enum {!Object}
54 */
55 goog.soy.data.SanitizedContentKind = {
56
57 /**
58 * A snippet of HTML that does not start or end inside a tag, comment, entity,
59 * or DOCTYPE; and that does not contain any executable code
60 * (JS, {@code <object>}s, etc.) from a different trust domain.
61 */
62 HTML: goog.DEBUG ? {sanitizedContentKindHtml: true} : {},
63
64 /**
65 * Executable Javascript code or expression, safe for insertion in a
66 * script-tag or event handler context, known to be free of any
67 * attacker-controlled scripts. This can either be side-effect-free
68 * Javascript (such as JSON) or Javascript that's entirely under Google's
69 * control.
70 */
71 JS: goog.DEBUG ? {sanitizedContentJsChars: true} : {},
72
73 /** A properly encoded portion of a URI. */
74 URI: goog.DEBUG ? {sanitizedContentUri: true} : {},
75
76 /** A resource URI not under attacker control. */
77 TRUSTED_RESOURCE_URI:
78 goog.DEBUG ? {sanitizedContentTrustedResourceUri: true} : {},
79
80 /**
81 * Repeated attribute names and values. For example,
82 * {@code dir="ltr" foo="bar" onclick="trustedFunction()" checked}.
83 */
84 ATTRIBUTES: goog.DEBUG ? {sanitizedContentHtmlAttribute: true} : {},
85
86 // TODO: Consider separating rules, declarations, and values into
87 // separate types, but for simplicity, we'll treat explicitly blessed
88 // SanitizedContent as allowed in all of these contexts.
89 /**
90 * A CSS3 declaration, property, value or group of semicolon separated
91 * declarations.
92 */
93 STYLE: goog.DEBUG ? {sanitizedContentStyle: true} : {},
94
95 /** A CSS3 style sheet (list of rules). */
96 CSS: goog.DEBUG ? {sanitizedContentCss: true} : {},
97
98 /**
99 * Unsanitized plain-text content.
100 *
101 * This is effectively the "null" entry of this enum, and is sometimes used
102 * to explicitly mark content that should never be used unescaped. Since any
103 * string is safe to use as text, being of ContentKind.TEXT makes no
104 * guarantees about its safety in any other context such as HTML.
105 */
106 TEXT: goog.DEBUG ? {sanitizedContentKindText: true} : {}
107 };
108
109
110
111 /**
112 * A string-like object that carries a content-type and a content direction.
113 *
114 * IMPORTANT! Do not create these directly, nor instantiate the subclasses.
115 * Instead, use a trusted, centrally reviewed library as endorsed by your team
116 * to generate these objects. Otherwise, you risk accidentally creating
117 * SanitizedContent that is attacker-controlled and gets evaluated unescaped in
118 * templates.
119 *
120 * @constructor
121 */
122 goog.soy.data.SanitizedContent = function() {
123 throw new Error('Do not instantiate directly');
124 };
125
126
127 /**
128 * The context in which this content is safe from XSS attacks.
129 * @type {goog.soy.data.SanitizedContentKind}
130 */
131 goog.soy.data.SanitizedContent.prototype.contentKind;
132
133
134 /**
135 * The content's direction; null if unknown and thus to be estimated when
136 * necessary.
137 * @type {?goog.i18n.bidi.Dir}
138 */
139 goog.soy.data.SanitizedContent.prototype.contentDir = null;
140
141
142 /**
143 * The already-safe content.
144 * @protected {string}
145 */
146 goog.soy.data.SanitizedContent.prototype.content;
147
148
149 /**
150 * Gets the already-safe content.
151 * @return {string}
152 */
153 goog.soy.data.SanitizedContent.prototype.getContent = function() {
154 return this.content;
155 };
156
157
158 /** @override */
159 goog.soy.data.SanitizedContent.prototype.toString = function() {
160 return this.content;
161 };
162
163
164 /**
165 * Converts sanitized content of kind TEXT or HTML into SafeHtml. HTML content
166 * is converted without modification, while text content is HTML-escaped.
167 * @return {!goog.html.SafeHtml}
168 * @throws {Error} when the content kind is not TEXT or HTML.
169 */
170 goog.soy.data.SanitizedContent.prototype.toSafeHtml = function() {
171 if (this.contentKind === goog.soy.data.SanitizedContentKind.TEXT) {
172 return goog.html.SafeHtml.htmlEscape(this.toString());
173 }
174 if (this.contentKind !== goog.soy.data.SanitizedContentKind.HTML) {
175 throw new Error('Sanitized content was not of kind TEXT or HTML.');
176 }
177 return goog.html.uncheckedconversions
178 .safeHtmlFromStringKnownToSatisfyTypeContract(
179 goog.string.Const.from(
180 'Soy SanitizedContent of kind HTML produces ' +
181 'SafeHtml-contract-compliant value.'),
182 this.toString(), this.contentDir);
183 };
184
185
186 /**
187 * Converts sanitized content of kind URI into SafeUrl without modification.
188 * @return {!goog.html.SafeUrl}
189 * @throws {Error} when the content kind is not URI.
190 */
191 goog.soy.data.SanitizedContent.prototype.toSafeUrl = function() {
192 if (this.contentKind !== goog.soy.data.SanitizedContentKind.URI) {
193 throw new Error('Sanitized content was not of kind URI.');
194 }
195 return goog.html.uncheckedconversions
196 .safeUrlFromStringKnownToSatisfyTypeContract(
197 goog.string.Const.from(
198 'Soy SanitizedContent of kind URI produces ' +
199 'SafeHtml-contract-compliant value.'),
200 this.toString());
201 };
202
203
204 /**
205 * Unsanitized plain text string.
206 *
207 * While all strings are effectively safe to use as a plain text, there are no
208 * guarantees about safety in any other context such as HTML. This is
209 * sometimes used to mark that should never be used unescaped.
210 *
211 * @param {*} content Plain text with no guarantees.
212 * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
213 * unknown and thus to be estimated when necessary. Default: null.
214 * @extends {goog.soy.data.SanitizedContent}
215 * @constructor
216 */
217 goog.soy.data.UnsanitizedText = function(content, opt_contentDir) {
218 // Not calling the superclass constructor which just throws an exception.
219
220 /** @override */
221 this.content = String(content);
222 this.contentDir = opt_contentDir != null ? opt_contentDir : null;
223 };
224 goog.inherits(goog.soy.data.UnsanitizedText, goog.soy.data.SanitizedContent);
225
226
227 /** @override */
228 goog.soy.data.UnsanitizedText.prototype.contentKind =
229 goog.soy.data.SanitizedContentKind.TEXT;
230
231
232
233 /**
234 * Content of type {@link goog.soy.data.SanitizedContentKind.HTML}.
235 *
236 * The content is a string of HTML that can safely be embedded in a PCDATA
237 * context in your app. If you would be surprised to find that an HTML
238 * sanitizer produced {@code s} (e.g. it runs code or fetches bad URLs) and
239 * you wouldn't write a template that produces {@code s} on security or privacy
240 * grounds, then don't pass {@code s} here. The default content direction is
241 * unknown, i.e. to be estimated when necessary.
242 *
243 * @extends {goog.soy.data.SanitizedContent}
244 * @constructor
245 */
246 goog.soy.data.SanitizedHtml = function() {
247 goog.soy.data.SanitizedHtml.base(this, 'constructor');
248 };
249 goog.inherits(goog.soy.data.SanitizedHtml, goog.soy.data.SanitizedContent);
250
251 /** @override */
252 goog.soy.data.SanitizedHtml.prototype.contentKind =
253 goog.soy.data.SanitizedContentKind.HTML;
254
255 /**
256 * Checks if the value could be used as the Soy type {html}.
257 * @param {*} value
258 * @return {boolean}
259 */
260 goog.soy.data.SanitizedHtml.isCompatibleWith = function(value) {
261 return goog.isString(value) ||
262 value instanceof goog.soy.data.SanitizedHtml ||
263 value instanceof goog.soy.data.UnsanitizedText ||
264 value instanceof goog.html.SafeHtml;
265 };
266
267
268
269 /**
270 * Content of type {@link goog.soy.data.SanitizedContentKind.JS}.
271 *
272 * The content is JavaScript source that when evaluated does not execute any
273 * attacker-controlled scripts. The content direction is LTR.
274 *
275 * @extends {goog.soy.data.SanitizedContent}
276 * @constructor
277 */
278 goog.soy.data.SanitizedJs = function() {
279 goog.soy.data.SanitizedJs.base(this, 'constructor');
280 };
281 goog.inherits(goog.soy.data.SanitizedJs, goog.soy.data.SanitizedContent);
282
283 /** @override */
284 goog.soy.data.SanitizedJs.prototype.contentKind =
285 goog.soy.data.SanitizedContentKind.JS;
286
287 /** @override */
288 goog.soy.data.SanitizedJs.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
289
290 /**
291 * Checks if the value could be used as the Soy type {js}.
292 * @param {*} value
293 * @return {boolean}
294 */
295 goog.soy.data.SanitizedJs.isCompatibleWith = function(value) {
296 return goog.isString(value) ||
297 value instanceof goog.soy.data.SanitizedJs ||
298 value instanceof goog.soy.data.UnsanitizedText ||
299 value instanceof goog.html.SafeScript;
300 };
301
302
303
304 /**
305 * Content of type {@link goog.soy.data.SanitizedContentKind.URI}.
306 *
307 * The content is a URI chunk that the caller knows is safe to emit in a
308 * template. The content direction is LTR.
309 *
310 * @extends {goog.soy.data.SanitizedContent}
311 * @constructor
312 */
313 goog.soy.data.SanitizedUri = function() {
314 goog.soy.data.SanitizedUri.base(this, 'constructor');
315 };
316 goog.inherits(goog.soy.data.SanitizedUri, goog.soy.data.SanitizedContent);
317
318 /** @override */
319 goog.soy.data.SanitizedUri.prototype.contentKind =
320 goog.soy.data.SanitizedContentKind.URI;
321
322 /** @override */
323 goog.soy.data.SanitizedUri.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
324
325 /**
326 * Checks if the value could be used as the Soy type {uri}.
327 * @param {*} value
328 * @return {boolean}
329 */
330 goog.soy.data.SanitizedUri.isCompatibleWith = function(value) {
331 return goog.isString(value) ||
332 value instanceof goog.soy.data.SanitizedUri ||
333 value instanceof goog.soy.data.UnsanitizedText ||
334 value instanceof goog.html.SafeUrl ||
335 value instanceof goog.html.TrustedResourceUrl ||
336 value instanceof goog.Uri;
337 };
338
339
340
341 /**
342 * Content of type
343 * {@link goog.soy.data.SanitizedContentKind.TRUSTED_RESOURCE_URI}.
344 *
345 * The content is a TrustedResourceUri chunk that is not under attacker control.
346 * The content direction is LTR.
347 *
348 * @extends {goog.soy.data.SanitizedContent}
349 * @constructor
350 */
351 goog.soy.data.SanitizedTrustedResourceUri = function() {
352 goog.soy.data.SanitizedTrustedResourceUri.base(this, 'constructor');
353 };
354 goog.inherits(
355 goog.soy.data.SanitizedTrustedResourceUri, goog.soy.data.SanitizedContent);
356
357 /** @override */
358 goog.soy.data.SanitizedTrustedResourceUri.prototype.contentKind =
359 goog.soy.data.SanitizedContentKind.TRUSTED_RESOURCE_URI;
360
361 /** @override */
362 goog.soy.data.SanitizedTrustedResourceUri.prototype.contentDir =
363 goog.i18n.bidi.Dir.LTR;
364
365 /**
366 * Converts sanitized content into TrustedResourceUrl without modification.
367 * @return {!goog.html.TrustedResourceUrl}
368 */
369 goog.soy.data.SanitizedTrustedResourceUri.prototype.toTrustedResourceUrl =
370 function() {
371 return goog.html.uncheckedconversions
372 .trustedResourceUrlFromStringKnownToSatisfyTypeContract(
373 goog.string.Const.from(
374 'Soy SanitizedContent of kind TRUSTED_RESOURCE_URI produces ' +
375 'TrustedResourceUrl-contract-compliant value.'),
376 this.toString());
377 };
378
379 /**
380 * Checks if the value could be used as the Soy type {trusted_resource_uri}.
381 * @param {*} value
382 * @return {boolean}
383 */
384 goog.soy.data.SanitizedTrustedResourceUri.isCompatibleWith = function(value) {
385 return goog.isString(value) ||
386 value instanceof goog.soy.data.SanitizedTrustedResourceUri ||
387 value instanceof goog.soy.data.UnsanitizedText ||
388 value instanceof goog.html.TrustedResourceUrl;
389 };
390
391
392
393 /**
394 * Content of type {@link goog.soy.data.SanitizedContentKind.ATTRIBUTES}.
395 *
396 * The content should be safely embeddable within an open tag, such as a
397 * key="value" pair. The content direction is LTR.
398 *
399 * @extends {goog.soy.data.SanitizedContent}
400 * @constructor
401 */
402 goog.soy.data.SanitizedHtmlAttribute = function() {
403 goog.soy.data.SanitizedHtmlAttribute.base(this, 'constructor');
404 };
405 goog.inherits(
406 goog.soy.data.SanitizedHtmlAttribute, goog.soy.data.SanitizedContent);
407
408 /** @override */
409 goog.soy.data.SanitizedHtmlAttribute.prototype.contentKind =
410 goog.soy.data.SanitizedContentKind.ATTRIBUTES;
411
412 /** @override */
413 goog.soy.data.SanitizedHtmlAttribute.prototype.contentDir =
414 goog.i18n.bidi.Dir.LTR;
415
416 /**
417 * Checks if the value could be used as the Soy type {attribute}.
418 * @param {*} value
419 * @return {boolean}
420 */
421 goog.soy.data.SanitizedHtmlAttribute.isCompatibleWith = function(value) {
422 return goog.isString(value) ||
423 value instanceof goog.soy.data.SanitizedHtmlAttribute ||
424 value instanceof goog.soy.data.UnsanitizedText;
425 };
426
427
428
429 /**
430 * Content of type {@link goog.soy.data.SanitizedContentKind.STYLE}.
431 *
432 * The content is non-attacker-exploitable CSS, such as {@code color:#c3d9ff}.
433 * The content direction is LTR.
434 *
435 * @extends {goog.soy.data.SanitizedContent}
436 * @constructor
437 */
438 goog.soy.data.SanitizedStyle = function() {
439 goog.soy.data.SanitizedStyle.base(this, 'constructor');
440 };
441 goog.inherits(goog.soy.data.SanitizedStyle, goog.soy.data.SanitizedContent);
442
443
444 /** @override */
445 goog.soy.data.SanitizedStyle.prototype.contentKind =
446 goog.soy.data.SanitizedContentKind.STYLE;
447
448
449 /** @override */
450 goog.soy.data.SanitizedStyle.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
451
452
453 /**
454 * Checks if the value could be used as the Soy type {css}.
455 * @param {*} value
456 * @return {boolean}
457 */
458 goog.soy.data.SanitizedStyle.isCompatibleWith = function(value) {
459 return goog.isString(value) ||
460 value instanceof goog.soy.data.SanitizedStyle ||
461 value instanceof goog.soy.data.UnsanitizedText ||
462 value instanceof goog.html.SafeStyle;
463 };
464
465
466
467 /**
468 * Content of type {@link goog.soy.data.SanitizedContentKind.CSS}.
469 *
470 * The content is non-attacker-exploitable CSS, such as {@code @import url(x)}.
471 * The content direction is LTR.
472 *
473 * @extends {goog.soy.data.SanitizedContent}
474 * @constructor
475 */
476 goog.soy.data.SanitizedCss = function() {
477 goog.soy.data.SanitizedCss.base(this, 'constructor');
478 };
479 goog.inherits(goog.soy.data.SanitizedCss, goog.soy.data.SanitizedContent);
480
481
482 /** @override */
483 goog.soy.data.SanitizedCss.prototype.contentKind =
484 goog.soy.data.SanitizedContentKind.CSS;
485
486
487 /** @override */
488 goog.soy.data.SanitizedCss.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
489
490
491 /**
492 * Checks if the value could be used as the Soy type {css}.
493 * @param {*} value
494 * @return {boolean}
495 */
496 goog.soy.data.SanitizedCss.isCompatibleWith = function(value) {
497 return goog.isString(value) ||
498 value instanceof goog.soy.data.SanitizedCss ||
499 value instanceof goog.soy.data.UnsanitizedText ||
500 value instanceof goog.html.SafeStyle || // TODO(jakubvrana): Delete.
501 value instanceof goog.html.SafeStyleSheet;
502 };
503
504
505 /**
506 * Converts SanitizedCss into SafeStyleSheet.
507 * Note: SanitizedCss in Soy represents both SafeStyle and SafeStyleSheet in
508 * Closure. It's about to be split so that SanitizedCss represents only
509 * SafeStyleSheet.
510 * @return {!goog.html.SafeStyleSheet}
511 */
512 goog.soy.data.SanitizedCss.prototype.toSafeStyleSheet = function() {
513 var value = this.toString();
514 // TODO(jakubvrana): Remove this check when there's a separate type for style
515 // declaration.
516 goog.asserts.assert(
517 /[@{]|^\s*$/.test(value),
518 'value doesn\'t look like style sheet: ' + value);
519 return goog.html.uncheckedconversions
520 .safeStyleSheetFromStringKnownToSatisfyTypeContract(
521 goog.string.Const.from(
522 'Soy SanitizedCss produces SafeStyleSheet-contract-compliant ' +
523 'value.'),
524 value);
525 };