docs(security): Add security documentation.

Substantially rewritten, based on original content by Brian Clarkio and
Ward Bell and contributions from Naomi Black.

Author: mprobst

public/docs/_examples/security/e2e-spec.ts

@@ -0,0 +1,25 @@
+/// <reference path="../_protractor/e2e.d.ts" />
+'use strict';
+describe('Security E2E Tests', () => {
+  beforeAll(function() { browser.get(''); });
+
+  it('sanitizes innerHTML', () => {
+    let interpolated = element(By.className('e2e-inner-html-interpolated'));
+    expect(interpolated.getText())
+        .toContain('Template <script>alert("0wned")</script> <b>Syntax</b>');
+    let bound = element(By.className('e2e-inner-html-bound'));
+    expect(bound.getText()).toContain('Template alert("0wned") Syntax');
+    let bold = element(By.css('.e2e-inner-html-bound b'));
+    expect(bold.getText()).toContain('Syntax');
+  });
+
+  it('binds trusted URLs', () => {
+    let dangerousUrl = element(By.className('e2e-dangerous-url'));
+    expect(dangerousUrl.getAttribute('href')).toMatch(/^javascript:alert/);
+  });
+
+  it('binds trusted resource URLs', () => {
+    let iframe = element(By.className('e2e-iframe'));
+    expect(iframe.getAttribute('src')).toMatch(/^https:\/\/www.youtube.com\//);
+  });
+});

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

@@ -0,0 +1,20 @@
+// #docregion
+import { Component } from '@angular/core';
+
+import { BypassSecurityComponent } from './bypass-security.component';
+import { InnerHtmlBindingComponent } from './inner-html-binding.component';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <h1>Security</h1>
+  <inner-html-binding></inner-html-binding>
+  <bypass-security></bypass-security>
+  `,
+  directives: [
+    BypassSecurityComponent,
+    InnerHtmlBindingComponent,
+  ],
+})
+export class AppComponent {
+}

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

@@ -0,0 +1,15 @@
+<!--#docregion -->
+<h3>Bypass Security Component</h3>
+
+<!--#docregion dangerous-url -->
+<h4>A dangerous URL:</h4>
+<p><a class="e2e-dangerous-url" [href]="dangerousUrl">Click me.</a></p>
+<!--#enddocregion dangerous-url -->
+
+<!--#docregion iframe-videoid -->
+<h4>Resource URL:</h4>
+<p><label>Showing: <input (input)="updateVideoUrl($event.target.value)"></label></p>
+<iframe class="e2e-iframe" width="640" height="390" [src]="videoUrl"></iframe>
+<!--#enddocregion iframe-videoid -->
+
+<!--#enddocregion -->

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

@@ -0,0 +1,33 @@
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+import { DomSanitizationService, SafeResourceUrl, SafeUrl } from '@angular/platform-browser';
+
+@Component({
+  selector: 'bypass-security',
+  templateUrl: 'app/bypass-security.component.html',
+})
+export class BypassSecurityComponent {
+  dangerousUrl: SafeUrl;
+  videoUrl: SafeResourceUrl;
+
+  // #docregion trust-url
+  constructor(private sanitizer: DomSanitizationService) {
+    // javascript: URLs are dangerous if attacker controlled. Angular sanitizes them in data
+    // binding, but we can explicitly tell Angular to trust this value:
+    this.dangerousUrl = sanitizer.bypassSecurityTrustUrl('javascript:alert("Hi there")');
+    // #enddocregion trust-url
+    this.updateVideoUrl('PUBnlbjZFAI');
+  }
+
+  // #docregion trust-video-url
+  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
+    // that it's easier to check if the value is safe.
+    this.videoUrl =
+        this.sanitizer.bypassSecurityTrustResourceUrl('https://www.youtube.com/embed/' + id);
+  }
+  // #enddocregion trust-video-url
+}
+// #enddocregion

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

@@ -0,0 +1,6 @@
+<!-- #docregion -->
+<h3>Binding innerHTML</h3>
+<p>Bound value:</p>
+<p class="e2e-inner-html-interpolated">{{htmlSnippet}}</p>
+<p>Result of binding to innerHTML:</p>
+<p class="e2e-inner-html-bound" [innerHTML]="htmlSnippet"></p>

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

@@ -0,0 +1,14 @@
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  moduleId: module.id,
+  selector: 'inner-html-binding',
+  templateUrl: 'inner-html-binding.component.html',
+})
+// #docregion inner-html-controller
+export class InnerHtmlBindingComponent {
+  // E.g. a user/attacker controlled value from a URL.
+  htmlSnippet = 'Template <script>alert("0wned")</script> <b>Syntax</b>';
+}
+// #enddocregion inner-html-controller

public/docs/_examples/security/ts/app/main.ts

@@ -0,0 +1,8 @@
+// #docregion
+import { bootstrap } from '@angular/platform-browser-dynamic';
+
+// #docregion import
+import { AppComponent } from './app.component';
+// #enddocregion import
+
+bootstrap(AppComponent);

public/docs/_examples/security/ts/example-config.json

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<!-- #docregion -->
+<html>
+  <head>
+    <title>Angular Content Security</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="styles.css">
+
+     <!-- Polyfill(s) for older browsers -->
+    <script src="node_modules/core-js/client/shim.min.js"></script>
+
+    <script src="node_modules/zone.js/dist/zone.js"></script>
+    <script src="node_modules/reflect-metadata/Reflect.js"></script>
+    <script src="node_modules/systemjs/dist/system.src.js"></script>
+
+    <script src="systemjs.config.js"></script>
+    <script>
+      System.import('app').catch(function(err){ console.error(err); });
+    </script>
+  </head>
+
+  <body>
+    <app-root>Loading...</app-root>
+  </body>
+</html>

public/docs/_examples/security/ts/index.html

@@ -0,0 +1,8 @@
+{
+  "description": "Content Security",
+  "files": [
+    "!**/*.d.ts",
+    "!**/*.js"
+  ],
+  "tags": ["security"]
+}