UNPKG

3.75 kBTypeScriptView Raw
1declare module '@ember/-internals/glimmer/lib/utils/string' {
2 /**
3 @module @ember/template
4 */
5 import type { SafeString as GlimmerSafeString } from '@glimmer/runtime';
6 /**
7 A wrapper around a string that has been marked as safe ("trusted"). **When
8 rendered in HTML, Ember will not perform any escaping.**
9
10 Note:
11
12 1. This does not *make* the string safe; it means that some code in your
13 application has *marked* it as safe using the `htmlSafe()` function.
14
15 2. The only public API for getting a `SafeString` is calling `htmlSafe()`. It
16 is *not* user-constructible.
17
18 If a string contains user inputs or other untrusted data, you must sanitize
19 the string before using the `htmlSafe` method. Otherwise your code is
20 vulnerable to [Cross-Site Scripting][xss]. There are many open source
21 sanitization libraries to choose from, both for front end and server-side
22 sanitization.
23
24 [xss]: https://owasp.org/www-community/attacks/DOM_Based_XSS
25
26 ```javascript
27 import { htmlSafe } from '@ember/template';
28
29 let someTrustedOrSanitizedString = "<div>Hello!</div>"
30
31 htmlSafe(someTrustedorSanitizedString);
32 ```
33
34 @for @ember/template
35 @class SafeString
36 @since 4.12.0
37 @public
38 */
39 export class SafeString implements GlimmerSafeString {
40 private __string;
41 constructor(string: string);
42 /**
43 Get the string back to use as a string.
44
45 @public
46 @method toString
47 @returns {String} The string marked as trusted
48 */
49 toString(): string;
50 /**
51 Get the wrapped string as HTML to use without escaping.
52
53 @public
54 @method toHTML
55 @returns {String} the trusted string, without any escaping applied
56 */
57 toHTML(): string;
58 }
59 export function escapeExpression(string: unknown): string;
60 /**
61 Use this method to indicate that a string should be rendered as HTML
62 when the string is used in a template. To say this another way,
63 strings marked with `htmlSafe` will not be HTML escaped.
64
65 A word of warning - The `htmlSafe` method does not make the string safe;
66 it only tells the framework to treat the string as if it is safe to render
67 as HTML. If a string contains user inputs or other untrusted
68 data, you must sanitize the string before using the `htmlSafe` method.
69 Otherwise your code is vulnerable to
70 [Cross-Site Scripting](https://owasp.org/www-community/attacks/DOM_Based_XSS).
71 There are many open source sanitization libraries to choose from,
72 both for front end and server-side sanitization.
73
74 ```javascript
75 import { htmlSafe } from '@ember/template';
76
77 const someTrustedOrSanitizedString = "<div>Hello!</div>"
78
79 htmlSafe(someTrustedorSanitizedString)
80 ```
81
82 @method htmlSafe
83 @for @ember/template
84 @param str {String} The string to treat as trusted.
85 @static
86 @return {SafeString} A string that will not be HTML escaped by Handlebars.
87 @public
88 */
89 export function htmlSafe(str: string): SafeString;
90 /**
91 Detects if a string was decorated using `htmlSafe`.
92
93 ```javascript
94 import { htmlSafe, isHTMLSafe } from '@ember/template';
95
96 let plainString = 'plain string';
97 let safeString = htmlSafe('<div>someValue</div>');
98
99 isHTMLSafe(plainString); // false
100 isHTMLSafe(safeString); // true
101 ```
102
103 @method isHTMLSafe
104 @for @ember/template
105 @static
106 @return {Boolean} `true` if the string was decorated with `htmlSafe`, `false` otherwise.
107 @public
108 */
109 export function isHTMLSafe(str: unknown): str is SafeString;
110}