Further clarification in CSP documentation. (aws#1680)

* Don't require a CHANGELOG entry for changes to guides, because they are not part of a release.

* Further clarification in CSP documentation.

Co-authored-by: Trung Le <[email protected]>

.changelog-watchlist

@@ -1,6 +1,5 @@
 # Require changelog if files in these directories change
 src/
-guides/
 libs/voicefocus
 
-# Exceptions (Add an exception by adding a path and prepend with a '!' )
+# Exceptions (Add an exception by adding a path and prepend with a '!' )

docs/modules/amazonvoice_focus.html

@@ -182,10 +182,15 @@ <h3>Content Security Policy</h3>
 						<li><code>worker-src</code>: add <code>blob:</code> to load worker JavaScript across origins.</li>
 						<li><code>child-src</code>: add <code>blob:</code> to load worker JavaScript across origins (only in Safari).</li>
 					</ul>
-					<p>In Chrome 95 and later, compiled WebAssembly modules cannot be passed across module boundaries, and the Amazon Voice Focus worker needs additional policy entries to allow it to compile its own estimation code. You must add:</p>
+					<p>In Chrome 95 and later, compiled WebAssembly modules cannot be passed across module boundaries, so your application must be permitted to evaluate those modules. You must add the following to <code>script-src</code> and <code>script-src-elem</code>:</p>
 					<ul>
-						<li><code>script-src</code>: <code>&#39;wasm-eval&#39;</code> and <code>&#39;wasm-unsafe-eval&#39;</code> to compile fetched WebAssembly, and <code>&#39;unsafe-eval&#39;</code> to allow the worker to compile.</li>
+						<li><code>&#39;wasm-eval&#39;</code> and <code>&#39;wasm-unsafe-eval&#39;</code> to compile fetched WebAssembly in your application.</li>
 					</ul>
+					<p>In Chrome 96 and later, the Amazon Voice Focus worker needs an additional policy entry to allow it to compile WebAssembly. If your application does not specify a fixed <code>variant</code> in its model spec, or uses a worker-based execution mode, then you must add the following to <code>script-src</code> and <code>script-src-elem</code>:</p>
+					<ul>
+						<li><code>&#39;unsafe-eval&#39;</code> to allow the worker to compile the estimator and/or noise suppression code.</li>
+					</ul>
+					<p>This might be an unintentional regression in Chrome; an <a href="https://bugs.chromium.org/p/chromium/issues/detail?id=1259726">issue has been filed</a>.</p>
 					<p>If you omit any of these entries, or if you use both HTTP headers and <code>http-equiv</code> <code>meta</code> tags to specify policy and inadvertently exclude any of these by intersection, then Amazon Voice Focus will not be able to initialize, and will either appear to be unsupported or will fail to create a suppressed audio device. You will see errors in your browser console like:</p>
 					<pre><code>Refused <span class="hljs-built_in">to</span> connect <span class="hljs-built_in">to</span>
 <span class="hljs-string">&#x27;https://static.sdkassets.chime.aws/workers/worker-v1.js…&#x27;</span>

docs/modules/contentsecurity_policy.html

@@ -126,15 +126,8 @@ <h2>Logging</h2>
 					<a href="#amazon-voice-focus" id="amazon-voice-focus" style="color: inherit; text-decoration: none;">
 						<h2>Amazon Voice Focus</h2>
 					</a>
-					<p>To use <a href="https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html">Amazon Voice Focus</a>, ensure that your policy includes the following:</p>
-					<ul>
-						<li><code>script-src</code> and <code>script-src-elem</code>: <code>https://*.sdkassets.chime.aws</code> to load audio processing code to run in the browser’s audio renderer thread.</li>
-						<li><code>connect-src</code>: <code>https://*.sdkassets.chime.aws</code> to load model files via <code>fetch</code>.</li>
-						<li><code>worker-src</code>: <code>blob:</code> to load worker JavaScript across origins.</li>
-						<li><code>child-src</code>: <code>blob:</code> to load worker JavaScript across origins (only in Safari).</li>
-					</ul>
-					<p>See the <a href="https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html#content-security-policy">Amazon Voice Focus guide</a> for more information.
-					<a href="https://github.com/aws/amazon-chime-sdk-js/issues/new?assignees=&amp;labels=documentation&amp;template=documentation-request.md&amp;title=Content%20Security_Policy%20feedback">Give feedback on this guide</a></p>
+					<p>To use <a href="https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html">Amazon Voice Focus</a>, see the <a href="https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html#content-security-policy">Amazon Voice Focus guide</a>.</p>
+					<p><a href="https://github.com/aws/amazon-chime-sdk-js/issues/new?assignees=&amp;labels=documentation&amp;template=documentation-request.md&amp;title=Content%20Security_Policy%20feedback">Give feedback on this guide</a></p>
 				</div>
 			</section>
 		</div>

guides/09_Amazon_Voice_Focus.md

@@ -82,9 +82,15 @@ Modern web applications use [Content Security Policy](https://developer.mozilla.
 * `worker-src`: add `blob:` to load worker JavaScript across origins.
 * `child-src`: add `blob:` to load worker JavaScript across origins (only in Safari).
 
-In Chrome 95 and later, compiled WebAssembly modules cannot be passed across module boundaries, and the Amazon Voice Focus worker needs additional policy entries to allow it to compile its own estimation code. You must add:
+In Chrome 95 and later, compiled WebAssembly modules cannot be passed across module boundaries, so your application must be permitted to evaluate those modules. You must add the following to `script-src` and `script-src-elem`:
 
-* `script-src`: `'wasm-eval'` and `'wasm-unsafe-eval'` to compile fetched WebAssembly, and `'unsafe-eval'` to allow the worker to compile.
+* `'wasm-eval'` and `'wasm-unsafe-eval'` to compile fetched WebAssembly in your application.
+
+In Chrome 96 and later, the Amazon Voice Focus worker needs an additional policy entry to allow it to compile WebAssembly. If your application does not specify a fixed `variant` in its model spec, or uses a worker-based execution mode, then you must add the following to `script-src` and `script-src-elem`:
+
+* `'unsafe-eval'` to allow the worker to compile the estimator and/or noise suppression code.
+
+This might be an unintentional regression in Chrome; an [issue has been filed](https://bugs.chromium.org/p/chromium/issues/detail?id=1259726).
 
 If you omit any of these entries, or if you use both HTTP headers and `http-equiv` `meta` tags to specify policy and inadvertently exclude any of these by intersection, then Amazon Voice Focus will not be able to initialize, and will either appear to be unsupported or will fail to create a suppressed audio device. You will see errors in your browser console like:
 

guides/14_Content_Security_Policy.md

@@ -74,11 +74,4 @@ meetingSession.audioVideo.start()
 
 ## Amazon Voice Focus
 
-To use [Amazon Voice Focus](https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html), ensure that your policy includes the following:
-
-* `script-src` and `script-src-elem`: `https://*.sdkassets.chime.aws` to load audio processing code to run in the browser’s audio renderer thread.
-* `connect-src`: `https://*.sdkassets.chime.aws` to load model files via `fetch`.
-* `worker-src`: `blob:` to load worker JavaScript across origins.
-* `child-src`: `blob:` to load worker JavaScript across origins (only in Safari).
-
-See the [Amazon Voice Focus guide](https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html#content-security-policy) for more information.
+To use [Amazon Voice Focus](https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html), see the [Amazon Voice Focus guide](https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html#content-security-policy).