Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit a2d6c2e

Browse files
NarretzNarretz
committed
docs: more ngProp docs
1 parent 7dc7feb commit a2d6c2e

File tree

2 files changed

+141
-8
lines changed

2 files changed

+141
-8
lines changed

‎src/ng/compile.js

+140-7
Original file line numberDiff line numberDiff line change
@@ -1074,15 +1074,146 @@
10741074
* Binding expressions to arbitrary properties poses a security risk, as properties like `innerHTML`
10751075
* can insert potentially dangerous HTML into the application, e.g. script tags that execute
10761076
* malicious code.
1077-
* For this reason, `ngProp` requires trusted expression content via
1078-
* Strict Contextual Escaping with the {@link ng.$sce $sce service}. Practically this means
1079-
* that different properties require different trusted content types
1077+
* For this reason, `ngProp` applies Strict Contextual Escaping with the {@link ng.$sce $sce service}.
1078+
* This means vulnerable properties require their content to be "trusted", based on the
1079+
* context of the property. For example, the `iframe[src]` property is in the `RESOURCE_URL` context and
1080+
* `innerHTML` is in the `HTML` context.
1081+
* If you trust the source of the content, you can use {@link ng.$sce#trustAs $sce.trustAs()}, (and
1082+
* the shortcut methods {@link ng.$sce#trustAsHtml $sce.trustAsHtml()} et al.) to create an object
1083+
* that wraps the value and is marked as safe. However, you should only do this if you are sure the
1084+
* value is safe.
1085+
*
1086+
* Based on the context, other options may exist to mark a value as trusted / configure the behavior
1087+
* of {@link ng.$sce}. For example, to the `RESOURCE_URL` context to specific origins, use the
1088+
* {@link $sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider#resourceUrlWhitelist} and
1089+
* {@link $sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider#resourceUrlBlacklist}.
1090+
*
1091+
* {@link ng.$sce#what-trusted-context-types-are-supported- Find out more about the different context types}.
10801092
*
10811093
* ### Sanitization
10821094
*
1083-
* By default, `$sce` will throw an error if it detects potentially dangerous content. However,
1084-
* if you include the {@link ngSanitize ngSanitize module}, it will try to strip the
1085-
* potentially dangerous content, i.e. script tags in the `innerHTML` property.
1095+
* By default, `$sce` will throw an error if it detects untrusted content, and will not bind the
1096+
* content.
1097+
* However, if you include the {@link ngSanitize ngSanitize module}, it will try to sanitize the
1098+
* potentially dangerous content, e.g. strip non-whitelisted tags and attributes when binding to
1099+
* `innerHTML`.
1100+
*
1101+
* @example
1102+
* ### Binding to different contexts
1103+
*
1104+
* <example name="ngProp" module="exampleNgProp">
1105+
* <file name="app.js">
1106+
* angular.module('exampleNgProp', [])
1107+
* .component('main', {
1108+
* templateUrl: 'main.html',
1109+
* controller: function($sce) {
1110+
* this.safeContent = '<strong>Safe content</strong>';
1111+
* this.unsafeContent = '<button onclick="alert(\'Hello XSS!\')">Click for XSS</button>';
1112+
* this.trustedUnsafeContent = $sce.trustAsHtml(this.unsafeContent);
1113+
* }
1114+
* });
1115+
* </file>
1116+
* <file name="main.html">
1117+
* <div>
1118+
* <div class="prop-unit">
1119+
* Binding to a property without security context:
1120+
* <div class="prop-binding" ng-prop-inner_text="$ctrl.safeContent"></div>
1121+
* <span class="prop-note">innerText</span> (safeContent)
1122+
* </div>
1123+
*
1124+
* <div class="prop-unit">
1125+
* "Safe" content that requires a security context will throw because the contents could potentially be dangerous ...
1126+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.safeContent"></div>
1127+
* <span class="prop-note">innerHTML</span> (safeContent)
1128+
* </div>
1129+
*
1130+
* <div class="prop-unit">
1131+
* ... so that actually dangerous content cannot be executed:
1132+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.unsafeContent"></div>
1133+
* <span class="prop-note">innerHTML</span> (unsafeContent)
1134+
* </div>
1135+
*
1136+
* <div class="prop-unit">
1137+
* ... but unsafe Content that has been trusted explicitly works - only do this if you are 100% sure!
1138+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.trustedUnsafeContent"></div>
1139+
* <span class="prop-note">innerHTML</span> (trustedUnsafeContent)
1140+
* </div>
1141+
* </div>
1142+
* </file>
1143+
* <file name="index.html">
1144+
* <main></main>
1145+
* </file>
1146+
* <file name="styles.css">
1147+
* .prop-unit {
1148+
* margin-bottom: 10px;
1149+
* }
1150+
*
1151+
* .prop-binding {
1152+
* min-height: 30px;
1153+
* border: 1px solid blue;
1154+
* }
1155+
*
1156+
* .prop-note {
1157+
* font-family: Monospace;
1158+
* }
1159+
* </file>
1160+
* </example>
1161+
*
1162+
*
1163+
* @example
1164+
* ### Binding unsafe content with ngSanitize
1165+
*
1166+
* <example name="ngProp" module="exampleNgProp" deps="angular-sanitize.js">
1167+
* <file name="app.js">
1168+
* angular.module('exampleNgProp', ['ngSanitize'])
1169+
* .component('main', {
1170+
* templateUrl: 'main.html',
1171+
* controller: function($sce) {
1172+
* this.safeContent = '<strong>Safe content</strong>';
1173+
* this.unsafeContent = '<button onclick="alert(\'Hello XSS!\')">Click for XSS</button>';
1174+
* this.trustedUnsafeContent = $sce.trustAsHtml(this.unsafeContent);
1175+
* }
1176+
* });
1177+
* </file>
1178+
* <file name="main.html">
1179+
* <div>
1180+
* <div class="prop-unit">
1181+
* "Safe" content will be sanitized ...
1182+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.safeContent"></div>
1183+
* <span class="prop-note">innerHTML</span> (safeContent)
1184+
* </div>
1185+
*
1186+
* <div class="prop-unit">
1187+
* ... as will dangerous content:
1188+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.unsafeContent"></div>
1189+
* <span class="prop-note">innerHTML</span> (unsafeContent)
1190+
* </div>
1191+
*
1192+
* <div class="prop-unit">
1193+
* ... and content that has been trusted explicitly works the same as without ngSanitize:
1194+
* <div class="prop-binding" ng-prop-inner_h_t_m_l="$ctrl.trustedUnsafeContent"></div>
1195+
* <span class="prop-note">innerHTML</span> (trustedUnsafeContent)
1196+
* </div>
1197+
* </div>
1198+
* </file>
1199+
* <file name="index.html">
1200+
* <main></main>
1201+
* </file>
1202+
* <file name="styles.css">
1203+
* .prop-unit {
1204+
* margin-bottom: 10px;
1205+
* }
1206+
*
1207+
* .prop-binding {
1208+
* min-height: 30px;
1209+
* border: 1px solid blue;
1210+
* }
1211+
*
1212+
* .prop-note {
1213+
* font-family: Monospace;
1214+
* }
1215+
* </file>
1216+
* </example>
10861217
*
10871218
*/
10881219

@@ -1102,7 +1233,9 @@
11021233
* cases it is not necessary to use `ngOn`. However, AngularJS does not support all events
11031234
* (e.g. the `drop` event in the example above), and
11041235
* [custom elements](https://developer.mozilla.org/docs/Web/Web_Components/Using_custom_elements)
1105-
* often use custom events that are fired like normal DOM events.
1236+
* often use
1237+
* [custom events](https://developer.mozilla.org/docs/Web/Guide/Events/Creating_and_triggering_events)
1238+
* that are fired like normal DOM events.
11061239
*
11071240
* @example
11081241
* ### Bind to built-in DOM events

‎src/ng/sce.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -623,7 +623,7 @@ function $SceDelegateProvider() {
623623
* | `$sce.CSS` | For CSS that's safe to source into the application. Currently unused. Feel free to use it in your own directives. |
624624
* | `$sce.MEDIA_URL` | For URLs that are safe to render as media. Is automatically converted from string by sanitizing when needed. |
625625
* | `$sce.URL` | For URLs that are safe to follow as links. Is automatically converted from string by sanitizing when needed. Note that `$sce.URL` makes a stronger statement about the URL than `$sce.MEDIA_URL` does and therefore contexts requiring values trusted for `$sce.URL` can be used anywhere that values trusted for `$sce.MEDIA_URL` are required.|
626-
* | `$sce.RESOURCE_URL` | For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include `ng-include`, `src` / `ngSrc` bindings for tags other than `IMG` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` or `$sce.MEDIA_URL` do and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` or `$sce.MEDIA_URL` are required. |
626+
* | `$sce.RESOURCE_URL` | For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include `ng-include`, `src` / `ngSrc` bindings for tags other than `IMG` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` or `$sce.MEDIA_URL` do and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` or `$sce.MEDIA_URL` are required. <br><br> The {@link $sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider#resourceUrlWhitelist()} and {@link $sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider#resourceUrlBlacklist()} can be used to restrict trusted origins for `RESOURCE_URL` |
627627
* | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently unused. Feel free to use it in your own directives. |
628628
*
629629
*

0 commit comments

Comments
 (0)