1 | declare 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 | }
|