From 510b2d73037cd2409e59cac9726caf191150e11e Mon Sep 17 00:00:00 2001
From: Kimmo Puputti <git@kimmo.kpuputti.fi>
Date: Thu, 18 Jan 2018 11:13:54 +0200
Subject: [PATCH] Add CSP docs

---
 docs/README.md                  |  1 +
 docs/content-security-policy.md | 43 +++++++++++++++++++++++++++++++++
 public/index.html               |  8 ++++++
 3 files changed, 52 insertions(+)
 create mode 100644 docs/content-security-policy.md

diff --git a/docs/README.md b/docs/README.md
index a6cd401c..f5c88060 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,3 +19,4 @@ Documentation for specific topics can be found in the following files:
 * [Colors and icons](colors-and-icons.md)
 * [Starting a new customisation project](starting-a-new-customisation-project.md)
 * [Google Maps](google-maps.md)
+* [Content Security Policy (CSP)](content-security-policy.md)
diff --git a/docs/content-security-policy.md b/docs/content-security-policy.md
new file mode 100644
index 00000000..196a9bf1
--- /dev/null
+++ b/docs/content-security-policy.md
@@ -0,0 +1,43 @@
+# Content Security Policy (CSP)
+
+According to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP):
+
+> Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate
+> certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These
+> attacks are used for everything from data theft to site defacement or distribution of malware.
+
+This document describes how to use a CSP with the Starter App. By default the CSP is disabled. By
+turning it on, the default whitelist in [server/csp.js](../server/csp.js) works with the all the
+URLs and tools that come with the application.
+
+## Setup
+
+The CSP is configured using the `REACT_APP_CSP` environment variable.
+
+Possible values:
+
+* not set: disabled
+* `REACT_APP_CSP=report`: Enabled, but policy violations are only reported
+* `REACT_APP_CSP=block`: Enabled. Policy violations are reported and requests that violate the
+  policy are blocked
+
+If error logging with Sentry is enabled (See [Error logging with Sentry](sentry.md)), the reports
+are sent to Sentry. Otherwise the reports are just logged in the backend.
+
+## Extending the policy
+
+If you want to whitelist new sources (for example adding a new external analytics service) and keep
+the CSP enabled, you should add the domains to the white list in [server/csp.js](../server/csp.js).
+
+The easiest way to do this is to first turn on the policy in report mode and then see what policy
+violations are logged to the browser developer console or to the backend policy violation report
+URL.
+
+## Resources
+
+To understand what CSP is and how browsers work, here are some resources:
+
+* https://content-security-policy.com/
+* https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+* https://ponyfoo.com/articles/content-security-policy-in-express-apps
+* https://helmetjs.github.io/docs/csp/
diff --git a/public/index.html b/public/index.html
index ed031279..09ed1a31 100644
--- a/public/index.html
+++ b/public/index.html
@@ -158,5 +158,13 @@
     <script src="https://js.stripe.com/v3/"></script>
     <!--!preloadedStateScript-->
     <!--!script-->
+
+    <!--
+         Note when adding new external scripts/styles/fonts/etc.:
+         If a Content Security Policy (CSP) is turned on, the new URLs
+         should be whitelisted in the policy.
+
+         See docs/content-security-policy.md for more information.
+    -->
   </body>
 </html>