@angular-wave/angular.ts 0.9.3 → 0.9.5

package/src/services/sce/sce.md

@@ -1,300 +0,0 @@
-/\*\*
-
-- The $sceProvider provider allows developers to configure the {@link ng.$sce $sce} service.
-- - enable/disable Strict Contextual Escaping (SCE) in a module
-- - override the default implementation with a custom delegate
--
-- Read more about {@link ng.$sce Strict Contextual Escaping (SCE)}.
-  \*/
-
-/\*\*
-
--
-- `$sce` is a service that provides Strict Contextual Escaping services to AngularTS.
--
-- ## Strict Contextual Escaping
--
-- Strict Contextual Escaping (SCE) is a mode in which AngularTS 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, AngularTS treats all values as untrusted by default in
-- HTML or sensitive URL bindings. When binding untrusted values, AngularTS will automatically
-- run security checks on them (sanitizations, trusted URL resource, 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, AngularTS 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, AngularTS ships with SCE enabled by default.
--
-- ### In practice
--
-- Here's an example of a binding in a privileged context:
--
-- ```
-
-  ```
-
-- <input ng-model="userHtml" aria-label="User input">
-- <div ng-bind-html="userHtml"></div>
-- ```
-
-  ```
-
--
-- 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 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.
--
-- How would you ensure that every place that used these types of bindings was bound to a value that
-- was sanitized by your library (or returned as safe for rendering by your server?) How can you
-- 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, AngularTS 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 AngularTS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs}
-- (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
-- 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. Think of this function as
-- a way to enforce the required security context in your data sink. Directives use {@link
-- ng.$sceparseAs $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, AngularTS will understand the context of your bindings
-- automatically.
--
-- As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link
-- ng.$sceparseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly
-- simplified):
--
-- ```
-
-  ```
-
-- let ngBindHtmlDirective = ['$sce', function($sce) {
-- return function(scope, element, attr) {
--     scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
--       element.html(value || '');
--     });
-- };
-- }];
-- ```
-
-  ```
-
--
-- ### Impact on loading templates
--
-- This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
-- `templateUrl`'s specified by {@link guide/directive directives}.
--
-- By default, AngularTS only loads templates from the same domain and protocol as the application
-- document. This is done by calling {@link ng.$sce#getTrustedResourceUrl
-- $sce.getTrustedResourceUrl} on the template URL. To load templates from other domains and/or
-- protocols, you may either add them to the {@link ng.$sceDelegateProvider#trustedResourceUrlList
-- trustedResourceUrlList} or {@link ng.$sce#trustAsResourceUrl wrap them} into trusted values.
--
-- _Please note_:
-- The browser's
-- [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
-- and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
-- policy apply in addition to this and may further restrict whether the template is successfully
-- loaded. This means that without the right CORS policy, loading templates from a different domain
-- won't work on all browsers. Also, loading templates from `file://` URL does not work on some
-- browsers.
--
-- ### This feels like too much overhead
--
-- 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 (e.g.
-- `<div ng-bind-html="'<b>implicitly trusted</b>'"></div>`) just works (remember to include the
-- `ngSanitize` module). The `$sceDelegate` will also use the `$sanitize` service if it is available
-- when binding untrusted values to `$sce.HTML` context.
-- AngularTS 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.
-- It blocks loading templates from other domains or loading templates over http from an https
-- served document. You can change these by setting your own custom {@link
-- ng.$sceDelegateProvider#trustedResourceUrlList trusted resource URL list} and {@link
-- ng.$sceDelegateProvider#bannedResourceUrlList banned resource URL list} for matching such URLs.
--
-- This significantly reduces the overhead. It is far easier to pay the small overhead and have an
-- application that's secure and can be audited to verify that with much more ease than bolting
-- security onto an application later.
--
-- <a name="contexts"></a>
-- ### What trusted context types are supported?
--
-- | 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.MEDIA_URL` | For URLs that are safe to render as media. Is automatically converted from string by sanitizing when needed. |
-- | `$sce.URL` | For URLs that are safe to follow as links. Is automatically converted from string by sanitizing when needed. Note that `$sce.URL` makes a stronger statement about the URL than `$sce.MEDIA_URL` does and therefore contexts requiring values trusted for `$sce.URL` can be used anywhere that values trusted for `$sce.MEDIA_URL` are required.|
-- | `$sce.RESOURCE_URL` | For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include `ng-include`, `src` / `ngSrc` bindings for tags other than `IMG` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` or `$sce.MEDIA_URL` do and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` or `$sce.MEDIA_URL` are required. <br><br> The {@link $sceDelegateProvider#trustedResourceUrlList $sceDelegateProvider#trustedResourceUrlList()} and {@link $sceDelegateProvider#bannedResourceUrlList $sceDelegateProvider#bannedResourceUrlList()} can be used to restrict trusted origins for `RESOURCE_URL` |
-- | `$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. |
--
--
-- <div class="alert alert-warning">
-- Be aware that, before AngularTS 1.7.0, `a[href]` and `img[src]` used to sanitize their
-- interpolated values directly rather than rely upon {@link ng.$sce#getTrusted `$sce.getTrusted`}.
--
-- **As of 1.7.0, this is no longer the case.**
--
-- Now such interpolations are marked as requiring `$sce.URL` (for `a[href]`) or `$sce.MEDIA_URL`
-- (for `img[src]`), so that the sanitization happens (via `$sce.getTrusted...`) when the `$interpolate`
-- service evaluates the expressions.
-- </div>
--
-- There are no CSS or JS context bindings in AngularTS currently, so their corresponding `$sce.trustAs`
-- functions aren't useful yet. This might evolve.
--
-- ### Format of items in {@link ng.$sceDelegateProvider#trustedResourceUrlList trustedResourceUrlList}/{@link ng.$sceDelegateProvider#bannedResourceUrlList bannedResourceUrlList} <a name="resourceUrlPatternItem"></a>
--
-- Each element in these arrays must be one of the following:
--
-- - **'self'**
-- - The special **string**, `'self'`, can be used to match against all URLs of the \*\*same
--      domain** as the application document using the **same protocol**.
-- - **String** (except the special value `'self'`)
-- - The string is matched against the full _normalized / absolute URL_ of the resource
--      being tested (substring matches are not good enough.)
-- - There are exactly **two wildcard sequences** - `*` and `**`. All other characters
--      match themselves.
-- - `*`: matches zero or more occurrences of any character other than one of the following 6
--      characters: '`:`', '`/`', '`.`', '`?`', '`&`' and '`;`'.  It's a useful wildcard for use
--      for matching resource URL lists.
-- - `**`: matches zero or more occurrences of _any_ character. As such, it's not
--      appropriate for use in a scheme, domain, etc. as it would match too much.  (e.g.
--      http://**.example.com/ would match http://evil.com/?ignore=.example.com/ and that might
--      not have been the intention.)  Its usage at the very end of the path is ok.  (e.g.
--      http://foo.example.com/templates/**).
-- - **RegExp** (_see caveat below_)
-- - _Caveat_: While regular expressions are powerful and offer great flexibility, their syntax
--      (and all the inevitable escaping) makes them *harder to maintain*.  It's easy to
--      accidentally introduce a bug when one updates a complex expression (imho, all regexes should
--      have good test coverage).  For instance, the use of `.` in the regex is correct only in a
--      small number of cases.  A `.` character in the regex used when matching the scheme or a
--      subdomain could be matched against a `:` or literal `.` that was likely not intended.   It
--      is highly recommended to use the string patterns and only fall back to regular expressions
--      as a last resort.
-- - The regular expression must be an instance of RegExp (i.e. not a string.) It is
--      matched against the **entire** *normalized / absolute URL* of the resource being tested
--      (even when the RegExp did not have the `^` and `$` codes.)  In addition, any flags
--      present on the RegExp (such as multiline, global, ignoreCase) are ignored.
-- - If you are generating your JavaScript from some other templating engine (not
--      recommended, e.g. in issue [#4006](https://github.com/angular/angular.js/issues/4006)),
--      remember to escape your regular expression (and be aware that you might need more than
--      one level of escaping depending on your templating engine and the way you interpolated
--      the value.)  Do make use of your platform's escaping mechanism as it might be good
--      enough before coding your own.  E.g. Ruby has
--      [Regexp.escape(str)](http://www.ruby-doc.org/core-2.0.0/Regexp.html#method-c-escape)
--      and Python has [re.escape](http://docs.python.org/library/re.html#re.escape).
--      Javascript lacks a similar built in function for escaping.  Take a look at Google
--      Closure library's [goog.string.regExpEscape(s)](
--      http://docs.closure-library.googlecode.com/git/closure_goog_string_string.js.source.html#line962).
--
-- Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
--
--
-- ## Can I disable SCE completely?
--
-- Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security beneits
-- 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. 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 or libraries.
-- $sceProvider.enabled(false);
-- });
-- ```
-
-  ```
-
-- \*/
-
-/\* Design notes on the default implementation for SCE.
-
--
-- The API contract for the SCE delegate
-- ***
-- The SCE delegate object must provide the following 3 methods:
--
-- - trustAs(contextEnum, value)
--     This method is used to tell the SCE service that the provided value is OK to use in the
--     contexts specified by contextEnum.  It must return an object that will be accepted by
--     getTrusted() for a compatible contextEnum and return this value.
--
-- - valueOf(value)
--     For values that were not produced by trustAs(), return them as is.  For values that were
--     produced by trustAs(), return the corresponding input value to trustAs.  Basically, if
--     trustAs is wrapping the given values into some type, this operation unwraps it when given
--     such a value.
--
-- - getTrusted(contextEnum, value)
--     This function should return the value that is safe to use in the context specified by
--     contextEnum or throw and exception otherwise.
--
-- NOTE: This contract deliberately does NOT state that values returned by trustAs() must be
-- opaque or wrapped in some holder object. That happens to be an implementation detail. For
-- instance, an implementation could maintain a registry of all trusted objects by context. In
-- such a case, trustAs() would return the same object that was passed in. getTrusted() would
-- return the same object passed in if it was found in the registry under a compatible context or
-- throw an exception otherwise. An implementation might only wrap values some of the time based
-- on some criteria. getTrusted() might return a value and not throw an exception for special
-- constants or objects even if not wrapped. All such implementations fulfill this contract.
--
--
-- A note on the inheritance model for SCE contexts
-- ***
-- I've used inheritance and made RESOURCE_URL wrapped types a subtype of URL wrapped types. This
-- is purely an implementation details.
--
-- The contract is simply this:
--
--     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.
-  \*/