From 9340e1b065edb66717d937a86098541ac93278c6 Mon Sep 17 00:00:00 2001
From: Naomi Black <naomitraveller@gmail.com>
Date: Tue, 28 Jun 2016 11:01:35 -0700
Subject: [PATCH] docs(security): security api doc update and fix stability
 marker for Type

---
 .../@angular/compiler/src/runtime_compiler.ts |  4 ++++
 modules/@angular/compiler/src/url_resolver.ts |  5 +++++
 .../@angular/core/src/linker/element_ref.ts   |  4 ++++
 modules/@angular/facade/src/lang.ts           |  8 +++-----
 modules/@angular/http/src/http.ts             |  8 ++++++++
 .../@angular/platform-browser/src/browser.ts  |  3 +++
 .../src/security/dom_sanitization_service.ts  | 20 ++++++++++++++-----
 7 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/modules/@angular/compiler/src/runtime_compiler.ts b/modules/@angular/compiler/src/runtime_compiler.ts
index f532e008fe..e3fe012461 100644
--- a/modules/@angular/compiler/src/runtime_compiler.ts
+++ b/modules/@angular/compiler/src/runtime_compiler.ts
@@ -30,6 +30,10 @@ import {InterpretiveAppViewInstanceFactory} from './output/interpretive_view';
  * An internal module of the Angular compiler that begins with component types,
  * extracts templates, and eventually produces a compiled version of the component
  * ready for linking into an application.
+ *
+ * @security  When compiling templates at runtime, you must ensure that the entire template comes
+ * from a trusted source. Attacker-controlled data introduced by a template could expose your
+ * application to XSS risks.  For more detail, see the [Security Guide](http://g.co/ng/security).
  */
 @Injectable()
 export class RuntimeCompiler implements ComponentResolver, Compiler {
diff --git a/modules/@angular/compiler/src/url_resolver.ts b/modules/@angular/compiler/src/url_resolver.ts
index c4e2694018..0f74bb53a3 100644
--- a/modules/@angular/compiler/src/url_resolver.ts
+++ b/modules/@angular/compiler/src/url_resolver.ts
@@ -42,6 +42,11 @@ export var DEFAULT_PACKAGE_URL_PROVIDER = {
  * ## Example
  *
  * {@example compiler/ts/url_resolver/url_resolver.ts region='url_resolver'}
+ *
+ * @security  When compiling templates at runtime, you must
+ * ensure that the entire template comes from a trusted source.
+ * Attacker-controlled data introduced by a template could expose your
+ * application to XSS risks. For more detail, see the [Security Guide](http://g.co/ng/security).
  */
 @Injectable()
 export class UrlResolver {
diff --git a/modules/@angular/core/src/linker/element_ref.ts b/modules/@angular/core/src/linker/element_ref.ts
index 85b31005b3..f61cd6b748 100644
--- a/modules/@angular/core/src/linker/element_ref.ts
+++ b/modules/@angular/core/src/linker/element_ref.ts
@@ -12,6 +12,10 @@
  * An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
  * element.
  *
+ * @security Permitting direct access to the DOM can make your application more vulnerable to
+ * XSS attacks. Carefully review any use of `ElementRef` in your code. For more detail, see the
+ * [Security Guide](http://g.co/ng/security).
+ *
  * @stable
  */
 // Note: We don't expose things like `Injector`, `ViewContainer`, ... here,
diff --git a/modules/@angular/facade/src/lang.ts b/modules/@angular/facade/src/lang.ts
index d64590407e..1e5e49abdf 100644
--- a/modules/@angular/facade/src/lang.ts
+++ b/modules/@angular/facade/src/lang.ts
@@ -59,11 +59,6 @@ var _global: BrowserNodeGlobal = globalScope;
 
 export {_global as global};
 
-/**
- * @stable
- */
-export var Type = Function;
-
 /**
  * Runtime representation a type that a Component or other object is instances of.
  *
@@ -72,6 +67,9 @@ export var Type = Function;
  *
  * @stable
  */
+export var Type = Function;
+
+
 export interface Type extends Function {}
 
 /**
diff --git a/modules/@angular/http/src/http.ts b/modules/@angular/http/src/http.ts
index 4141da6a6a..24554eb9da 100644
--- a/modules/@angular/http/src/http.ts
+++ b/modules/@angular/http/src/http.ts
@@ -202,6 +202,14 @@ export class Jsonp extends Http {
    * a {@link Request} instance. If the first argument is a url, an optional {@link RequestOptions}
    * object can be provided as the 2nd argument. The options object will be merged with the values
    * of {@link BaseRequestOptions} before performing the request.
+   *
+   * @security Regular XHR is the safest alternative to JSONP for most applications, and is
+   * supported by all current browsers. Because JSONP creates a `<script>` element with
+   * contents retrieved from a remote source, attacker-controlled data introduced by an untrusted
+   * source could expose your application to XSS risks. Data exposed by JSONP may also be
+   * readable by malicious third-party websites. In addition, JSONP introduces potential risk for
+   * future security issues (e.g. content sniffing).  For more detail, see the
+   * [Security Guide](http://g.co/ng/security).
    */
   request(url: string|Request, options?: RequestOptionsArgs): Observable<Response> {
     var responseObservable: any;
diff --git a/modules/@angular/platform-browser/src/browser.ts b/modules/@angular/platform-browser/src/browser.ts
index ab30329ea7..98cd6c47e8 100644
--- a/modules/@angular/platform-browser/src/browser.ts
+++ b/modules/@angular/platform-browser/src/browser.ts
@@ -44,6 +44,9 @@ export const BROWSER_PLATFORM_PROVIDERS: Array<any /*Type | Provider | any[]*/>
 ];
 
 /**
+ * @security Replacing built-in sanitization providers exposes the application to XSS risks.
+ * Attacker-controlled data introduced by an unsanitized provider could expose your
+ * application to XSS risks. For more detail, see the [Security Guide](http://g.co/ng/security).
  * @experimental
  */
 export const BROWSER_SANITIZATION_PROVIDERS: Array<any> = [
diff --git a/modules/@angular/platform-browser/src/security/dom_sanitization_service.ts b/modules/@angular/platform-browser/src/security/dom_sanitization_service.ts
index 7363d8f639..2aa369b067 100644
--- a/modules/@angular/platform-browser/src/security/dom_sanitization_service.ts
+++ b/modules/@angular/platform-browser/src/security/dom_sanitization_service.ts
@@ -83,6 +83,11 @@ export interface SafeResourceUrl extends SafeValue {}
  * does not start with a suspicious protocol, or an HTML snippet that does not contain dangerous
  * code. The sanitizer leaves safe values intact.
  *
+ * @security Calling any of the `bypassSecurityTrust...` APIs disables Angular's built-in
+ * sanitization for the value passed in. Carefully check and audit all values and code paths going
+ * into this call. Make sure any user data is appropriately escaped for this security context.
+ * For more detail, see the [Security Guide](http://g.co/ng/security).
+ *
  * @stable
  */
 export abstract class DomSanitizationService implements SanitizationService {
@@ -101,21 +106,24 @@ export abstract class DomSanitizationService implements SanitizationService {
    * is unsafe (e.g. contains `<script>` tags) and the code should be executed. The sanitizer will
    * leave safe HTML intact, so in most situations this method should not be used.
    *
-   * WARNING: calling this method with untrusted user data will cause severe security bugs!
+   * **WARNING:** calling this method with untrusted user data exposes your application to XSS
+   * security risks!
    */
   abstract bypassSecurityTrustHtml(value: string): SafeHtml;
 
   /**
    * Bypass security and trust the given value to be safe style value (CSS).
    *
-   * WARNING: calling this method with untrusted user data will cause severe security bugs!
+   * **WARNING:** calling this method with untrusted user data exposes your application to XSS
+   * security risks!
    */
   abstract bypassSecurityTrustStyle(value: string): SafeStyle;
 
   /**
    * Bypass security and trust the given value to be safe JavaScript.
    *
-   * WARNING: calling this method with untrusted user data will cause severe security bugs!
+   * **WARNING:** calling this method with untrusted user data exposes your application to XSS
+   * security risks!
    */
   abstract bypassSecurityTrustScript(value: string): SafeScript;
 
@@ -123,7 +131,8 @@ export abstract class DomSanitizationService implements SanitizationService {
    * Bypass security and trust the given value to be a safe style URL, i.e. a value that can be used
    * in hyperlinks or `<img src>`.
    *
-   * WARNING: calling this method with untrusted user data will cause severe security bugs!
+   * **WARNING:** calling this method with untrusted user data exposes your application to XSS
+   * security risks!
    */
   abstract bypassSecurityTrustUrl(value: string): SafeUrl;
 
@@ -131,7 +140,8 @@ export abstract class DomSanitizationService implements SanitizationService {
    * Bypass security and trust the given value to be a safe resource URL, i.e. a location that may
    * be used to load executable code from, like `<script src>`, or `<iframe src>`.
    *
-   * WARNING: calling this method with untrusted user data will cause severe security bugs!
+   * **WARNING:** calling this method with untrusted user data exposes your application to XSS
+   * security risks!
    */
   abstract bypassSecurityTrustResourceUrl(value: string): SafeResourceUrl;
 }