chore(http): Refresh headers ~[s->x] (#36862)

* chore(http): Refresh headers s, source map glossary * chore(http): Refresh headers s, source map glossary * chore(http): Typo * chore(http): Delete Want-Digest header * chore(http): Updates to headers pages * chore(http): Updates to headers pages * chore(http): Updates to headers pages * chore(http): Updates to headers pages * chore(http): Updates to headers pages * chore(http): Updates to headers pages * chore(http): Reduce noise in PR * Update files/en-us/glossary/source_map/index.md * chore(HTTP): Fix common macro typo, improve syntax section * chore(HTTP): Some fixes for chunked encoding * chore(HTTP): Some fixes for www-authenticate * chore(HTTP): Some fixes for proxy auth, don't deploy HTTP headers * chore(HTTP): Remove compat data from prose * chore(HTTP): Be more strict about client IPs in request chain * Update files/en-us/web/http/headers/proxy-authenticate/index.md Co-authored-by: Hamish Willee <[email protected]> * chore(http): improvements following reviewer feedback * chore(http): improvements following reviewer feedback --------- Co-authored-by: Hamish Willee <[email protected]>
mdn · Dec 9, 2024 · ed04138 · ed04138
1 parent fa17d0e
commit ed04138
Show file tree

Hide file tree

Showing 47 changed files with 850 additions and 601 deletions.
diff --git a/files/en-us/glossary/source_map/index.md b/files/en-us/glossary/source_map/index.md
@@ -0,0 +1,20 @@
+---
+title: Source map
+slug: Glossary/Source_map
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+A **source map** is a file that maps between minified or transformed code received by the browser and its original unmodified form, allowing the original code to be reconstructed and used when debugging.
+
+The JavaScript code executed by the browser has often been transformed in some way from the original source created by a developer.
+For example, sources are often combined and minified to make delivering them from the server more efficient.
+Additionally, JavaScript running on a page is often machine-generated, such as compiled from a language like TypeScript.
+
+In these situations, debugging the original source is much easier than the source in the transformed state that the browser has downloaded.
+
+## See also
+
+- HTTP {{HTTPHeader("SourceMap")}} response header
+- [Firefox Developer Tools: using a source map](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html)
diff --git a/files/en-us/web/api/ndefrecord/lang/index.md b/files/en-us/web/api/ndefrecord/lang/index.md
@@ -38,4 +38,4 @@ A string.
 ## See also
 
 - [HTML `lang` attribute](/en-US/docs/Web/HTML/Global_attributes/lang), that declares content language of the document or its elements
-- HTTP headers that declare content language: {{HTTPHeader("Content-Language")}} and {{HTTPHEader("Accept-Language")}}
+- HTTP headers that declare content language: {{HTTPHeader("Content-Language")}} and {{HTTPHeader("Accept-Language")}}
diff --git a/files/en-us/web/http/headers/connection/index.md b/files/en-us/web/http/headers/connection/index.md
@@ -70,3 +70,8 @@ Connection: close
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [Connection management in HTTP/1.x](/en-US/docs/Web/HTTP/Connection_management_in_HTTP_1.x)
+- [Protocol upgrade mechanism](/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism)
diff --git a/files/en-us/web/http/headers/forwarded/index.md b/files/en-us/web/http/headers/forwarded/index.md
@@ -14,7 +14,7 @@ The header is optional and may be added to, modified, or removed, by any of the
 
 This header is used for debugging, statistics, and generating location-dependent content.
 By design, it exposes privacy sensitive information, such as the IP address of the client.
-Therefore, the user's privacy must be kept in mind when deploying this header.
+Therefore, the user's privacy must be kept in mind when using this header.
 
 The alternative and de-facto standard versions of this header are the {{HTTPHeader("X-Forwarded-For")}}, {{HTTPHeader("X-Forwarded-Host")}} and {{HTTPHeader("X-Forwarded-Proto")}} headers.
 

diff --git a/files/en-us/web/http/headers/index.md b/files/en-us/web/http/headers/index.md
@@ -316,7 +316,7 @@ Headers used by the [WebSockets API](/en-US/docs/Web/API/WebSockets_API) in the
 - `Service-Worker-Allowed`
   - : Used to remove the [path restriction](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#why_is_my_service_worker_failing_to_register) by including this header [in the response of the Service Worker script](https://w3c.github.io/ServiceWorker/#service-worker-script-response).
 - {{HTTPHeader("SourceMap")}}
-  - : Links generated code to a [source map](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html).
+  - : Links to a {{Glossary("source map")}} so that debuggers can step through original source code instead of generated or transformed code.
 - {{HTTPHeader("Upgrade")}}
   - : This HTTP/1.1 (only) header can be used to upgrade an already established client/server connection to a different protocol (over the same transport protocol). For example, it can be used by a client to upgrade a connection from HTTP 1.1 to HTTP 2.0, or an HTTP or HTTPS connection into a WebSocket.
 - {{HTTPHeader("Priority")}}

diff --git a/files/en-us/web/http/headers/no-vary-search/index.md b/files/en-us/web/http/headers/no-vary-search/index.md
@@ -132,3 +132,7 @@ No-Vary-Search: params, except=("id")
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} header
diff --git a/files/en-us/web/http/headers/origin-agent-cluster/index.md b/files/en-us/web/http/headers/origin-agent-cluster/index.md
@@ -9,10 +9,37 @@ browser-compat: http.headers.Origin-Agent-Cluster
 
 {{HTTPSidebar}}{{SeeCompatTable}}
 
-The HTTP **`Origin-Agent-Cluster`** {{Glossary("response header")}} is used to request that the associated {{domxref("Document")}} should be placed in an _origin-keyed [agent cluster](https://tc39.es/ecma262/#sec-agent-clusters)_. This means that operating system resources (for example, the operating system process) used to evaluate the document should be shared only with other documents from the same {{glossary("origin")}}.
+The HTTP **`Origin-Agent-Cluster`** {{Glossary("response header")}} is used to request that the associated {{domxref("Document")}} should be placed in an **origin-keyed [agent cluster](https://tc39.es/ecma262/#sec-agent-clusters)**. This means that operating system resources (for example, the operating system process) used to evaluate the document should be shared only with other documents from the same {{glossary("origin")}}.
 
 The effect of this is that a resource-intensive document will be less likely to degrade the performance of documents from other origins.
 
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>{{Glossary("Response header")}}</td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Origin-Agent-Cluster: <boolean>
+```
+
+### Directives
+
+- `<boolean>`
+  - : `?1` indicates that the associated {{domxref("Document")}} should be placed in an origin-keyed agent cluster.
+    Values other than `?1` are ignored (e.g., the `?0` structured field for false).
+
+## Description
+
 Modern web browsers have a multiprocess architecture in which pages from different origins can run in different operating system processes. This is important for performance, because it means that a resource-intensive page will not have as much of an impact on other pages that the user has open.
 
 However, browsers can't as a general rule run {{glossary("site", "same-site")}}, {{glossary("origin", "cross-origin")}} pages in different processes, because of certain DOM APIs that depend on same-site, cross-origin communication. For example, by default, pages from the following two origins will share the same operating system resources:
@@ -41,31 +68,6 @@ The browser will ensure that all pages from a given origin are either origin-key
 
 To avoid this kind of unpredictable situation, you should set this header for all pages from a given origin, or none of them.
 
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Header type</th>
-      <td>{{Glossary("Response header")}}</td>
-    </tr>
-    <tr>
-      <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>No</td>
-    </tr>
-  </tbody>
-</table>
-
-## Syntax
-
-```http
-Origin-Agent-Cluster: <boolean>
-```
-
-### Directives
-
-- `<boolean>`
-  - : `?1` indicates that the associated {{domxref("Document")}} should be placed in an origin-keyed agent cluster.
-    Values other than `?1` are ignored (e.g., the `?0` structured field for false).
-
 ## Examples
 
 ```http

diff --git a/files/en-us/web/http/headers/permissions-policy/index.md b/files/en-us/web/http/headers/permissions-policy/index.md
@@ -38,16 +38,22 @@ Permissions-Policy: <directive>=<allowlist>
 
   - : An allowlist is a list of origins that takes one or more of the following values contained in parentheses, separated by spaces:
 
-    - `*`: The feature will be allowed in this document, and all nested browsing contexts (`<iframe>`s) regardless of their origin.
-    - `()` (empty allowlist): The feature is disabled in top-level and nested browsing contexts. The equivalent for `<iframe>` `allow` attributes is `'none'`.
-    - `self`: The feature will be allowed in this document, and in all nested browsing contexts (`<iframe>`s) in the same origin only. The feature is not allowed in cross-origin documents in nested browsing contexts. `self` can be considered shorthand for `https://your-site.example.com`. The equivalent for `<iframe>` `allow` attributes is `self`.
-    - `src`: The feature will be allowed in this `<iframe>`, as long as the document loaded into it comes from the same origin as the URL in its {{HTMLElement('iframe','src','#Attributes')}} attribute. This value is only used in the `<iframe>` `allow` attribute, and is the _default_ `allowlist` value in `<iframe>`s.
-    - `"<origin>"`: The feature is allowed for specific origins (for example, `"https://a.example.com"`). Origins should be separated by spaces. Note that origins in `<iframe>` allow attributes are not quoted.
+    - `*` (wildcard)
+      - : The feature will be allowed in this document, and all nested browsing contexts (`<iframe>`s) regardless of their origin.
+    - `()` (empty allowlist)
+      - : The feature is disabled in top-level and nested browsing contexts. The equivalent for `<iframe>` `allow` attributes is `'none'`.
+    - `self`
+      - : The feature will be allowed in this document, and in all nested browsing contexts (`<iframe>`s) in the same origin only. The feature is not allowed in cross-origin documents in nested browsing contexts. `self` can be considered shorthand for `https://your-site.example.com`. The equivalent for `<iframe>` `allow` attributes is `self`.
+    - `src`
+      - : The feature will be allowed in this `<iframe>`, as long as the document loaded into it comes from the same origin as the URL in its {{HTMLElement('iframe','src','#Attributes')}} attribute. This value is only used in the `<iframe>` `allow` attribute, and is the _default_ `allowlist` value in `<iframe>`s.
+    - `"<origin>"`
+      - : The feature is allowed for specific origins (for example, `"https://a.example.com"`). Origins should be separated by spaces. Note that origins in `<iframe>` allow attributes are not quoted.
 
     The values `*` and `()` may only be used on their own, while `self` and `src` may be used in combination with one or more origins.
 
     > [!NOTE]
-    > Directives have a default allowlist, which is always one of `*`, `self`, or `none` for the `Permissions-Policy` HTTP header, and governs the default behavior if they are not explicitly listed in a policy. These are specified on the individual [directive reference pages](#directives). For `<iframe>` `allow` attributes, the default behavior is always `src`.
+    > Directives have a default allowlist, which is always one of `*`, `self`, or `none` for the `Permissions-Policy` HTTP header, and governs the default behavior if they are not explicitly listed in a policy.
+    > These are specified on the individual [directive reference pages](#directives). For `<iframe>` `allow` attributes, the default behavior is always `src`.
 
 Where supported, you can include wildcards in Permissions Policy origins. This means that instead of having to explicitly specify several different subdomains in an allowlist, you can specify them all in a single origin with a wildcard.
 

diff --git a/files/en-us/web/http/headers/proxy-authenticate/index.md b/files/en-us/web/http/headers/proxy-authenticate/index.md
@@ -25,25 +25,69 @@ It is sent in a {{HTTPStatus("407", "407 Proxy Authentication Required")}} respo
 
 ## Syntax
 
+A comma-separated list of one or more authentication challenges:
+
 ```http
-Proxy-Authenticate: <type> realm=<realm>
+Proxy-Authenticate: <challenge>
+```
+
+Where a `<challenge>` is comprised of an `<auth-scheme>`, followed by an optional `<token68>` or a comma-separated list of `<auth-params>`:
+
+```plain
+challenge = <auth-scheme> <auth-param>, …, <auth-paramN>
+challenge = <auth-scheme> <token68>
+```
+
+For example:
+
+```http
+Proxy-Authenticate: <auth-scheme>
+Proxy-Authenticate: <auth-scheme> token68
+Proxy-Authenticate: <auth-scheme> auth-param1=param-token1
+Proxy-Authenticate: <auth-scheme> auth-param1=param-token1, …, auth-paramN=param-tokenN
+```
+
+The presence of a `token68` or authentication parameters depends on the selected `<auth-scheme>`.
+For example, [Basic authentication](/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme) requires a `<realm>`, and allows for optional use of `charset` key, but does not support a `token68`:
+
+```http
+Proxy-Authenticate: Basic realm="Dev", charset="UTF-8"
 ```
 
 ## Directives
 
-- `<type>`
-  - : [Authentication type](/en-US/docs/Web/HTTP/Authentication#authentication_schemes).
-    A common type is ["Basic"](/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme).
-    IANA maintains a [list of authentication schemes](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).
-- `realm=<realm>`
-  - : A description of the protected area, the realm. If no realm is specified, clients often display a formatted host name instead.
+- `<auth-scheme>`
+  - : A case-insensitive token indicating the [Authentication scheme](/en-US/docs/Web/HTTP/Authentication#authentication_schemes) used.
+    Some of the more common types are [`Basic`](/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme), `Digest`, `Negotiate` and `AWS4-HMAC-SHA256`.
+    IANA maintains a [list of authentication schemes](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml), but there are other schemes offered by host services.
+- `<auth-param>` {{optional_inline}}
+  - : An authentication parameter whose format depends on the `<auth-scheme>`.
+    `<realm>` is described below as it's a common authentication parameter among many auth schemes.
+    - `<realm>` {{optional_inline}}
+      - : The string `realm` followed by `=` and a quoted string describing a protected area, for example `realm="staging environment"`.
+        A realm allows a server to partition the areas it protects (if supported by a scheme that allows such partitioning).
+        Some clients show this value to the user to inform them about which particular credentials are required — though most browsers stopped doing so to counter phishing.
+        The only reliably supported character set for this value is `us-ascii`.
+        If no realm is specified, clients often display a formatted hostname instead.
+- `<token68>` {{optional_inline}}
+  - : A token that may be useful for some schemes.
+    The token allows the 66 unreserved URI characters plus a few others.
+    It can hold a {{glossary("base64")}}, base64url, base32, or base16 (hex) encoding, with or without padding, but excluding whitespace.
+    The `token68` alternative to auth-param lists is supported for consistency with legacy authentication schemes.
+
+Generally, you will need to check the relevant specifications for the authentication parameters needed for each `<auth-scheme>`.
+
+> [!NOTE]
+> See {{HTTPHeader("WWW-Authenticate")}} for more details on authentication parameters.
 
 ## Examples
 
-```http
-Proxy-Authenticate: Basic
+### Proxy-Authenticate Basic auth
 
-Proxy-Authenticate: Basic realm="Access to the internal site"
+The following response indicates a Basic auth scheme is required with a realm:
+
+```http
+Proxy-Authenticate: Basic realm="Staging server"
 ```
 
 ## Specifications
@@ -56,7 +100,7 @@ Proxy-Authenticate: Basic realm="Access to the internal site"
 
 ## See also
 
+- {{HTTPHeader("WWW-Authenticate")}}
 - [HTTP authentication](/en-US/docs/Web/HTTP/Authentication)
 - {{HTTPHeader("Authorization")}}, {{HTTPHeader("Proxy-Authorization")}}
-- {{HTTPHeader("WWW-Authenticate")}}
 - {{HTTPStatus("401")}}, {{HTTPStatus("403")}}, {{HTTPStatus("407")}}
diff --git a/files/en-us/web/http/headers/proxy-authorization/index.md b/files/en-us/web/http/headers/proxy-authorization/index.md
@@ -31,10 +31,15 @@ Proxy-Authorization: <auth-scheme> <credentials>
 ## Directives
 
 - `<auth-scheme>`
-  - : Token indicating the [authentication scheme](/en-US/docs/Web/HTTP/Authentication#authentication_schemes), such as `Basic`, `Bearer`, etc.
-    The [IANA registry of Authentication schemes](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml) maintains a full list of available types.
+  - : A case-insensitive token indicating the [Authentication scheme](/en-US/docs/Web/HTTP/Authentication#authentication_schemes) used.
+    Some of the more common types are [`Basic`](/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme), `Digest`, `Negotiate` and `AWS4-HMAC-SHA256`.
+    IANA maintains a [list of authentication schemes](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml), but there are other schemes offered by host services.
 - `<credentials>`
   - : Credentials use for the authentication scheme.
+    Generally, you will need to check the relevant specifications for the format.
+
+> [!NOTE]
+> See {{HTTPHeader("Authorization")}} for more details.
 
 ## Examples
 

diff --git a/files/en-us/web/http/headers/range/index.md b/files/en-us/web/http/headers/range/index.md
@@ -13,7 +13,7 @@ If the server sends back ranges, it uses the {{HTTPStatus("206", "206 Partial Co
 If the ranges are invalid, the server returns the {{HTTPStatus("416", "416 Range Not Satisfiable")}} error.
 
 A server that doesn't support range requests may ignore the `Range` header and return the whole resource with a {{HTTPStatus("200")}} status code.
-Older browsers used a response header of {{HTTPHeader("Accept-Ranges", "Accept-Ranges: none")}} to disable features like 'pause' or 'resume' in download managers, but since ignoring the `Range` header has the same effect as `Accept-Ranges: none`, the header is rarely used in this way.
+Older browsers used a response header of {{HTTPHeader("Accept-Ranges", "Accept-Ranges: none")}} to disable features like 'pause' or 'resume' in download managers, but since a server ignoring the `Range` header has the same meaning as responding with `Accept-Ranges: none`, the header is rarely used in this way.
 
 Currently only [`bytes` units are registered](https://www.iana.org/assignments/http-parameters/http-parameters.xhtml#range-units) which are _offsets_ (zero-indexed & inclusive).
 If the requested data has a [content coding](/en-US/docs/Web/HTTP/Headers/Content-Encoding) applied, each byte range represents the encoded sequence of bytes, not the bytes that would be obtained after decoding.
@@ -38,7 +38,7 @@ The header is a [CORS-safelisted request header](/en-US/docs/Glossary/CORS-safel
 ```http
 Range: <unit>=<range-start>-
 Range: <unit>=<range-start>-<range-end>
-Range: <unit>=<range-start>-<range-end>, <range-start>-<range-end>, …
+Range: <unit>=<range-start>-<range-end>, …, <range-startN>-<range-endN>
 Range: <unit>=-<suffix-length>
 ```
 

diff --git a/files/en-us/web/http/headers/reporting-endpoints/index.md b/files/en-us/web/http/headers/reporting-endpoints/index.md
@@ -42,7 +42,7 @@ For more details on setting up CSP reporting, see the [Content Security Policy (
 
 ```http
 Reporting-Endpoints: <endpoint>
-Reporting-Endpoints: <endpoint>, <endpoint>
+Reporting-Endpoints: <endpoint>, …, <endpointN>
 ```
 
 - `<endpoint>`

diff --git a/files/en-us/web/http/headers/repr-digest/index.md b/files/en-us/web/http/headers/repr-digest/index.md
@@ -35,7 +35,7 @@ A {{HTTPHeader("Content-Digest")}} applies to the content of a specific message,
 Repr-Digest: <digest-algorithm>=<digest-value>
 
 // Multiple digest algorithms
-Repr-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>
+Repr-Digest: <digest-algorithm>=<digest-value>,…,<digest-algorithmN>=<digest-valueN>
 ```
 
 ## Directives