From 267df4576d941a0d507b2736fa7dc7af0a7d172f Mon Sep 17 00:00:00 2001
From: wbamberg <will@bootbonnet.ca>
Date: Fri, 4 Oct 2024 14:47:55 -0700
Subject: [PATCH] Fix issue 36168: describe source expression upgrades

---
 .../content-security-policy/sources/index.md  | 32 +++++++++++++++----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/files/en-us/web/http/headers/content-security-policy/sources/index.md b/files/en-us/web/http/headers/content-security-policy/sources/index.md
index 718568028210b53..baeedfd7aae765a 100644
--- a/files/en-us/web/http/headers/content-security-policy/sources/index.md
+++ b/files/en-us/web/http/headers/content-security-policy/sources/index.md
@@ -7,7 +7,20 @@ spec-urls: https://w3c.github.io/webappsec-csp/#framework-directive-source-list
 
 {{HTTPSidebar}}
 
-HTTP {{HTTPHeader("Content-Security-Policy")}} (CSP) [fetch directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives) may take as a value a space-separated list of _source expressions_. Each source expression can be any of the values listed below.
+This page describes the syntax of a _source expression_, which is used in a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) to describe a way to decide whether the browser should be allowed to use a particular resource referenced by a web page.
+
+Most commonly, source expressions are used in CSP [fetch directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives), which are the parts of a CSP that define whether the browser is allowed to load a particular resource. Fetch directives a may take as a value a space-separated list of source expressions.
+
+For example, the following fetch directive, [`img-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src), contains two source expressions, `'self'` and `example.org`:
+
+```plain
+img-src 'self' example.org
+```
+
+- `'self'` means the resource can be loaded from the same origin as the document.
+- `example.org` means the resource can be loaded from the `example.org` domain.
+
+The overall effect of this directive is that images may be loaded from either of those sources.
 
 As well as fetch directives, some other CSP directives may take as a value a space-separated list of source expressions, each of which may be a subset of the values listed below, namely: one of `<host-source>`, `<scheme-source>`, or the keyword `'self'`. These other directives are:
 
@@ -19,11 +32,15 @@ Directives that accept a list of source expressions may instead be given the sin
 
 ## Sources
 
+A source expression follows one of the following formats. The `<host-source>` and `<scheme-source>` formats must be unquoted, and all other formats must be enclosed in single quotes.
+
 - `<host-source>`
 
   - : Internet host by name or IP address. The [URL scheme](/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL), port number, and path are optional.
     Wildcards (`'*'`) can be used for subdomains, host address, and port number, indicating that all legal values of each are valid.
-    When matching schemes, secure upgrades are allowed (e.g. specifying `http://example.com` will match `https://example.com`).
+
+    When matching schemes, secure upgrades are allowed, so `http://example.com` will also match `https://example.com`, and `ws://example.org` will also match `wss://example.org`.
+
     Examples:
 
     - `http://*.example.com`: Matches all attempts to load from any subdomain of example.com. Also matches `https` resources.
@@ -39,10 +56,9 @@ Directives that accept a list of source expressions may instead be given the sin
 
 - `<scheme-source>`
 
-  - : A scheme such as `http:` or `https:`.
-    The colon is required.
-    Unlike other values below, single quotes shouldn't be used.
-    You can also specify data schemes (not recommended).
+  - : A scheme such as `http:` or `https:`. The colon is required.
+
+    Secure upgrades are allowed, so `http:` will also match resources loaded using HTTPS, and `ws:` will also match resources loaded using WSS.
 
     - `data:` Allows [`data:` URLs](/en-US/docs/Web/URI/Schemes/data) to be used as a content source.
       _This is insecure; an attacker can also inject arbitrary `data:` URLs. Use this sparingly and definitely not for scripts._
@@ -56,9 +72,13 @@ Directives that accept a list of source expressions may instead be given the sin
     > For more information, see [CSP Level 3](https://www.w3.org/TR/CSP3/#match-url-to-source-list).
 
 - `'self'`
+
   - : Refers to the origin from which the protected document is being served, including the same URL scheme and port number.
     You must include the single quotes. Some browsers specifically exclude `blob` and `filesystem` from source directives.
     Sites needing to allow these content types can specify them using the Data attribute.
+
+    Note that `https:` and `wss:` schemes are automatically matched even if the document's origin does not match that scheme: so for example, if the document's origin is `https://example.org` and its CSP includes a directive like `connect-src 'self'`, then a WebSocket connection to `wss://example.org` will be allowed.
+
 - `'unsafe-eval'`
   - : Allows the use of `eval()` and other unsafe methods for creating code from strings.
     You must include the single quotes.