From 9edb0071428a42c491357a2475ffd72cede4ff93 Mon Sep 17 00:00:00 2001
From: Ze Yu <angzeyu@gmail.com>
Date: Sat, 19 Nov 2022 22:20:48 +0800
Subject: [PATCH] Document content security policy

---
 docs/src/SUMMARY.md      |  1 +
 docs/src/csp.md          | 24 ++++++++++++++++++++++++
 docs/src/introduction.md |  8 +++-----
 3 files changed, 28 insertions(+), 5 deletions(-)
 create mode 100644 docs/src/csp.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 2d35b1db..f0c5c72a 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -5,6 +5,7 @@
 # User Guide
 
 - [Getting Started](./getting_started.md)
+  - [Content Security Policy](./csp.md)
   - [mdBook](./getting_started_mdbook.md)
   - [Others](./getting_started_others.md)
 - [Search UI](./search_configuration.md)
diff --git a/docs/src/csp.md b/docs/src/csp.md
new file mode 100644
index 00000000..68078a5f
--- /dev/null
+++ b/docs/src/csp.md
@@ -0,0 +1,24 @@
+# Content Security Policy
+
+## WebAssembly CSP
+
+InfiSearch runs using WebAssembly. If you are using a restrictive content security policy,  WebAssembly as a whole currently unfortunately requires adding the `script-src: 'unsafe-eval';` directive.
+
+This error will show up in chrome for example as the following extremely detailed error message:
+
+
+> Uncaught (in promise) CompileError: WebAssembly.instantiateStreaming():
+> Refused to compile or instantiate WebAssembly module because 'unsafe-eval'
+> is not an allowed source of script in the following Content Security Policy directive: '...'
+
+Support for a more specific `script-src: 'wasm-unsafe-eval';` directive has landed in Chrome, Edge and Firefox, but is still pending in Safari.
+
+## WebWorker CSP
+
+InfiSearch also utilises a [blob URL](https://stackoverflow.com/questions/30864573/what-is-a-blob-url-and-why-it-is-used) to load its WebWorker. This shouldn't pose as much of a security concern since blob URLs can only be created by scripts already executing within the browser.
+
+To whitelist this, add the `script-src: blob:;` directive.
+
+## CDN CSP
+
+Naturally, if you load InfiSearch assets from CDN, you will also need to whitelist this in the `script-src: cdn.jsdelivr.net;` and `style-src: cdn.jsdelivr.net;` directives.
diff --git a/docs/src/introduction.md b/docs/src/introduction.md
index 12ae07ae..77a7279a 100644
--- a/docs/src/introduction.md
+++ b/docs/src/introduction.md
@@ -16,17 +16,15 @@ InfiSearch is a *client-side* search solution made for static sites, including a
 
 ## How it Works:
 
-The following is a quick high level breakdown of how InfiSearch works:
-
-1. The CLI indexer tool generates:
+1. The CLI indexer tool first generates:
    - Binary index files
    - JSON field stores (raw document texts)
    - Supporting metadata (e.g. search dictionary)
-1. The search UI, which consists a JS file and WebAssembly binary:
+1. The search UI:
    1. Figures out which index files are needed from the user query
    1. Retrieves the index files from cache/memory/network requests
    1. Obtains and ranks the result set
-   1. Finally, retrieves the field stores from cache/memory/network requests progressively to generate result previews to show to the user!
+   1. Finally, retrieves the field stores from cache/memory/network requests progressively to generate result previews
 
 ## Search Features in Detail