Security Edits Combined (#2245)

* Security Edits Combined

* Security copy edits

* Fix typo in security

* fixing trailing whitespace

public/docs/_examples/security/ts/app/bypass-security.component.html

@@ -2,7 +2,7 @@
 <h3>Bypass Security Component</h3>
 
 <!--#docregion dangerous-url -->
-<h4>A untrusted URL:</h4>
+<h4>An untrusted URL:</h4>
 <p><a class="e2e-dangerous-url" [href]="dangerousUrl">Click me</a></p>
 <h4>A trusted URL:</h4>
 <p><a class="e2e-trusted-url" [href]="trustedUrl">Click me</a></p>

public/docs/_examples/security/ts/app/bypass-security.component.ts

@@ -16,7 +16,7 @@ export class BypassSecurityComponent {
   // #docregion trust-url
   constructor(private sanitizer: DomSanitizer) {
     // javascript: URLs are dangerous if attacker controlled.
-    // Angular sanitizes them in data binding, but we can
+    // Angular sanitizes them in data binding, but you can
     // explicitly tell Angular to trust this value:
     this.dangerousUrl = 'javascript:alert("Hi there")';
     this.trustedUrl = sanitizer.bypassSecurityTrustUrl(this.dangerousUrl);
@@ -28,7 +28,7 @@ export class BypassSecurityComponent {
   updateVideoUrl(id: string) {
     // Appending an ID to a YouTube URL is safe.
     // Always make sure to construct SafeValue objects as
-    // close as possible to the input data, so
+    // close as possible to the input data so
     // that it's easier to check if the value is safe.
     this.dangerousVideoUrl = 'https://www.youtube.com/embed/' + id;
     this.videoUrl =

public/docs/_examples/security/ts/app/inner-html-binding.component.ts

@@ -8,6 +8,6 @@ import { Component } from '@angular/core';
 })
 // #docregion inner-html-controller
 export class InnerHtmlBindingComponent {
-  // E.g. a user/attacker controlled value from a URL.
+  // For example, a user/attacker-controlled value from a URL.
   htmlSnippet = 'Template <script>alert("0wned")</script> <b>Syntax</b>';
 }

public/docs/ts/latest/glossary.jade

@@ -41,7 +41,8 @@ block includes
   .l-sub-section
     :marked
       Helps us organize an application into cohesive blocks of functionality.
-      An Angular module identifies the components, directives, and pipes that the application uses      along with the list of external Angular modules that the application needs, such as `FormsModule`.
+      An Angular module identifies the components, directives, and pipes that the application uses 
+      along with the list of external Angular modules that the application needs, such as `FormsModule`.
 
       Every Angular application has an application root module class. By convention, the class is
       called `AppModule` and resides in a file named `app.component.ts`.
@@ -251,7 +252,7 @@ block includes
     that each do one thing well and then wiring them together at runtime.
 
     These parts often rely on other parts. An Angular [component](#component)
-    part might rely on a service part to get data or perform a calculation. When 
+    part might rely on a service part to get data or perform a calculation. When
     part "A" relies on another part "B", you say that "A" depends on "B" and
     that "B" is a dependency of "A".
 

public/docs/ts/latest/guide/security.jade

@@ -1,115 +1,113 @@
 block includes
   include ../_util-fns
 :marked
-  Web application security has many aspects. This chapter describes Angular's built in
-  protections against common web application vulnerabilities and attacks, such as Cross Site
-  Scripting Attacks. It does not cover application level security, such as authentication (_Who is
+  This section describes Angular's built-in
+  protections against common web application vulnerabilities and attacks such as cross-site
+  scripting attacks. It does not cover application-level security, such as authentication (_Who is
   this user?_) or authorization (_What can this user do?_).
 
-  The [Open Web Application Security Project (OWASP)](https://www.owasp.org/index.php/Category:OWASP_Guide_Project)
-  has further information on the attacks and mitigations described below.
+  For more information about the attacks and mitigations described below, see [OWASP Guide Project](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).
 
 .l-main-section
 :marked
-  # Table Of Contents
+  # Contents:
 
-  * [Reporting Vulnerabilities](#report-issues)
-  * [Best Practices](#best-practices)
-  * [Preventing Cross-Site Scripting (XSS)](#xss)
-  * [Trusting Safe Values](#bypass-security-apis)
-  * [HTTP-level Vulnerabilities](#http)
-  * [Auditing Angular Applications](#code-review)
+  * [Reporting vulnerabilities](#report-issues).
+  * [Best practices](#best-practices).
+  * [Preventing cross-site scripting (XSS)](#xss).
+  * [Trusting safe values](#bypass-security-apis).
+  * [HTTP-Level vulnerabilities](#http).
+  * [Auditing Angular applications](#code-review).
 
-  Try the <live-example></live-example> of the code shown in this chapter.
+  Try the <live-example></live-example> of the code shown in this page.
 
 .l-main-section
-h2#report-issues Reporting Vulnerabilities
+h2#report-issues Reporting vulnerabilities
 :marked
   Email us at [security@angular.io](mailto:security@angular.io) to report vulnerabilities in
   Angular itself.
 
-  For further details on how Google handles security issues please refer to [Google's security
+  For more information about how Google handles security issues, see [Google's security
   philosophy](https://www.google.com/about/appsecurity/).
 
 .l-main-section
-h2#best-practices Best Practices
+h2#best-practices Best practices
 :marked
   * **Keep current with the latest Angular library releases.**
-  We regularly update our Angular libraries and these updates may fix security defects discovered in
-  previous version. Check the Angular [change
+  We regularly update our Angular libraries, and these updates may fix security defects discovered in
+  previous versions. Check the Angular [change
   log](https://github.com/angular/angular/blob/master/CHANGELOG.md) for security-related updates.
 
   * **Don't modify your copy of Angular.**
-  Private, customized versions of Angular tend to fall behind the current version and may neglect
+  Private, customized versions of Angular tend to fall behind the current version and may not include
   important security fixes and enhancements. Instead, share your Angular improvements with the
   community and make a pull request.
 
-  * **Avoid Angular APIs marked in the documentation as “[_Security Risk_](#bypass-security-apis)”.**
+  * **Avoid Angular APIs marked in the documentation as “[_Security Risk_](#bypass-security-apis).”**
 
 .l-main-section
-h2#xss Preventing Cross-Site Scripting (XSS)
+h2#xss Preventing cross-site scripting (XSS)
 :marked
-  [Cross-Site Scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers
-  to inject malicious code into web pages. Such code can then, for example, steal user's data (in
-  particular their login data), or perform actions impersonating the user. This is one of the most
+  [Cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers
+  to inject malicious code into web pages. Such code can then, for example, steal user data (in
+  particular, their login data) or perform actions impersonating the user. This is one of the most
   common attacks on the web.
 
-  To block XSS attacks, we must prevent malicious code from entering the DOM. For example, if an
-  attacker can trick us into inserting a `<script>` tag in the DOM, they can run arbitrary code on
-  our website. The attack is not limited to `<script>` tags - many elements and properties in the
-  DOM allow code execution, for example `<img onerror="...">`, `<a href="javascript:...">`. If
-  attacker controlled data enters the DOM, we have to expect security vulnerabilities.
+  To block XSS attacks, you must prevent malicious code from entering the DOM (Document Object Model). For example, if an
+  attacker can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on
+  your website. The attack is not limited to `<script>` tags&mdash;many elements and properties in the
+  DOM allow code execution, for example, `<img onerror="...">` and `<a href="javascript:...">`. If
+  attacker-controlled data enters the DOM, expect security vulnerabilities.
 
-  ### Angular’s Cross-site Scripting Security Model
+  ### Angular’s cross-site scripting security model
 
   To systematically block XSS bugs, Angular treats all values as untrusted by default. When a value
-  is inserted into the DOM from a template, via property, attribute, style, or class binding, or via
-  interpolation, Angular will sanitize and escape untrusted values.
+  is inserted into the DOM from a template, via property, attribute, style, class binding, or interpolation, Angular sanitizes and escapes untrusted values.
 
-  **Angular templates are the same as executable code**: HTML, attributes, and binding expressions
-  (but not the values bound!) in templates are trusted to be safe. That means applications must
-  prevent potentially attacker controlled values from ever making it into the source code of a
+  _Angular templates are the same as executable code_: HTML, attributes, and binding expressions
+  (but not the values bound!) in templates are trusted to be safe. This means that applications must
+  prevent values that an attacker can control from ever making it into the source code of a
   template. Never generate template source code by concatenating user input and templates! Using
   the [offline template compiler](#offline-template-compiler) is an effective way to prevent these
-  vulnerabilities, also known as template injection.
+  vulnerabilities, also known as _template injection_.
 
   ### Sanitization and security contexts
 
-  Sanitization inspects an untrusted value and turns it into a value that is safe to insert into
-  the DOM. In many cases, values do not get changed by this at all. Sanitization depends on context:
+  _Sanitization_ is the inspection of an untrusted value, turning it into a value that is safe to insert into
+  the DOM. In many cases, sanitization does not change a value at all. Sanitization depends on context:
   a value that is harmless in CSS is potentially dangerous in a URL.
 
-  Angular defines four security contexts: HTML, style, URL, and resource URL.
+  Angular defines four security contexts&mdash;HTML, style, URL, and resource URL:
 
-  * HTML is used when interpreting a value as HTML, e.g., when binding to `innerHtml`
-  * Style is used when binding CSS into the `style` property
-  * URL is used for URL properties such as `<a href>`
-  * Resource URLs are URLs that will be loaded and executed as code, e.g., in `<script src>`
+  * **HTML** is used when interpreting a value as HTML, for example, when binding to `innerHtml`
+  * **Style** is used when binding CSS into the `style` property
+  * **URL** is used for URL properties such as `<a href>`
+  * **Resource URL** is a URL that will be loaded and executed as code, for example, in `<script src>`
 
   Angular sanitizes untrusted values for the first three items; sanitizing resource URLs is not
-  possible as they contain arbitrary code. In development mode, Angular prints a console warning
+  possible because they contain arbitrary code. In development mode, Angular prints a console warning
   when it has to change a value during sanitization.
 
   ### Sanitization example
 
   The template below binds the value of `htmlSnippet`, once by interpolating it into an element's
-  content, and once by binding it to the `innerHTML` property of an element.
+  content, and once by binding it to the `innerHTML` property of an element:
 
 +makeExample('app/inner-html-binding.component.html')
 
 :marked
-  Interpolated content is always escaped - the HTML is not interpreted, and the browser displays
-  angle brackets in the elements text content.
+  Interpolated content is always escaped&mdash;the HTML is not interpreted, and the browser displays
+  angle brackets in the element's text content.
 
-  For the HTML to be interpreted, we must bind to an HTML property, such as `innerHTML`. But binding
-  a potentially attacker controlled value into `innerHTML` would normally cause an XSS
-  vulnerability. For example, code contained in a `<script>` tag would be executed.
+  For the HTML to be interpreted, you must bind it to an HTML property such as `innerHTML`. But binding
+  a value that an attacker might control into `innerHTML` normally causes an XSS
+  vulnerability. For example, code contained in a `<script>` tag is executed:
 
 +makeExcerpt('app/inner-html-binding.component.ts ()', 'inner-html-controller')
 
 :marked
-  Angular recognizes the value as unsafe, and automatically sanitizes it. It removes the `<script>`
-  tag but keeps safe content, such as the text content of the `<script>` tag, or the `<b>` element.
+  Angular recognizes the value as unsafe and automatically sanitizes it, which removes the `<script>`
+  tag but keeps safe content such as the text content of the `<script>` tag, or the `<b>` element.
 
 figure.image-display
     img(src='/resources/images/devguide/security/binding-inner-html.png'
@@ -118,47 +116,46 @@ figure.image-display
   ### Avoid direct use of the DOM APIs
 
   The built-in browser DOM APIs do not automatically protect you from security vulnerabilities.
-  For example, `document`, the node available through `ElementRef`, and many third party APIs
-  contain unsafe methods. Avoid directly interacting with the DOM, and instead use Angular
+  For example, `document`, the node available through `ElementRef`, and many third-party APIs
+  contain unsafe methods. Avoid directly interacting with the DOM and instead use Angular
   templates where possible.
 
-  ### Content Security Policy
+  ### Content security policy
 
-  A [Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/) is a defense-in-depth
+  [Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/) is a defense-in-depth
   technique to prevent XSS. To enable CSP, configure your web server to return an appropriate
   `Content-Security-Policy` HTTP header.
 
   <a id="offline-template-compiler"></a>
-  ### Use the Offline Template Compiler
+  ### Use the offline template compiler
 
   The offline template compiler prevents a whole class of vulnerabilities called template injection,
   and also greatly improves application performance. Use the offline template compiler in production
-  deployments. Do not dynamically generate templates. Angular trusts template code, so generating
-  templates, in particular containing user data, circumvents Angular's built-in protections. See the
-  [Dynamic Forms Cookbook](../cookbook/dynamic-form.html) on how to dynamically construct forms in a
-  safe way.
+  deployments; do not dynamically generate templates. Angular trusts template code, so generating
+  templates, in particular templates containing user data, circumvents Angular's built-in protections. For information about how to dynamically construct forms in a safe way, see 
+  [Dynamic Forms Cookbook](../cookbook/dynamic-form.html).
 
-  ### Server side XSS protection
+  ### Server-side XSS protection
 
   HTML constructed on the server is vulnerable to injection attacks. Injecting template code into an
   Angular application is the same as injecting executable code into the
-  application; it gives the attacker full control over the application. To prevent this, make sure
-  to use a templating language that automatically escapes values to prevent XSS vulnerabilities on
-  the server. Do not generate Angular templates on the server side using a templating language, this
-  carries a high risk of introducing template injection vulnerabilities.
+  application: it gives the attacker full control over the application. To prevent this, 
+  use a templating language that automatically escapes values to prevent XSS vulnerabilities on
+  the server. Do not generate Angular templates on the server side using a templating language; doing this
+  carries a high risk of introducing template-injection vulnerabilities.
 
 .l-main-section
-h2#bypass-security-apis Trusting Safe Values
+h2#bypass-security-apis Trusting safe values
 :marked
   Sometimes applications genuinely need to include executable code, display an `<iframe>` from some
-  URL, or construct potentially dangerous URLs. To prevent automatic sanitization in this situation,
-  you can tell Angular that you inspected a value, checked how it is generated, and made sure it is
-  always secure. But **be careful**! If you trust a value that can be malicious, you will likely
-  introduce a security vulnerability into your application. If in doubt, find a professional
+  URL, or construct potentially dangerous URLs. To prevent automatic sanitization in any of these 
+  situations, you can tell Angular that you inspected a value, checked how it was generated, and made 
+  sure it will always be secure. But **be careful**! If you trust a value that might be malicious, you 
+  are introducing a security vulnerability into your application. If in doubt, find a professional 
   security reviewer.
 
-  You can mark a value as trusted by injecting `DomSanitizer`, and calling one of the
-  following methods.
+  You can mark a value as trusted by injecting `DomSanitizer` and calling one of the
+  following methods:
 
   * `bypassSecurityTrustHtml`
   * `bypassSecurityTrustScript`
@@ -167,15 +164,15 @@ h2#bypass-security-apis Trusting Safe Values
   * `bypassSecurityTrustResourceUrl`
 
   Remember, whether a value is safe depends on context, so you need to choose the right context for
-  your intended use of the value. Imagine the following template needs to bind a URL to a
-  `javascript:alert(...)` call.
+  your intended use of the value. Imagine that the following template needs to bind a URL to a
+  `javascript:alert(...)` call:
 
 +makeExcerpt('app/bypass-security.component.html ()', 'dangerous-url')
 
 :marked
-  Normally, Angular automatically sanitizes the URL, disables the dangerous code and,
+  Normally, Angular automatically sanitizes the URL, disables the dangerous code, and
   in development mode, logs this action to the console. To prevent
-  this, we can mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:
+  this, you can mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:
 
 +makeExcerpt('app/bypass-security.component.ts ()', 'trust-url')
 
@@ -184,80 +181,80 @@ figure.image-display
         alt='A screenshot showing an alert box created from a trusted URL')
 
 :marked
-  If we need to convert user input into a trusted value, it can be convenient to do so in a
-  controller method. The template below allows users to enter a YouTube video ID, and load the
+  If you need to convert user input into a trusted value, use a
+  controller method. The template below allows users to enter a YouTube video ID and load the
   corresponding video in an `<iframe>`. The `<iframe src>` attribute is a resource URL security
-  context, because an untrusted source can, e.g., smuggle in file downloads that unsuspecting users
-  would execute. So we call a method on the controller to construct a trusted video URL, which
-  Angular then allows binding into `<iframe src>`.
+  context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users 
+  could execute. So call a method on the controller to construct a trusted video URL, that causes
+  Angular to then allow binding into `<iframe src>`:
 
 +makeExcerpt('app/bypass-security.component.html ()', 'iframe-videoid')
 +makeExcerpt('app/bypass-security.component.ts ()', 'trust-video-url')
 
 .l-main-section
-h2#http HTTP-level Vulnerabilities
+h2#http HTTP-level vulnerabilities
 :marked
-  Angular has built in support to help prevent two common HTTP vulnerabilities, Cross-site Request
-  Forgery (XSRF) and Cross-site Script Inclusion (XSSI). Both of these must be primarily mitigated
+  Angular has built-in support to help prevent two common HTTP vulnerabilities, cross-site request
+  forgery (CSRF or XSRF) and cross-site script inclusion (XSSI). Both of these must be mitigated primarily 
   on the server side, but Angular ships helpers to make integration on the client side easier.
 
-h3#xsrf Cross-site Request Forgery (XSRF)
+h3#xsrf Cross-site request forgery
 :marked
-  In a Cross-site Request Forgery (XSRF or CSRF), an attacker tricks the user into visiting a
-  _different_ page, and has them, e.g., submit a form that sends a request to your application's
+  In a cross-site request forgery, an attacker tricks the user into visiting a
+  _different_ page and has them, for example, submit a form that sends a request to your application's
   web server. If the user is logged into your application, the browser will send authentication
-  cookies, and the attacker could &mdash; for example &mdash; cause a bank transfer in the user's name with
+  cookies, and the attacker could&mdash;for example&mdash;cause a bank transfer in the user's name with
   the right request.
 
   To prevent this, your application must ensure that user requests originate in your own
   application, not on a different site. A common technique is that the server sends a randomly
-  generated authentication token in a cookie, often with the name `XSRF-TOKEN`. Cookies can only
-  be read by the website on which they are set, so only your own application can read this token. On
+  generated authentication token in a cookie, often with the name `XSRF-TOKEN`. Only the website 
+  on which cookies are set can read the cookies, so only your own application can read this token. On
   each API request, the server then validates the client by checking that the token is sent back,
   usually in an HTTP header called `X-XSRF-TOKEN`.
 
   The Angular `http` client has built-in support for this technique. The default
   `CookieXSRFStrategy` looks for a cookie called `XSRF-TOKEN` and sets an HTTP request header named
   `X-XSRF-TOKEN` with the value of that cookie on every request. The server must set the
-  `XSRF-TOKEN` cookie, and validate the response header for each state modifying request.
+  `XSRF-TOKEN` cookie and validate the response header for each state-modifying request.
 
-  XSRF tokens should be unique per user and session, have a large random value generated by a
+  CSRF tokens should be unique per user and session, have a large random value generated by a
   cryptographically secure random number generator, and expire.
 
   Angular applications can customize cookie and header names by binding their own
-  `CookieXSRFStrategy` value, or implement an entirely custom `XSRFStrategy` by providing a custom
-  binding for that type, by adding either of the following to your providers list:
+  `CookieXSRFStrategy` value or implement an entirely custom `XSRFStrategy` through providing a custom
+  binding for that type by adding either of the following to your providers list:
 
 code-example(language="typescript").
   { provide: XSRFStrategy, useValue: new CookieXSRFStrategy('myCookieName', 'My-Header-Name')}
   { provide: XSRFStrategy, useClass: MyXSRFStrategy}
 
 :marked
-  Learn about Cross Site Request Forgery (XSRF) at the Open Web Application Security Project (OWASP)
-  [here](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29) and
-  [here](https://www.owasp.org/index.php/CSRF_Prevention_Cheat_Sheet). This [Stanford University
-  paper](https://seclab.stanford.edu/websec/csrf/csrf.pdf) is also a rich source of detail.
+  For information about CSRF at the Open Web Application Security Project (OWASP) see
+  [Cross-Site Request Forgery (CSRF)](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29) and
+  [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://www.owasp.org/index.php/CSRF_Prevention_Cheat_Sheet). The Stanford University
+  paper [Robust Defenses for Cross-Site Request Forgery](https://seclab.stanford.edu/websec/csrf/csrf.pdf) is also a rich source of detail.
 
-h3#xssi Cross-site Script Inclusion (XSSI)
+h3#xssi Cross-site script inclusion (XSSI)
 :marked
-  Cross-site Script Inclusion, also known as JSON vulnerability, can allow an attacker's website to
-  read data from a JSON API. The attack works on older browser by overriding native JavaScript
+  Cross-site script inclusion, also known as JSON vulnerability, can allow an attacker's website to
+  read data from a JSON API. The attack works on older browsers by overriding native JavaScript
   object constructors, and then including an API URL using a `<script>` tag.
 
   This attack is only successful if the returned JSON is executable as JavaScript. Servers can
-  prevent it by prefixing all JSON responses to make them non-executable, by convention using the
+  prevent an attack by prefixing all JSON responses to make them non-executable, by convention, using the
   well-known string `")]}',\n"`.
 
   Angular's `Http` library recognizes this convention and automatically strips the string
   `")]}',\n"` from all responses before further parsing.
 
-  Learn more in the XSSI section of this [Google web security blog
-  post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html)
+  For more information, see the XSSI section of this [Google web security blog
+  post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html).
 
 .l-main-section
-h2#code-review Auditing Angular Applications
+h2#code-review Auditing angular applications
 :marked
-  Angular applications should follow the same security principles as regular web applications, and
-  should be audited as such. Angular specific APIs that should be audited in a security review,
-  such as the [_bypassSecurityTrust_](#bypass-security-apis) APIs, are marked in the documentation
+  Angular applications must follow the same security principles as regular web applications, and
+  must be audited as such. Angular-specific APIs that should be audited in a security review,
+  such as the [_bypassSecurityTrust_](#bypass-security-apis) methods, are marked in the documentation
   as security sensitive.