`Feature-Policy` HTTP Header Field

The Feature-Policy HTTP [response] header field is used to deliver a feature policy from a server to client. The header's value is represented by the following ABNF [[!RFC5234]]:

          Disable = 1#json-field-value
                    ; See Section 2 of [[HTTP-JFV]], and Section 2 of [[RFC7159]]
        

The policy is parsed as defined in , and the header’s value is interpreted as an array of JSON objects, as described in Section 4 of [[!HTTP-JFV]].

The policy MUST be delivered via an HTTP response header field to be processed by the client; the client MUST ignore any policy set via `meta` element's `http-equiv` attribute.

The feature policy needs to be set before the response is processed and before any subresource requests are initiated. Once active the policy also needs to apply for the lifetime of the document and is not allowed to be modified at runtime. Due to these requirements, `meta` element cannot be used to set the policy.

The following sections define the set of known members in each JSON object the header’s value defines. Future versions of this document may define additional such members, and user agents MUST ignore unknown members when parsing the header.

Process response policy

Given a [response] (response) and a [request] (request), this algorithm returns a feature policy.

1. Abort these steps if any of the following conditions are true:
   1. response’s [HTTPS state] is not "modern", and the [origin] of response’s [url] is not [potentially trustworthy].
   2. response’s [header list] does not contain a [header] whose [name] is "`Feature-Policy`".
2. Let header be the [value] of the [header] in response’s [header list] whose name is "`Feature-Policy`".
3. Let feature policy be the result of executing on header.

Parse disable features

Given a list, this algorithm returns a list of valid disable features, which may be empty.

1. Let valid-features be an empty list.
2. If list is null or empty, return valid-features.
3. For each item in list:
   1. Convert item to ASCII-lowercase.
   2. If item's string value is not one of the valid disable features, ignore item, and continue to the next item.
   3. Append item to valid-features.
4. Return valid-features.

`cookie`

Disables `document.cookie`: when present, the attribute's getter and setter will throw a SecurityError.

  Feature-Policy: {"disable":["cookie"]}

  document.cookie = "a=b;Secure;SameSite";
  alert(document.cookie);

`domain`

Disables `document.domain`: when present, the attribute's getter and setter will throw a SecurityError.

  Feature-Policy: {"disable":["domain"]}

  document.domain = "example.com";
  alert(document.domain);

`docwrite`

Disables `document.write`: when called, throws "`NotSupportedError`" `DOMException`.

  Feature-Policy: {"disable":["docwrite"]}

  document.write("...");

`geolocation`

Disables Geolocation API. [[!GEOLOCATION-API]]

`midi`

Disables Web MIDI API. [[!WEBMIDI]]

`notifications`

Disables Notification API. [[!NOTIFICATIONS]]

`push`

Disables Push API. [[!PUSH-API]]

`sync-script`

Disables synchronous `script` elements. When this policy is set, such scripts are ignored by the user agent.

  Feature-Policy: {"disable":["sync-script"]}

  <script src="/script1.js"></script>
  <script src="/script2.js" async></script>
  <script src="/script3.js" defer></script>
  <script>
    const scriptEl = document.createElement("script");
    scriptEl.src = "/script4.js";
    document.body.appendChild(scriptEl);
  </script>

`sync-xhr`

Disables synchronous `XMLHttpRequest` API: when [open() method](xhr-open) is called with async argument set to true, an `InvalidAccessError` except will be thrown.

  Feature-Policy: {"disable":["sync-xhr"]}

  var xhr = new XMLHttpRequest();
  xhr.open("GET", "/foo", true);

`webrtc`

Disables WebRTC. [[!WEBRTC]]

Integration with HTML

1. Document and WorkerGlobalScope objects have a Feature Policy List, which is either the empty set or a feature policy. This property is the empty set unless otherwise specified, and is populated via the algorithm.
2. The algorithm is called during the "Initialising a new Document object" and "Run a Worker" algorithms.

3. `document.cookie`'s getter and setter algorithms call into the algorithm to determine whether or not to throw, as follows:

   On getting:

   1. If the document is a cookie-averse Document object, return the empty string.
   2. If the document's origin is an opaque origin, throw a "`SecurityError`" `DOMException`.
   3. If the algorithm returns "`Disabled`" when executed upon "`cookie`" and the document's global object, throw a "`SecurityError`" `DOMException`.
   4. Otherwise the user agent must return the cookie-string for the document's URL for a "non-HTTP" API, decoded using UTF-8 decode without BOM.

   On setting:

   1. If the document is a cookie-averse Document object, then the user agent must skip the remaining substeps.
   2. If the document's origin is an opaque origin, throw a "`SecurityError`" `DOMException`.
   3. If the algorithm returns "`Disabled`" when executed upon "`cookie`" and the document's global object, throw a "`SecurityError`" `DOMException`.
   4. Otherwise, the user agent must act as it would when receiving a set-cookie-string for the document's URL via a "non-HTTP" API, consisting of the new value encoded as UTF-8.

4. `document.domain`'s getter and setter algorithms call into the algorithm to determine whether or not to throw, as follows:

   1. Add the following step after the current step 1 of the attribute's getter:
      1. If the algorithm returns "`Disabled`" when executed upon "`domain`" and the document's global object, throw a "`SecurityError`" `DOMException`.
   2. Add the following step after the current step 1 of the attribute's setter:
      1. If the algorithm returns "`Disabled`" when executed upon "`domain`" and the document's global object, throw a "`SecurityError`" `DOMException`.

5. [`document.write` method](docwrite-method) calls into the algorithm to determine whether or not to throw, as follows:

   1. Add the following step after the current step 1:
      1. If the algorithm returns "`Disabled`" when executed upon "`docwrite`" and the document's global object, throw a "`NotSupportedError`" `DOMException`.

6. The "[prepare a script]" algorithm calls into algorithm to determine whether or not to execute a script, as follows:

   1. Add the following step before the current step 10 (which is the first of several "disabled" checks):
      1. If the `script` element's "`non-blocking`" flag is unset, the `script`'s type is "`classic`", and the algorithm returns "`Disabled`" when executed upon the `script` element's node document's global object, then abort these steps at this point. The script is not executed.

Integration with XMLHttpRequest

The `open() method` calls into the algorithm to determine whether or not to throw, as follows:

1. Add the following step after the current step 3:
   1. If async is false and the algorithm returns "`Disabled`" when executed upon "`sync-xhr`" and the document's global object, throw "`InvalidAccessError`" exception.

Parse enable features

Given a list, this algorithm returns a list of valid enable features, which may be empty.

1. Let valid-features be an empty list.
2. If list is null or empty, return valid-features.
3. For each item in list:
   1. Convert item to ASCII-lowercase.
   2. TODO... should we merge/refactor this with disable parse?
   3. Append item to valid-features.
4. Return valid-features.