docs($sce): overhaul the $sce service documentation
A big docs update around `$sce`: There is a lot of content in there that is often misunderstood, and some of the documentation starts to get really old too. Also fixed capitalization, formatting, indentation and uniformized `@param` descriptions. Closes #15735
This commit is contained in:
Raphael Jamet
committed by
Georgios Kalpakas
Georgios Kalpakas
parent
d96e58fdc8
commit
0d9d57d418
+252
-182
@@ -16,12 +16,21 @@
|
||||
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 +92,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.
|
||||
*
|
||||
* <div class="alert alert-danger">
|
||||
* 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.
|
||||
* </div>
|
||||
*
|
||||
* 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 +127,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}
|
||||
* $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
|
||||
* places that use the `$sce.RESOURCE_URL` context). 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 +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`.
|
||||
*/
|
||||
|
||||
function $SceDelegateProvider() {
|
||||
@@ -155,23 +185,23 @@ 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.
|
||||
*
|
||||
* <div class="alert alert-warning">
|
||||
* **Note:** an empty whitelist array will block all URLs!
|
||||
* </div>
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @description
|
||||
* Sets/Gets the whitelist of trusted resource URLs.
|
||||
* <div class="alert alert-warning">
|
||||
* **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.
|
||||
* </div>
|
||||
*/
|
||||
this.resourceUrlWhitelist = function(value) {
|
||||
if (arguments.length) {
|
||||
@@ -186,25 +216,23 @@ 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.</p><p>
|
||||
* Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items
|
||||
* allowed in this array.</p><p>
|
||||
* 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.
|
||||
* </p><p>
|
||||
* Finally, **the blacklist overrides the whitelist** and has the final say.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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) {
|
||||
@@ -288,17 +316,24 @@ 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.
|
||||
* 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.
|
||||
*
|
||||
* @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 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 should be considered trusted.
|
||||
* @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);
|
||||
@@ -330,11 +365,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`}, 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.
|
||||
* @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.
|
||||
*/
|
||||
@@ -351,33 +386,38 @@ 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.
|
||||
*
|
||||
* <div class="alert alert-danger">
|
||||
* Disabling auto-escaping is extremely dangerous, it usually creates a Cross Site Scripting
|
||||
* (XSS) vulnerability in your application.
|
||||
* </div>
|
||||
* 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.)
|
||||
*
|
||||
* @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.
|
||||
* @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.)
|
||||
* @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) {
|
||||
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 +426,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 +465,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.
|
||||
*
|
||||
* ## Overview
|
||||
*
|
||||
* 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
|
||||
* can be sanitized, but template URLs cannot, for instance.
|
||||
*
|
||||
* 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 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.
|
||||
*
|
||||
* 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
|
||||
* <http://blogs.msdn.com/b/ie/archive/2008/10/16/ending-expressions.aspx> to learn more about them.
|
||||
* You can ensure your document is in standards mode and not quirks mode by adding `<!doctype html>`
|
||||
* to the top of your HTML document.
|
||||
*
|
||||
* 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.
|
||||
* ## In practice
|
||||
*
|
||||
* Here's an example of a binding in a privileged context:
|
||||
*
|
||||
@@ -447,10 +495,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 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.
|
||||
@@ -460,25 +508,29 @@ 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
|
||||
* 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.
|
||||
* $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.
|
||||
*
|
||||
* 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 +571,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.
|
||||
* `<div ng-bind-html="'<b>implicitly trusted</b>'"></div>`) 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.
|
||||
* `<div ng-bind-html="'<b>implicitly trusted</b>'"></div>`) just works. The `$sceDelegate` will
|
||||
* 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.
|
||||
*
|
||||
* 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 +594,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 (`<a href=` and `<img src=` sanitize their urls and don't constitute an SCE context. |
|
||||
* | `$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`, `VIDEO`, `AUDIO`, `SOURCE`, and `TRACK` (e.g. `IFRAME`, `OBJECT`, etc.), plus some miscellaneous sensitive attributes (BASE HREF, LINK HREF, etc.)<br><br>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 (`<a href=`, `<img src=`, and some others sanitize their urls and don't constitute an SCE context.) |
|
||||
* | `$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`, `VIDEO`, `AUDIO`, `SOURCE`, and `TRACK` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>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} <a name="resourceUrlPatternItem"></a>
|
||||
*
|
||||
@@ -664,14 +723,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);
|
||||
* });
|
||||
* ```
|
||||
@@ -686,8 +746,8 @@ function $SceProvider() {
|
||||
* @name $sceProvider#enabled
|
||||
* @kind function
|
||||
*
|
||||
* @param {boolean=} value If provided, then enables/disables SCE.
|
||||
* @return {boolean} true if SCE is enabled, false otherwise.
|
||||
* @param {boolean=} value If provided, then enables/disables SCE application-wide.
|
||||
* @return {boolean} True if SCE is enabled, false otherwise.
|
||||
*
|
||||
* @description
|
||||
* Enables/disables SCE and returns the current value.
|
||||
@@ -741,9 +801,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(
|
||||
@@ -765,8 +825,8 @@ function $SceProvider() {
|
||||
* @name $sce#isEnabled
|
||||
* @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}.
|
||||
* @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
|
||||
* Returns a boolean indicating if SCE is enabled.
|
||||
@@ -793,14 +853,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);
|
||||
@@ -818,18 +878,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
|
||||
* interpolations. 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 {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.
|
||||
* @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
|
||||
* in the context you specified.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -840,11 +900,23 @@ 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 `$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 `$sce.CSS` context. This context is currently unused, so there are
|
||||
* almost no reasons to use this function so far.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -855,11 +927,10 @@ 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 `$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.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -870,11 +941,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 `$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, ...)
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -885,11 +955,10 @@ 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 `$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.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -898,16 +967,17 @@ 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`}
|
||||
* 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, 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.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -919,7 +989,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)`
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -931,7 +1001,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)`
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -943,7 +1013,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)`
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -955,7 +1025,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)`
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -967,7 +1037,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)`
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -979,12 +1049,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`.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -996,12 +1066,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`.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -1013,12 +1083,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`.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -1030,12 +1100,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`.
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -1047,12 +1117,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.
|
||||
|
||||
Reference in New Issue
Block a user