From d346a005566f595331eb02fd0606e3515df2e860 Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Mon, 20 Feb 2017 16:59:05 +0100 Subject: [PATCH 1/6] doc($sce): Overhaul the $sce service's documentation. A big docs update around the $sce: there's a lot of content in there that's often misunderstood, and some of the documentation starts to get really old too. --- src/ng/sce.js | 273 +++++++++++++++++++++++++++++++------------------- 1 file changed, 168 insertions(+), 105 deletions(-) diff --git a/src/ng/sce.js b/src/ng/sce.js index 03c382581aab..8413f444d016 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -16,12 +16,22 @@ var $sceMinErr = minErr('$sce'); var SCE_CONTEXTS = { + // HTML is used when there's HTML rendered (e.g. ng-bind-html, iframe srcdoc + // binding). HTML: 'html', + + // Style statements or stylesheets. Currently unused in AngularJS. CSS: 'css', + + // An URL used in a context where it does not refer to a resource that loads + // code. Currently unused in AngularJS. URL: 'url', - // RESOURCE_URL is a subtype of URL used in contexts where a privileged resource is sourced from a - // url. (e.g. ng-include, script src, templateUrl) + + // RESOURCE_URL is a subtype of URL used where the referred-to resource could + // be interpreted as code. (e.g. ng-include, script src binding, templateUrl) RESOURCE_URL: 'resourceUrl', + + // Script. Currently unused in AngularJS. JS: 'js' }; @@ -83,6 +93,16 @@ function adjustMatchers(matchers) { * `$sceDelegate` is a service that is used by the `$sce` service to provide {@link ng.$sce Strict * Contextual Escaping (SCE)} services to AngularJS. * + * For an overview of this service and the functionnality it provides in AngularJS, see the main + * page for {@link ng.$sce SCE}. The current page is targeted for developers who need to alter how + * SCE works in their application, which shouldn't be needed in most cases. + * + *
+ * AngularJS strongly relies on contextual escaping for the security of bindings: disabling or + * modifying this might cause cross site scripting (XSS) vulnerabilities. For libraries owners, + * changes to this service will also influence users, so be extra careful and document your changes. + *
+ * * Typically, you would configure or override the {@link ng.$sceDelegate $sceDelegate} instead of * the `$sce` service to customize the way Strict Contextual Escaping works in AngularJS. This is * because, while the `$sce` provides numerous shorthand methods, etc., you really only need to @@ -108,10 +128,14 @@ function adjustMatchers(matchers) { * @description * * The `$sceDelegateProvider` provider allows developers to configure the {@link ng.$sceDelegate - * $sceDelegate} service. This allows one to get/set the whitelists and blacklists used to ensure - * that the URLs used for sourcing AngularJS templates are safe. Refer {@link - * ng.$sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider.resourceUrlWhitelist} and - * {@link ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist} + * service, used as a delegate for {@link ng.$sce Strict Contextual Escaping (SCE)}. + * + * The `$sceDelegateProvider` allows one to get/set the whitelists and blacklists used to ensure + * that the URLs used for sourcing AngularJS templates and other script-running URLs are safe (all + * RESOURCE_URL sinks). See + * {@link ng.$sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider.resourceUrlWhitelist} + * and + * {@link ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist}, * * For the general details about this service in AngularJS, read the main page for {@link ng.$sce * Strict Contextual Escaping (SCE)}. @@ -140,6 +164,15 @@ function adjustMatchers(matchers) { * ]); * }); * ``` + * Note that an empty whitelist will block every RESOURCE_URL from + * being loaded, and will require you to manually mark each one as trusted with + * $sce.trustAsResourceUrl. However, templates requested by + * {@link ng.$templateRequest $templateRequest} that are present in + * {@link ng.$templateCache $templateCache} will not go through this check. If + * you have a mechanism to populate your templates in that cache at config time, + * then it is a good idea to remove 'self' from that whitelist. This helps to + * mitigate the security impact of certain types of issues, like for instance + * attacker-controlled ng-includes. */ function $SceDelegateProvider() { @@ -161,15 +194,16 @@ function $SceDelegateProvider() { * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items * allowed in this array. * - *
- * **Note:** an empty whitelist array will block all URLs! - *
- * * @return {Array} the currently set whitelist array. * * The **default value** when no whitelist has been explicitly set is `['self']` allowing only * same origin resource requests. * + *
+ * **Note:** the default whitelist of 'self' is not recommanded if your app shares its origin + * with other apps! It is a good idea to limit it to only your application's directory. + *
+ * * @description * Sets/Gets the whitelist of trusted resource URLs. */ @@ -288,17 +322,23 @@ function $SceDelegateProvider() { * @name $sceDelegate#trustAs * * @description - * Returns an object that is trusted by AngularJS for use in specified strict - * contextual escaping contexts (such as ng-bind-html, ng-include, any src - * attribute interpolation, any dom event binding attribute interpolation - * such as for onclick, etc.) that uses the provided value. - * See {@link ng.$sce $sce} for enabling strict contextual escaping. + * Marks the parameter as trusted for the specified context, and returns the + * trusted representation of it. This trusted object should later on be + * used as-is, without any security check, by sinks that use this context. + * For instance, marking a string as trusted for the $sce.HTML context will + * entirely bypass the potential $sanitize call in corresponding $sce.HTML + * sinks, such as an ng-bind-html directive, while using the same value + * passed as a string will cause it to be sanitized. * - * @param {string} type The kind of context in which this value is safe for use. e.g. url, - * resourceUrl, html, js and css. - * @param {*} value The value that that should be considered trusted/safe. - * @returns {*} A value that can be used to stand in for the provided `value` in places - * where AngularJS expects a $sce.trustAs() return value. + * See {@link ng.$sceDelegate#getTrusted getTrusted} for the + * function that will consume those trusted values, and {@link ng.$sce $sce} + * for general documentation about strict contextual escaping. + * + * @param {string} type The kind of context in which this value is safe + * for use. e.g. url, resourceUrl, html, js and css. + * @param {*} value The value that that should be considered trusted. + * @returns {*} A trusted version of value, that can be used in sinks of + * the given context. */ function trustAs(type, trustedValue) { var Constructor = (byType.hasOwnProperty(type) ? byType[type] : null); @@ -330,7 +370,8 @@ function $SceDelegateProvider() { * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. * * If the passed parameter is not a value that had been returned by {@link - * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}, returns it as-is. + * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}, it must be returned + * as-is. * * @param {*} value The result of a prior {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} * call or anything else. @@ -351,33 +392,41 @@ function $SceDelegateProvider() { * @name $sceDelegate#getTrusted * * @description - * Takes the result of a {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call and - * returns the originally supplied value if the queried context type is a supertype of the - * created type. If this condition isn't satisfied, throws an exception. + * Takes any input, and either returns a value that's safe to use in the + * specified context, or throws an exception. * - *
- * Disabling auto-escaping is extremely dangerous, it usually creates a Cross Site Scripting - * (XSS) vulnerability in your application. - *
+ * In practice, there's several cases. When given a string, then this should + * run checks and sanitization to make it safe without prior assumptions. + * When given the result of a {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, + * this returns the originally supplied value if that value's context is + * valid for this call's context. Finally, this function can also throw when + * there is no way to turn maybeTrusted in a safe value (e.g., no sanitization + * is available or possible.) * * @param {string} type The kind of context in which this value is to be used. * @param {*} maybeTrusted The result of a prior {@link ng.$sceDelegate#trustAs - * `$sceDelegate.trustAs`} call. - * @returns {*} The value the was originally provided to {@link ng.$sceDelegate#trustAs - * `$sceDelegate.trustAs`} if valid in this context. Otherwise, throws an exception. + * `$sceDelegate.trustAs`} call, or anything else (which will not be considered + * trusted.) + * @returns {*} A version of value that's safe to use in the given context, + * or throws an exception if this is impossible. */ function getTrusted(type, maybeTrusted) { if (maybeTrusted === null || isUndefined(maybeTrusted) || maybeTrusted === '') { return maybeTrusted; } var constructor = (byType.hasOwnProperty(type) ? byType[type] : null); + // If maybeTrusted is a trusted class instance or subclass instance, + // then unwrap and return as-is. if (constructor && maybeTrusted instanceof constructor) { return maybeTrusted.$$unwrapTrustedValue(); } - // If we get here, then we may only take one of two actions. - // 1. sanitize the value for the requested type, or - // 2. throw an exception. + // Otherwise, if we get here, then we may either make it safe, or throw an + // exception. This depends on the context: some are sanitizatible (HTML), + // some use whitelists (RESOURCE_URL), some are impossible to do (JS). + // This step isn't implemented for CSS and URL, as AngularJS has no + // corresponding sinks. if (type === SCE_CONTEXTS.RESOURCE_URL) { + // RESOURCE_URL uses a whitelist. if (isResourceUrlAllowedByPolicy(maybeTrusted)) { return maybeTrusted; } else { @@ -386,8 +435,10 @@ function $SceDelegateProvider() { maybeTrusted.toString()); } } else if (type === SCE_CONTEXTS.HTML) { + // htmlSanitizer throws its own error when no sanitizer is available. return htmlSanitizer(maybeTrusted); } + // Default error when the $sce service has no way to make the input safe. throw $sceMinErr('unsafe', 'Attempting to use an unsafe value in a safe context.'); } @@ -423,21 +474,27 @@ function $SceDelegateProvider() { * * # Strict Contextual Escaping * - * Strict Contextual Escaping (SCE) is a mode in which AngularJS requires bindings in certain - * contexts to result in a value that is marked as safe to use for that context. One example of - * such a context is binding arbitrary html controlled by the user via `ng-bind-html`. We refer - * to these contexts as privileged or SCE contexts. + * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only + * render trusted values. Its goal is to assist in writing code in a way that (a) is secure by + * default, and (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a + * lot easier. * - * As of version 1.2, AngularJS ships with SCE enabled by default. + * ## Overview + * + * To systematically block XSS bugs, AngularJS treats all values as untrusted by default in + * HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically + * run security checks on them (sanitizations, whitelists, depending on context), or throw when it + * cannot guarantee the security of the result. That behavior depends strongly on contexts: HTML + * can be sanitized, but template URLs cannot, for instance. * - * Note: When enabled (the default), IE<11 in quirks mode is not supported. In this mode, IE<11 allow - * one to execute arbitrary javascript by the use of the expression() syntax. Refer - * to learn more about them. - * You can ensure your document is in standards mode and not quirks mode by adding `` - * to the top of your HTML document. + * To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML: + * we call that the *context*. When given an untrusted input, AngularJS will attempt to sanitize it + * before rendering if a sanitizer is available, and throw otherwise. To render the input as-is, you + * will need to mark it as trusted for that context before attempting to bind it. * - * SCE assists in writing code in a way that (a) is secure by default and (b) makes auditing for - * security vulnerabilities such as XSS, clickjacking, etc. a lot easier. + * As of version 1.2, AngularJS ships with SCE enabled by default. + * + * ## In practice * * Here's an example of a binding in a privileged context: * @@ -447,10 +504,10 @@ function $SceDelegateProvider() { * ``` * * Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE - * disabled, this application allows the user to render arbitrary HTML into the DIV. - * In a more realistic example, one may be rendering user comments, blog articles, etc. via - * bindings. (HTML is just one example of a context where rendering user controlled input creates - * security vulnerabilities.) + * disabled, this application allows the user to render arbitrary HTML into the DIV, which would + * be an XSS bug. In a more realistic example, one may be rendering user comments, blog articles, + * etc. via bindings. (HTML is just one example of a context where rendering user controlled input + * creates security vulnerabilities.) * * For the case of HTML, you might use a library, either on the client side, or on the server side, * to sanitize unsafe HTML before binding to the value and rendering it in the document. @@ -460,25 +517,28 @@ function $SceDelegateProvider() { * ensure that you didn't accidentally delete the line that sanitized the value, or renamed some * properties/fields and forgot to update the binding to the sanitized value? * - * To be secure by default, you want to ensure that any such bindings are disallowed unless you can - * determine that something explicitly says it's safe to use a value for binding in that - * context. You can then audit your code (a simple grep would do) to ensure that this is only done - * for those values that you can easily tell are safe - because they were received from your server, - * sanitized by your library, etc. You can organize your codebase to help with this - perhaps - * allowing only the files in a specific directory to do this. Ensuring that the internal API - * exposed by that code doesn't markup arbitrary values as safe then becomes a more manageable task. + * To be secure by default, AngularJS makes sure bindings go through that sanitization, or + * any similar validation process, unless there's a good reason to trust the given value in this + * context. That trust is formalized with a function call. This means that as a developer, you + * can assume all untrusted bindings are safe. Then, to audit your code for binding security issues, + * you just need to ensure the values you mark as trusted indeed are safe - because they were + * received from your server, sanitized by your library, etc.. You can organize your codebase to + * help with this - perhaps allowing only the files in a specific directory to do this. + * Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then + * becomes a more manageable task. * * In the case of AngularJS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs} * (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to - * obtain values that will be accepted by SCE / privileged contexts. - * + * build the trusted versions of your values. * * ## How does it work? * * In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted - * $sce.getTrusted(context, value)} rather than to the value directly. Directives use {@link + * $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as + * a way to enforce the required security context in your data sink. Directives use {@link * ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs the - * {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. + * {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also, when + * binding without directives, AngularJS will understand the context of your bindings automatically. * * As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link * ng.$sce#parseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly @@ -519,11 +579,12 @@ function $SceDelegateProvider() { * It's important to remember that SCE only applies to interpolation expressions. * * If your expressions are constant literals, they're automatically trusted and you don't need to - * call `$sce.trustAs` on them (remember to include the `ngSanitize` module) (e.g. - * `
`) just works. - * - * Additionally, `a[href]` and `img[src]` automatically sanitize their URLs and do not pass them - * through {@link ng.$sce#getTrusted $sce.getTrusted}. SCE doesn't play a role here. + * call `$sce.trustAs` on them (e.g. + * `
`) just works. The $sceDelegate will also + * use the `$sanitize` injectable if it is available when binding untrusted values to HTML context. + * AngularJS provides an implementation in `angular-sanitize.js`, and if you + * wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in + * your application. * * The included {@link ng.$sceDelegate $sceDelegate} comes with sane defaults to allow you to load * templates in `ng-include` from your application's domain without having to even know about SCE. @@ -541,11 +602,17 @@ function $SceDelegateProvider() { * * | Context | Notes | * |---------------------|----------------| - * | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered and the {@link ngSanitize $sanitize} module is present this will sanitize the value instead of throwing an error. | - * | `$sce.CSS` | For CSS that's safe to source into the application. Currently unused. Feel free to use it in your own directives. | - * | `$sce.URL` | For URLs that are safe to follow as links. Currently unused (`
Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` does and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` are required. | - * | `$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. | + * | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered, and the {@link ngSanitize.$sanitize $sanitize} service is available (implemented by the {@link ngSanitize ngSanitize} module) this will sanitize the value instead of throwing an error. | + * | `$sce.CSS` | For CSS that's safe to source into the application. Currently, no bindings require this context. Feel free to use it in your own directives. | + * | `$sce.URL` | For URLs that are safe to follow as links. Currently unused (`
Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` does (it's not just the URL that matters, but also what is at the end of it), and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` are required. | + * | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently, no bindings require this context. Feel free to use it in your own directives. | + * + * + * Be aware that `a[href]` and `img[src]` automatically sanitize their URLs and do not pass them + * through {@link ng.$sce#getTrusted $sce.getTrusted}. There's no CSS-, URL-, or JS-context bindings + * in AngularJS currently, so their corresponding `$sce.trustAs` functions aren't useful yet. This + * might evolve. * * ## Format of items in {@link ng.$sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist}/{@link ng.$sceDelegateProvider#resourceUrlBlacklist Blacklist} * @@ -664,14 +731,15 @@ function $SceDelegateProvider() { * for little coding overhead. It will be much harder to take an SCE disabled application and * either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE * for cases where you have a lot of existing code that was written before SCE was introduced and - * you're migrating them a module at a time. + * you're migrating them a module at a time. Also do note that this is an app-wide setting, so if + * you are writing a library, you will cause security bugs applications using it. * * That said, here's how you can completely disable SCE: * * ``` * angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) { * // Completely disable SCE. For demonstration purposes only! - * // Do not use in new projects. + * // Do not use in new projects or libraries. * $sceProvider.enabled(false); * }); * ``` @@ -818,18 +886,18 @@ function $SceProvider() { * @name $sce#trustAs * * @description - * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, - * returns an object that is trusted by AngularJS for use in specified strict contextual - * escaping contexts (such as ng-bind-html, ng-include, any src attribute - * interpolation, any dom event binding attribute interpolation such as for onclick, etc.) - * that uses the provided value. See * {@link ng.$sce $sce} for enabling strict contextual - * escaping. + * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, + * returns a wrapped object that represents your value, and the trust you have + * in its safety for the given context. AngularJS can then use that value as-is + * in bindings of the specified secure context. This is used in bindings + * for ng-bind-html, ng-include, and most src attribute interpolation. + * See {@link ng.$sce $sce} for strict contextual escaping. * * @param {string} type The kind of context in which this value is safe for use. e.g. url, * resourceUrl, html, js and css. - * @param {*} value The value that that should be considered trusted/safe. - * @returns {*} A value that can be used to stand in for the provided `value` in places - * where AngularJS expects a $sce.trustAs() return value. + * @param {*} value The value that that should be considered trusted. + * @returns {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in the context you specified. */ /** @@ -840,11 +908,9 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsHtml(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.HTML, value)`} * - * @param {*} value The value to trustAs. - * @returns {*} An object that can be passed to {@link ng.$sce#getTrustedHtml - * $sce.getTrustedHtml(value)} to obtain the original value. (privileged directives - * only accept expressions that are either literal constants or are the - * return value of {@link ng.$sce#trustAs $sce.trustAs}.) + * @param {*} value The value to mark as trusted for HTML context. + * @returns {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in HTML context (like ng-bind-html). */ /** @@ -855,11 +921,9 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsUrl(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.URL, value)`} * - * @param {*} value The value to trustAs. - * @returns {*} An object that can be passed to {@link ng.$sce#getTrustedUrl - * $sce.getTrustedUrl(value)} to obtain the original value. (privileged directives - * only accept expressions that are either literal constants or are the - * return value of {@link ng.$sce#trustAs $sce.trustAs}.) + * @param {*} value The value to mark as trusted for URL context. + * @returns {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in URL context (currently unused.) */ /** @@ -870,11 +934,10 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsResourceUrl(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.RESOURCE_URL, value)`} * - * @param {*} value The value to trustAs. - * @returns {*} An object that can be passed to {@link ng.$sce#getTrustedResourceUrl - * $sce.getTrustedResourceUrl(value)} to obtain the original value. (privileged directives - * only accept expressions that are either literal constants or are the return - * value of {@link ng.$sce#trustAs $sce.trustAs}.) + * @param {*} value The value to mark as trusted for RESOURCE_URL context. + * @returns {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in RESOURCE_URL context (template URLs in `ng-include`, most `src` + * attributes bindings, ...) */ /** @@ -885,11 +948,9 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsJs(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.JS, value)`} * - * @param {*} value The value to trustAs. - * @returns {*} An object that can be passed to {@link ng.$sce#getTrustedJs - * $sce.getTrustedJs(value)} to obtain the original value. (privileged directives - * only accept expressions that are either literal constants or are the - * return value of {@link ng.$sce#trustAs $sce.trustAs}.) + * @param {*} value The value to mark as trusted for JS context. + * @returns {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in JS context (currently unused.) */ /** @@ -898,9 +959,11 @@ function $SceProvider() { * * @description * Delegates to {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted`}. As such, - * takes the result of a {@link ng.$sce#trustAs `$sce.trustAs`}() call and returns the - * originally supplied value if the queried context type is a supertype of the created type. - * If this condition isn't satisfied, throws an exception. + * takes any input, and either returns a value that's safe to use in the specified context, + * or throws an exception. This function is aware of trusted values created by the `trustAs` + * function and its shorthands, and when contexts are appropriate, returns the unwrapped value + * as-is. Finally, this function can also throw when there is no way to turn maybeTrusted in a + * safe value (e.g., no sanitization is available or possible.) * * @param {string} type The kind of context in which this value is to be used. * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs `$sce.trustAs`} From 5e6a0406192f23b43733a62217eba4845d8649ff Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Wed, 22 Feb 2017 14:48:13 +0100 Subject: [PATCH 2/6] doc($sce): adress comments, plus more formatting fixes --- src/ng/sce.js | 314 ++++++++++++++++++++++++++------------------------ 1 file changed, 161 insertions(+), 153 deletions(-) diff --git a/src/ng/sce.js b/src/ng/sce.js index 8413f444d016..17f8db08b9e9 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -16,19 +16,18 @@ var $sceMinErr = minErr('$sce'); var SCE_CONTEXTS = { - // HTML is used when there's HTML rendered (e.g. ng-bind-html, iframe srcdoc - // binding). + // HTML is used when there's HTML rendered (e.g. ng-bind-html, iframe srcdoc binding). HTML: 'html', // Style statements or stylesheets. Currently unused in AngularJS. CSS: 'css', - // An URL used in a context where it does not refer to a resource that loads - // code. Currently unused in AngularJS. + // An URL used in a context where it does not refer to a resource that loads code. Currently + // unused in AngularJS. URL: 'url', - // RESOURCE_URL is a subtype of URL used where the referred-to resource could - // be interpreted as code. (e.g. ng-include, script src binding, templateUrl) + // RESOURCE_URL is a subtype of URL used where the referred-to resource could be interpreted as + // code. (e.g. ng-include, script src binding, templateUrl) RESOURCE_URL: 'resourceUrl', // Script. Currently unused in AngularJS. @@ -132,7 +131,7 @@ function adjustMatchers(matchers) { * * The `$sceDelegateProvider` allows one to get/set the whitelists and blacklists used to ensure * that the URLs used for sourcing AngularJS templates and other script-running URLs are safe (all - * RESOURCE_URL sinks). See + * places that use the `$sce.RESOURCE_URL` context). See * {@link ng.$sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider.resourceUrlWhitelist} * and * {@link ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist}, @@ -164,15 +163,13 @@ function adjustMatchers(matchers) { * ]); * }); * ``` - * Note that an empty whitelist will block every RESOURCE_URL from - * being loaded, and will require you to manually mark each one as trusted with - * $sce.trustAsResourceUrl. However, templates requested by - * {@link ng.$templateRequest $templateRequest} that are present in - * {@link ng.$templateCache $templateCache} will not go through this check. If - * you have a mechanism to populate your templates in that cache at config time, - * then it is a good idea to remove 'self' from that whitelist. This helps to - * mitigate the security impact of certain types of issues, like for instance - * attacker-controlled ng-includes. + * Note that an empty whitelist will block every resource URL from being loaded, and will require + * you to manually mark each one as trusted with `$sce.trustAsResourceUrl`. However, templates + * requested by {@link ng.$templateRequest $templateRequest} that are present in + * {@link ng.$templateCache $templateCache} will not go through this check. If you have a mechanism + * to populate your templates in that cache at config time, then it is a good idea to remove 'self' + * from that whitelist. This helps to mitigate the security impact of certain types of issues, like + * for instance attacker-controlled `ng-includes`. */ function $SceDelegateProvider() { @@ -188,21 +185,21 @@ function $SceDelegateProvider() { * @kind function * * @param {Array=} whitelist When provided, replaces the resourceUrlWhitelist with the value - * provided. This must be an array or null. A snapshot of this array is used so further - * changes to the array are ignored. + * provided. This must be an array or null. A snapshot of this array is used so further + * changes to the array are ignored. * - * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items - * allowed in this array. + * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items + * allowed in this array. * * @return {Array} the currently set whitelist array. * * The **default value** when no whitelist has been explicitly set is `['self']` allowing only * same origin resource requests. * - *
- * **Note:** the default whitelist of 'self' is not recommanded if your app shares its origin - * with other apps! It is a good idea to limit it to only your application's directory. - *
+ *
+ * **Note:** the default whitelist of 'self' is not recommanded if your app shares its origin + * with other apps! It is a good idea to limit it to only your application's directory. + *
* * @description * Sets/Gets the whitelist of trusted resource URLs. @@ -220,17 +217,17 @@ function $SceDelegateProvider() { * @kind function * * @param {Array=} blacklist When provided, replaces the resourceUrlBlacklist with the value - * provided. This must be an array or null. A snapshot of this array is used so further - * changes to the array are ignored. + * provided. This must be an array or null. A snapshot of this array is used so further + * changes to the array are ignored. * - * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items - * allowed in this array. + * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items + * allowed in this array. * - * The typical usage for the blacklist is to **block - * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as - * these would otherwise be trusted but actually return content from the redirected domain. + * The typical usage for the blacklist is to **block + * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as + * these would otherwise be trusted but actually return content from the redirected domain. * - * Finally, **the blacklist overrides the whitelist** and has the final say. + * Finally, **the blacklist overrides the whitelist** and has the final say. * * @return {Array} the currently set blacklist array. * @@ -322,23 +319,24 @@ function $SceDelegateProvider() { * @name $sceDelegate#trustAs * * @description - * Marks the parameter as trusted for the specified context, and returns the - * trusted representation of it. This trusted object should later on be - * used as-is, without any security check, by sinks that use this context. - * For instance, marking a string as trusted for the $sce.HTML context will - * entirely bypass the potential $sanitize call in corresponding $sce.HTML - * sinks, such as an ng-bind-html directive, while using the same value - * passed as a string will cause it to be sanitized. + * Returns a trusted representation of the parameter for the specified context. This trusted + * object will later on be used as-is, without any security check, by bindings or directives + * that require this security context. + * For instance, marking a string as trusted for the `$sce.HTML` context will entirely bypass + * the potential `$sanitize` call in corresponding `$sce.HTML` bindings or directives, such as + * `ng-bind-html`. Note that in most cases you won't need to call this function: if you have the + * sanitizer loaded, passing the value itself will render all the HTML that does not pose a + * security risk. * - * See {@link ng.$sceDelegate#getTrusted getTrusted} for the - * function that will consume those trusted values, and {@link ng.$sce $sce} - * for general documentation about strict contextual escaping. + * See {@link ng.$sceDelegate#getTrusted getTrusted} for the function that will consume those + * trusted values, and {@link ng.$sce $sce} for general documentation about strict contextual + * escaping. + * + * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`, + * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`. * - * @param {string} type The kind of context in which this value is safe - * for use. e.g. url, resourceUrl, html, js and css. * @param {*} value The value that that should be considered trusted. - * @returns {*} A trusted version of value, that can be used in sinks of - * the given context. + * @return {*} A trusted representation of value, that can be used in the given context. */ function trustAs(type, trustedValue) { var Constructor = (byType.hasOwnProperty(type) ? byType[type] : null); @@ -370,12 +368,11 @@ function $SceDelegateProvider() { * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. * * If the passed parameter is not a value that had been returned by {@link - * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}, it must be returned - * as-is. + * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}, it must be returned as-is. * * @param {*} value The result of a prior {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} - * call or anything else. - * @returns {*} The `value` that was originally provided to {@link ng.$sceDelegate#trustAs + * call or anything else. + * @return {*} The `value` that was originally provided to {@link ng.$sceDelegate#trustAs * `$sceDelegate.trustAs`} if `value` is the result of such a call. Otherwise, returns * `value` unchanged. */ @@ -392,39 +389,36 @@ function $SceDelegateProvider() { * @name $sceDelegate#getTrusted * * @description - * Takes any input, and either returns a value that's safe to use in the - * specified context, or throws an exception. + * Takes any input, and either returns a value that's safe to use in the specified context, or + * throws an exception. * - * In practice, there's several cases. When given a string, then this should - * run checks and sanitization to make it safe without prior assumptions. - * When given the result of a {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, - * this returns the originally supplied value if that value's context is - * valid for this call's context. Finally, this function can also throw when - * there is no way to turn maybeTrusted in a safe value (e.g., no sanitization + * In practice, there's several cases. When given a string, this run checks and sanitization to + * make it safe without prior assumptions. When given the result of a {@link + * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, this returns the originally supplied + * value if that value's context is valid for this call's context. Finally, this function can + * also throw when there is no way to turn `maybeTrusted` in a safe value (e.g., no sanitization * is available or possible.) * - * @param {string} type The kind of context in which this value is to be used. + * @param {string} type The context in which this value is to be used (such as `$sce.HTML`). * @param {*} maybeTrusted The result of a prior {@link ng.$sceDelegate#trustAs - * `$sceDelegate.trustAs`} call, or anything else (which will not be considered - * trusted.) - * @returns {*} A version of value that's safe to use in the given context, - * or throws an exception if this is impossible. + * `$sceDelegate.trustAs`} call, or anything else (which will not be considered trusted.) + * @return {*} A version of value that's safe to use in the given context, or throws an + * exception if this is impossible. */ function getTrusted(type, maybeTrusted) { if (maybeTrusted === null || isUndefined(maybeTrusted) || maybeTrusted === '') { return maybeTrusted; } var constructor = (byType.hasOwnProperty(type) ? byType[type] : null); - // If maybeTrusted is a trusted class instance or subclass instance, - // then unwrap and return as-is. + // If maybeTrusted is a trusted class instance or subclass instance, then unwrap and return + // as-is. if (constructor && maybeTrusted instanceof constructor) { return maybeTrusted.$$unwrapTrustedValue(); } - // Otherwise, if we get here, then we may either make it safe, or throw an - // exception. This depends on the context: some are sanitizatible (HTML), - // some use whitelists (RESOURCE_URL), some are impossible to do (JS). - // This step isn't implemented for CSS and URL, as AngularJS has no - // corresponding sinks. + // Otherwise, if we get here, then we may either make it safe, or throw an exception. This + // depends on the context: some are sanitizatible (HTML), some use whitelists (RESOURCE_URL), + // some are impossible to do (JS). This step isn't implemented for CSS and URL, as AngularJS + // has no corresponding sinks. if (type === SCE_CONTEXTS.RESOURCE_URL) { // RESOURCE_URL uses a whitelist. if (isResourceUrlAllowedByPolicy(maybeTrusted)) { @@ -474,14 +468,13 @@ function $SceDelegateProvider() { * * # Strict Contextual Escaping * - * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only - * render trusted values. Its goal is to assist in writing code in a way that (a) is secure by - * default, and (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a - * lot easier. + * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render + * trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and + * (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier. * * ## Overview * - * To systematically block XSS bugs, AngularJS treats all values as untrusted by default in + * To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in * HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically * run security checks on them (sanitizations, whitelists, depending on context), or throw when it * cannot guarantee the security of the result. That behavior depends strongly on contexts: HTML @@ -505,9 +498,9 @@ function $SceDelegateProvider() { * * Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE * disabled, this application allows the user to render arbitrary HTML into the DIV, which would - * be an XSS bug. In a more realistic example, one may be rendering user comments, blog articles, - * etc. via bindings. (HTML is just one example of a context where rendering user controlled input - * creates security vulnerabilities.) + * be an XSS security bug. In a more realistic example, one may be rendering user comments, blog + * articles, etc. via bindings. (HTML is just one example of a context where rendering user + * controlled input creates security vulnerabilities.) * * For the case of HTML, you might use a library, either on the client side, or on the server side, * to sanitize unsafe HTML before binding to the value and rendering it in the document. @@ -536,9 +529,10 @@ function $SceDelegateProvider() { * In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted * $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as * a way to enforce the required security context in your data sink. Directives use {@link - * ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs the - * {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also, when - * binding without directives, AngularJS will understand the context of your bindings automatically. + * ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs + * the {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also, + * when binding without directives, AngularJS will understand the context of your bindings + * automatically. * * As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link * ng.$sce#parseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly @@ -580,9 +574,9 @@ function $SceDelegateProvider() { * * If your expressions are constant literals, they're automatically trusted and you don't need to * call `$sce.trustAs` on them (e.g. - * `
`) just works. The $sceDelegate will also - * use the `$sanitize` injectable if it is available when binding untrusted values to HTML context. - * AngularJS provides an implementation in `angular-sanitize.js`, and if you + * `
`) just works. The `$sceDelegate` will + * also use the `$sanitize` injectable if it is available when binding untrusted values to + * `$sce.HTML` context. AngularJS provides an implementation in `angular-sanitize.js`, and if you * wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in * your application. * @@ -754,7 +748,7 @@ function $SceProvider() { * @name $sceProvider#enabled * @kind function * - * @param {boolean=} value If provided, then enables/disables SCE. + * @param {boolean=} value If provided, then enables/disables SCE application-wide. * @return {boolean} true if SCE is enabled, false otherwise. * * @description @@ -809,9 +803,9 @@ function $SceProvider() { * getTrusted($sce.RESOURCE_URL, value) succeeding implies that getTrusted($sce.URL, value) * will also succeed. * - * Inheritance happens to capture this in a natural way. In some future, we - * may not use inheritance anymore. That is OK because no code outside of - * sce.js and sceSpecs.js would need to be aware of this detail. + * Inheritance happens to capture this in a natural way. In some future, we may not use + * inheritance anymore. That is OK because no code outside of sce.js and sceSpecs.js would need to + * be aware of this detail. */ this.$get = ['$parse', '$sceDelegate', function( @@ -834,7 +828,7 @@ function $SceProvider() { * @kind function * * @return {Boolean} true if SCE is enabled, false otherwise. If you want to set the value, you - * have to do it at module config time on {@link ng.$sceProvider $sceProvider}. + * have to do it at module config time on {@link ng.$sceProvider $sceProvider}. * * @description * Returns a boolean indicating if SCE is enabled. @@ -861,14 +855,14 @@ function $SceProvider() { * wraps the expression in a call to {@link ng.$sce#getTrusted $sce.getTrusted(*type*, * *result*)} * - * @param {string} type The kind of SCE context in which this result will be used. + * @param {string} type The SCE context in which this result will be used. * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ sce.parseAs = function sceParseAs(type, expr) { var parsed = $parse(expr); @@ -886,18 +880,18 @@ function $SceProvider() { * @name $sce#trustAs * * @description - * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, - * returns a wrapped object that represents your value, and the trust you have - * in its safety for the given context. AngularJS can then use that value as-is - * in bindings of the specified secure context. This is used in bindings - * for ng-bind-html, ng-include, and most src attribute interpolation. - * See {@link ng.$sce $sce} for strict contextual escaping. + * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, returns a + * wrapped object that represents your value, and the trust you have in its safety for the given + * context. AngularJS can then use that value as-is in bindings of the specified secure context. + * This is used in bindings for `ng-bind-html`, `ng-include`, and most `src` attribute + * interpolations. See {@link ng.$sce $sce} for strict contextual escaping. + * + * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`, + * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`. * - * @param {string} type The kind of context in which this value is safe for use. e.g. url, - * resourceUrl, html, js and css. * @param {*} value The value that that should be considered trusted. - * @returns {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in the context you specified. + * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` + * in the context you specified. */ /** @@ -908,9 +902,23 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsHtml(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.HTML, value)`} * - * @param {*} value The value to mark as trusted for HTML context. - * @returns {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in HTML context (like ng-bind-html). + * @param {*} value The value to mark as trusted for `$sce.HTML` context. + * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` + * in `$sce.HTML` context (like `ng-bind-html`). + */ + + /** + * @ngdoc method + * @name $sce#trustAsCss + * + * @description + * Shorthand method. `$sce.trustAsCss(value)` → + * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.CSS, value)`} + * + * @param {*} value The value to mark as trusted for `$sce.CSS` context. + * @return {*} A wrapped version of value that can be used as a trusted variant + * of your `value` in CSS context. This context is currently unused, so there are almost no + * reasons to use this function so far. */ /** @@ -921,9 +929,10 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsUrl(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.URL, value)`} * - * @param {*} value The value to mark as trusted for URL context. - * @returns {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in URL context (currently unused.) + * @param {*} value The value to mark as trusted for `$sce.URL` context. + * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` + * in `$sce.URL` context. That context is currently unused, so there are almost no reasons + * to use this function so far. */ /** @@ -934,10 +943,10 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsResourceUrl(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.RESOURCE_URL, value)`} * - * @param {*} value The value to mark as trusted for RESOURCE_URL context. - * @returns {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in RESOURCE_URL context (template URLs in `ng-include`, most `src` - * attributes bindings, ...) + * @param {*} value The value to mark as trusted for `$sce.RESOURCE_URL` context. + * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` + * in `$sce.RESOURCE_URL` context (template URLs in `ng-include`, most `src` attribute + * bindings, ...) */ /** @@ -949,8 +958,9 @@ function $SceProvider() { * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.JS, value)`} * * @param {*} value The value to mark as trusted for JS context. - * @returns {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in JS context (currently unused.) + * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` + * in `$sce.JS` context. That context is currently unused, so there are almost no reasons to + * use this function so far. */ /** @@ -965,12 +975,10 @@ function $SceProvider() { * as-is. Finally, this function can also throw when there is no way to turn maybeTrusted in a * safe value (e.g., no sanitization is available or possible.) * - * @param {string} type The kind of context in which this value is to be used. - * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs `$sce.trustAs`} - * call. - * @returns {*} The value the was originally provided to - * {@link ng.$sce#trustAs `$sce.trustAs`} if valid in this context. - * Otherwise, throws an exception. + * @param {string} type The context in which this value is to be used. + * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs `$sce.trustAs`} call. + * @return {*} The value the was originally provided to {@link ng.$sce#trustAs `$sce.trustAs`} + * if valid in this context. Otherwise, throws an exception. */ /** @@ -982,7 +990,7 @@ function $SceProvider() { * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.HTML, value)`} * * @param {*} value The value to pass to `$sce.getTrusted`. - * @returns {*} The return value of `$sce.getTrusted($sce.HTML, value)` + * @return {*} The return value of `$sce.getTrusted($sce.HTML, value)` */ /** @@ -994,7 +1002,7 @@ function $SceProvider() { * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.CSS, value)`} * * @param {*} value The value to pass to `$sce.getTrusted`. - * @returns {*} The return value of `$sce.getTrusted($sce.CSS, value)` + * @return {*} The return value of `$sce.getTrusted($sce.CSS, value)` */ /** @@ -1006,7 +1014,7 @@ function $SceProvider() { * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.URL, value)`} * * @param {*} value The value to pass to `$sce.getTrusted`. - * @returns {*} The return value of `$sce.getTrusted($sce.URL, value)` + * @return {*} The return value of `$sce.getTrusted($sce.URL, value)` */ /** @@ -1018,7 +1026,7 @@ function $SceProvider() { * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.RESOURCE_URL, value)`} * * @param {*} value The value to pass to `$sceDelegate.getTrusted`. - * @returns {*} The return value of `$sce.getTrusted($sce.RESOURCE_URL, value)` + * @return {*} The return value of `$sce.getTrusted($sce.RESOURCE_URL, value)` */ /** @@ -1030,7 +1038,7 @@ function $SceProvider() { * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.JS, value)`} * * @param {*} value The value to pass to `$sce.getTrusted`. - * @returns {*} The return value of `$sce.getTrusted($sce.JS, value)` + * @return {*} The return value of `$sce.getTrusted($sce.JS, value)` */ /** @@ -1042,12 +1050,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.HTML, value)`} * * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1059,12 +1067,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.CSS, value)`} * * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1076,12 +1084,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.URL, value)`} * * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1093,12 +1101,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.RESOURCE_URL, value)`} * * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1110,12 +1118,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.JS, value)`} * * @param {string} expression String expression to compile. - * @returns {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} a function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the strings - * are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values in - * `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ // Shorthand delegations. From ecefd07ecda4ec065541811c437f19ed94e07afa Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Fri, 3 Mar 2017 15:51:15 +0100 Subject: [PATCH 3/6] doc($sce): Adress gkalpak's comments. --- src/ng/sce.js | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/ng/sce.js b/src/ng/sce.js index 17f8db08b9e9..3befdf50fde7 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -193,11 +193,11 @@ function $SceDelegateProvider() { * * @return {Array} the currently set whitelist array. * - * The **default value** when no whitelist has been explicitly set is `['self']` allowing only - * same origin resource requests. + * The **default value** when no whitelist has been explicitly set is `['self']` allowing only + * same origin resource requests. * *
- * **Note:** the default whitelist of 'self' is not recommanded if your app shares its origin + * **Note:** the default whitelist of 'self' is not recommended if your app shares its origin * with other apps! It is a good idea to limit it to only your application's directory. *
* @@ -335,7 +335,7 @@ function $SceDelegateProvider() { * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`, * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`. * - * @param {*} value The value that that should be considered trusted. + * @param {*} value The value that should be considered trusted. * @return {*} A trusted representation of value, that can be used in the given context. */ function trustAs(type, trustedValue) { @@ -392,9 +392,9 @@ function $SceDelegateProvider() { * Takes any input, and either returns a value that's safe to use in the specified context, or * throws an exception. * - * In practice, there's several cases. When given a string, this run checks and sanitization to - * make it safe without prior assumptions. When given the result of a {@link - * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, this returns the originally supplied + * In practice, there are several cases. When given a string, this function runs checks + * and sanitization to make it safe without prior assumptions. When given the result of a {@link + * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, it returns the originally supplied * value if that value's context is valid for this call's context. Finally, this function can * also throw when there is no way to turn `maybeTrusted` in a safe value (e.g., no sanitization * is available or possible.) @@ -402,7 +402,7 @@ function $SceDelegateProvider() { * @param {string} type The context in which this value is to be used (such as `$sce.HTML`). * @param {*} maybeTrusted The result of a prior {@link ng.$sceDelegate#trustAs * `$sceDelegate.trustAs`} call, or anything else (which will not be considered trusted.) - * @return {*} A version of value that's safe to use in the given context, or throws an + * @return {*} A version of the value that's safe to use in the given context, or throws an * exception if this is impossible. */ function getTrusted(type, maybeTrusted) { @@ -482,8 +482,9 @@ function $SceDelegateProvider() { * * To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML: * we call that the *context*. When given an untrusted input, AngularJS will attempt to sanitize it - * before rendering if a sanitizer is available, and throw otherwise. To render the input as-is, you - * will need to mark it as trusted for that context before attempting to bind it. + * before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and + * render the input as-is, you will need to mark it as trusted for that context before attempting + * to bind it. * * As of version 1.2, AngularJS ships with SCE enabled by default. * @@ -515,7 +516,7 @@ function $SceDelegateProvider() { * context. That trust is formalized with a function call. This means that as a developer, you * can assume all untrusted bindings are safe. Then, to audit your code for binding security issues, * you just need to ensure the values you mark as trusted indeed are safe - because they were - * received from your server, sanitized by your library, etc.. You can organize your codebase to + * received from your server, sanitized by your library, etc. You can organize your codebase to * help with this - perhaps allowing only the files in a specific directory to do this. * Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then * becomes a more manageable task. @@ -575,7 +576,7 @@ function $SceDelegateProvider() { * If your expressions are constant literals, they're automatically trusted and you don't need to * call `$sce.trustAs` on them (e.g. * `
`) just works. The `$sceDelegate` will - * also use the `$sanitize` injectable if it is available when binding untrusted values to + * also use the `$sanitize` service if it is available when binding untrusted values to * `$sce.HTML` context. AngularJS provides an implementation in `angular-sanitize.js`, and if you * wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in * your application. @@ -917,8 +918,8 @@ function $SceProvider() { * * @param {*} value The value to mark as trusted for `$sce.CSS` context. * @return {*} A wrapped version of value that can be used as a trusted variant - * of your `value` in CSS context. This context is currently unused, so there are almost no - * reasons to use this function so far. + * of your `value` in `$sce.CSS` context. This context is currently unused, so there are + * almost no reasons to use this function so far. */ /** @@ -972,12 +973,12 @@ function $SceProvider() { * takes any input, and either returns a value that's safe to use in the specified context, * or throws an exception. This function is aware of trusted values created by the `trustAs` * function and its shorthands, and when contexts are appropriate, returns the unwrapped value - * as-is. Finally, this function can also throw when there is no way to turn maybeTrusted in a + * as-is. Finally, this function can also throw when there is no way to turn `maybeTrusted` in a * safe value (e.g., no sanitization is available or possible.) * * @param {string} type The context in which this value is to be used. * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs `$sce.trustAs`} call. - * @return {*} The value the was originally provided to {@link ng.$sce#trustAs `$sce.trustAs`} + * @return {*} The value that was originally provided to {@link ng.$sce#trustAs `$sce.trustAs`} * if valid in this context. Otherwise, throws an exception. */ From 2d437bd9d69813e9674ec6da94f010e5b0c2123d Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Tue, 21 Mar 2017 14:50:41 +0100 Subject: [PATCH 4/6] doc($sce): more minor formatting/content fixes. Some capitalization was wrong, formatting fixes for +4 indentation on @param tags, and uniformize some params descriptions on the same functions (scedelegate / sce). --- src/ng/sce.js | 109 ++++++++++++++++++++++++-------------------------- 1 file changed, 53 insertions(+), 56 deletions(-) diff --git a/src/ng/sce.js b/src/ng/sce.js index 3befdf50fde7..c4b78e0e8334 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -127,7 +127,7 @@ function adjustMatchers(matchers) { * @description * * The `$sceDelegateProvider` provider allows developers to configure the {@link ng.$sceDelegate - * service, used as a delegate for {@link ng.$sce Strict Contextual Escaping (SCE)}. + * $sceDelegate service}, used as a delegate for {@link ng.$sce Strict Contextual Escaping (SCE)}. * * The `$sceDelegateProvider` allows one to get/set the whitelists and blacklists used to ensure * that the URLs used for sourcing AngularJS templates and other script-running URLs are safe (all @@ -187,22 +187,21 @@ function $SceDelegateProvider() { * @param {Array=} whitelist When provided, replaces the resourceUrlWhitelist with the value * provided. This must be an array or null. A snapshot of this array is used so further * changes to the array are ignored. - * * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items * allowed in this array. * - * @return {Array} the currently set whitelist array. - * - * The **default value** when no whitelist has been explicitly set is `['self']` allowing only - * same origin resource requests. - * - *
- * **Note:** the default whitelist of 'self' is not recommended if your app shares its origin - * with other apps! It is a good idea to limit it to only your application's directory. - *
+ * @return {Array} The currently set whitelist array. * * @description * Sets/Gets the whitelist of trusted resource URLs. + * + * The **default value** when no whitelist has been explicitly set is `['self']` allowing only + * same origin resource requests. + * + *
+ * **Note:** the default whitelist of 'self' is not recommended if your app shares its origin + * with other apps! It is a good idea to limit it to only your application's directory. + *
*/ this.resourceUrlWhitelist = function(value) { if (arguments.length) { @@ -218,24 +217,21 @@ function $SceDelegateProvider() { * * @param {Array=} blacklist When provided, replaces the resourceUrlBlacklist with the value * provided. This must be an array or null. A snapshot of this array is used so further - * changes to the array are ignored. - * + * changes to the array are ignored.

* Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items - * allowed in this array. - * + * allowed in this array.

* The typical usage for the blacklist is to **block * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as * these would otherwise be trusted but actually return content from the redirected domain. - * * Finally, **the blacklist overrides the whitelist** and has the final say. * - * @return {Array} the currently set blacklist array. - * - * The **default value** when no whitelist has been explicitly set is the empty array (i.e. there - * is no blacklist.) + * @return {Array} The currently set blacklist array. * * @description * Sets/Gets the blacklist of trusted resource URLs. + * + * The **default value** when no whitelist has been explicitly set is the empty array (i.e. there + * is no blacklist.) */ this.resourceUrlBlacklist = function(value) { @@ -750,7 +746,7 @@ function $SceProvider() { * @kind function * * @param {boolean=} value If provided, then enables/disables SCE application-wide. - * @return {boolean} true if SCE is enabled, false otherwise. + * @return {boolean} True if SCE is enabled, false otherwise. * * @description * Enables/disables SCE and returns the current value. @@ -828,7 +824,7 @@ function $SceProvider() { * @name $sce#isEnabled * @kind function * - * @return {Boolean} true if SCE is enabled, false otherwise. If you want to set the value, you + * @return {Boolean} True if SCE is enabled, false otherwise. If you want to set the value, you * have to do it at module config time on {@link ng.$sceProvider $sceProvider}. * * @description @@ -858,12 +854,12 @@ function $SceProvider() { * * @param {string} type The SCE context in which this result will be used. * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ sce.parseAs = function sceParseAs(type, expr) { var parsed = $parse(expr); @@ -958,7 +954,7 @@ function $SceProvider() { * Shorthand method. `$sce.trustAsJs(value)` → * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.JS, value)`} * - * @param {*} value The value to mark as trusted for JS context. + * @param {*} value The value to mark as trusted for `$sce.JS` context. * @return {*} A wrapped version of value that can be used as a trusted variant of your `value` * in `$sce.JS` context. That context is currently unused, so there are almost no reasons to * use this function so far. @@ -977,9 +973,10 @@ function $SceProvider() { * safe value (e.g., no sanitization is available or possible.) * * @param {string} type The context in which this value is to be used. - * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs `$sce.trustAs`} call. - * @return {*} The value that was originally provided to {@link ng.$sce#trustAs `$sce.trustAs`} - * if valid in this context. Otherwise, throws an exception. + * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs + * `$sce.trustAs`} call, or anything else (which will not be considered trusted.) + * @return {*} A version of the value that's safe to use in the given context, or throws an + * exception if this is impossible. */ /** @@ -1051,12 +1048,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.HTML, value)`} * * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1068,12 +1065,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.CSS, value)`} * * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1085,12 +1082,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.URL, value)`} * * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1102,12 +1099,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.RESOURCE_URL, value)`} * * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ /** @@ -1119,12 +1116,12 @@ function $SceProvider() { * {@link ng.$sce#parseAs `$sce.parseAs($sce.JS, value)`} * * @param {string} expression String expression to compile. - * @return {function(context, locals)} a function which represents the compiled expression: + * @return {function(context, locals)} A function which represents the compiled expression: * - * * `context` – `{object}` – an object against which any expressions embedded in the - * strings are evaluated against (typically a scope object). - * * `locals` – `{object=}` – local variables context object, useful for overriding values - * in `context`. + * * `context` – `{object}` – an object against which any expressions embedded in the + * strings are evaluated against (typically a scope object). + * * `locals` – `{object=}` – local variables context object, useful for overriding values + * in `context`. */ // Shorthand delegations. From 90fec6ab5cc7f6ba6b0b83f89ae2591f35432131 Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Tue, 21 Mar 2017 15:00:09 +0100 Subject: [PATCH 5/6] doc($sce): add missing paragraph in resourceUrlBlacklist --- src/ng/sce.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/ng/sce.js b/src/ng/sce.js index c4b78e0e8334..fd05af2f1390 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -223,6 +223,7 @@ function $SceDelegateProvider() { * The typical usage for the blacklist is to **block * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as * these would otherwise be trusted but actually return content from the redirected domain. + *

* Finally, **the blacklist overrides the whitelist** and has the final say. * * @return {Array} The currently set blacklist array. From ac1c9f4e9015d4c3e8bba0c297c73a5724e8fa63 Mon Sep 17 00:00:00 2001 From: Raphael Jamet Date: Tue, 21 Mar 2017 15:50:03 +0100 Subject: [PATCH 6/6] doc($sce): trailing space --- src/ng/sce.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ng/sce.js b/src/ng/sce.js index fd05af2f1390..d47d6a0d335d 100644 --- a/src/ng/sce.js +++ b/src/ng/sce.js @@ -976,7 +976,7 @@ function $SceProvider() { * @param {string} type The context in which this value is to be used. * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs * `$sce.trustAs`} call, or anything else (which will not be considered trusted.) - * @return {*} A version of the value that's safe to use in the given context, or throws an + * @return {*} A version of the value that's safe to use in the given context, or throws an * exception if this is impossible. */