diff --git a/index.html b/index.html index 280e17d0..028fd0ec 100644 --- a/index.html +++ b/index.html @@ -66,6 +66,22 @@ } }; +
@@ -355,107 +371,303 @@

Parse policy from value and global

- -
-

Disable Policy

-

The disable policy allows a developer to turn off certain - features for a Document or Worker.

-

Processing

+

Features

+

This section defines features and their effect when applied + via a directive as part of a feature policy.

+

The following table summarizes features defined by this + specification, by their corresponding keywords. This table is + non-normative; the actual definitions are given in the following + sections.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature + Enable policy + + Disable policy + Brief description
top-level contextnested context
+ cookie + `\*``\*``null`Controls access to `document.cookie`.
+ domain + `\*``\*``null`Controls access to `document.domain`.
+ docwrite + `\*``\*``null`Controls access to `document.write`, `document.writeln`.
+ ... + ............
+ geolocation + `self``null``null`Controls access to [Geolocation interface].
+ midi + `self``null``null`Controls access to [requestMIDIAccess method].
+ notifications + `self``null``null`Controls access to [Notification interface].
+ payment + `self``null``null`Controls access to [PaymentRequest interface].
+ push + `self``null``null`Controls access to [PushManager interface].
+ sync-script + `\*``\*``null`Controls use of synchronous `script` elements.
+ sync-xhr + `\*``\*``null`Controls access to synchronous `XMLHttpRequest` API.
+ usermedia + `self``null``null`Controls access to [NavigatorUserMedia interface].
+ vibrate + `self``null``null`Controls access to [vibrate method].
+ webrtc + `\*``\*``null`Controls access to [RTCPeerConnection interface].
-

Parse disable features

-

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

+

`cookie`

+ 
+partial interface Document {
+  [Feature=cookie] attribute USVString cookie;
+};
+

The cookie keyword controls whether the [cookie attribute] is + [exposed] for [current global object].

    -
  1. Let valid-features be an empty list.
    2. -
  2. If list is null or empty, return - valid-features.
    3. -
  3. For each item in list: -
      -
    1. Convert item to ASCII-lowercase.
      2. -
    2. If item's string value is not one of the valid - disable features, ignore item, and continue to the - next item. -
      3. -
    3. Append item to valid-features.
      4. -
    +
  4. The default enable policy is `\*` for [top-level browsing + context], and `\*` for [nested browsing context]. +
    5. +
  5. The default disable policy is `null`.
    6. -
  6. Return valid-features.
-
-
-

Features

-

This section defines the list of valid disable features and - their effect when applied via a directive as part of a feature - policy.

-
-

`cookie`

-

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

-
-

Given the following header:

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

The following JavaScript code will throw a `SecurityError` - exception:

- 
-  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.

-
-

Given the following header:

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

The following JavaScript code will throw a `SecurityError` - exception:

- 
-  document.domain = "example.com";
-  alert(document.domain);
-
+ 
+partial interface Document {
+  [Feature=domain] attribute USVString domain;
+};
+

The domain keyword controls whether the [domain attribute] is + [exposed] for [current global object].

+
    +
  1. The default enable policy is `\*` for [top-level browsing + context], and `\*` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`docwrite`

-

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

-
-

Given the following header:

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

The following JavaScript code will throw a `NotSupportedError` - exception:

- 
-  document.write("...");
-
+ 
+partial interface Document {
+  [CEReactions, Feature=docwrite] void write(DOMString... text);
+  [CEReactions, Feature=docwrite] void writeln(DOMString... text);
+};
+

The docwrite keyword controls whether the [document.write] + and [document.writeln] methods are [exposed] for [current global + object].

+
    +
  1. The default enable policy is `\*` for [top-level browsing + context], and `\*` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`geolocation`

-

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

+ 
+partial interface Navigator {
+  [Feature=geolocation] readonly attribute Geolocation geolocation;
+};
+

The geolocation keyword controls whether the [Geolocation + interface] ([[!GEOLOCATION-API]]) is [exposed] for [current global + object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`midi`

-

Disables Web MIDI API. [[!WEBMIDI]]

+ 
+partial interface Navigator {
+  [Feature=midi] Promise<MIDIAccess> requestMIDIAccess (optional MIDIOptions options);
+};
+

The midi keyword controls whether the [requestMIDIAccess + method] ([[!WEBMIDI]]) is [exposed] for [current global object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`notifications`

-

Disables Notification API. [[!NOTIFICATIONS]]

+ 
+[Constructor(DOMString title, optional NotificationOptions options),
+Feature=notifications]
+interface Notification : EventTarget {};
+

The notifications keyword controls whether the [Notification + interface] ([[!NOTIFICATIONS]]) is [exposed] for [current global + object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +
+
+
+

`payment`

+ 
+[Constructor(sequence<PaymentMethodData> methodData, PaymentDetails details, optional PaymentOptions options),
+ SecureContext, Feature=payment]
+interface PaymentRequest : EventTarget {};
+

The payment keyword controls whether the [PaymentRequest + interface] ([[!PAYMENT-REQUEST]]) is [exposed] for [current global + object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`push`

-

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

+ 
+partial interface ServiceWorkerRegistration {
+  [Feature=push] readonly attribute PushManager pushManager;
+};
+
+[Feature=push]
+interface PushManager {};
+
+

The push keyword controls whether the [PushManager interface] + ([[!PUSH-API]]) is [exposed] for [current global object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +

`sync-script`

-

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

+

The sync-script keyword controls use of synchronous `script` + elements, as defined in . When + this feature is disabled, such scripts are ignored by the user + agent.

Given the following header:

@@ -478,9 +690,11 @@ 
`sync-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.

+

The sync-xhr keyword controls use of synchronous + `XMLHttpRequest` API, as defined in . When [open() method](xhr-open) + is called with async argument set to false, an + `InvalidAccessError` except will be thrown.

Given the following header:

@@ -490,12 +704,86 @@ 
`sync-xhr`

           exception:

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

+  xhr.open("GET", "/foo", false);
+
+

`usermedia`

+ 
+[Exposed=Window, NoInterfaceObject, Feature=usermedia]
+interface NavigatorUserMedia {
+    [SameObject] readonly attribute MediaDevices mediaDevices;
+};
+

The usermedia keyword controls whether the + [NavigatorUserMedia interface] ([[!MEDIACAPTURE-API]]) is [exposed] for + [current global object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +
+
+
+

`vibrate`

+ 
+partial interface Navigator {
+  [Feature=vibrate] boolean vibrate(VibratePattern pattern);
+};
+

The vibrate keyword controls whether the [vibrate method] + ([[!VIBRATION]]) is [exposed] for [current global object].

+
    +
  1. The default enable policy is `self` for [top-level + browsing context], and `null` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +
+

`webrtc`

-

Disables WebRTC. [[!WEBRTC]]

+ 
+[Constructor(optional RTCConfiguration configuration), Feature=webrtc]
+interface RTCPeerConnection : EventTarget {};
+

The webrtc keyword controls whether the [RTCPeerConnection + interface] ([[!WEBRTC]]) is [exposed] for [current global object].

+
    +
  1. The default enable policy is `\*` for [top-level browsing + context], and `\*` for [nested browsing context]. +
    2. +
  2. The default disable policy is `null`. +
    3. +
+
+
+
+
+

Disable Policy

+

The disable policy allows a developer to turn off certain + features for a Document or Worker.

+
+

Processing

+
+

Parse disable features

+

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

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

Enable Policy

Processing

Parse enable features

-

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

+

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

  1. Let valid-features be an empty list.
  2. If list is null or empty, return @@ -554,86 +842,6 @@

    Integration with HTML

    "#process-meta-policy">processing of the meta element’s http-equiv.
    3. -
  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. -
    2. If the document's origin is an opaque origin, throw a - "`SecurityError`" `DOMException`.
      3. -
    3. If the algorithm returns - "`Disabled`" when executed upon "`cookie`" and the document's - global object, throw a "`SecurityError`" `DOMException`. -
      4. -
    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.
      5. -
    -

    On setting:

    -
      -
    1. If the document is a cookie-averse Document object, then the - user agent must skip the remaining substeps.
      2. -
    2. If the document's origin is an opaque origin, throw a - "`SecurityError`" `DOMException`.
      3. -
    3. If the algorithm returns - "`Disabled`" when executed upon "`cookie`" and the document's - global object, throw a "`SecurityError`" `DOMException`. -
      4. -
    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.
      5. -
    -
    -
    4. -
  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. -
      -
      2. -
    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`. -
        2. -
      -
      3. -
    -
    5. -
  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`. -
        2. -
      -
      2. -
    -

  6. The "[prepare a script]" algorithm calls into algorithm to determine whether or not to @@ -797,6 +1005,52 @@

    Integration with XMLHttpRequest

+
+

Integration with WebIDL

+

This section defines an extended attribute whose presence affects only + the ECMAScript binding.

+
+

[Feature]

+

If the [Feature] [extended attribute] appears on an + interface, partial interface, or an individual interface member, it + indicates that the interface or interface member is subject to + feature policy associated with the ECMAScript global + environment's global object.

+

The [Feature] [extended attribute] must [take an identifier], + which must be a [global name].

+

Whether a construct that the [Feature] [extended attribute] + can be specified on is enabled by feature policy for global + is defined as follows:

+
    +
  1. If the [Feature] [extended attribute] is specified on the + construct, then it is enabled by feature policy for global if + the "is feature disabled for + global?" algorithm returns "`Enabled`" when executed upon the + extended attribute's argument and the ECMAScript global environment's + global object. +
    2. +
  2. Otherwise, if the [Feature] [extended attribute] does not + appear on a construct, then it is enabled by feature policy for + global, depending on the type of construct: +
      +
    1. **Interface**: the interface or dictionary is implicity + "`Enabled`" by feature policy.
      2. +
    2. **Partial interface**: the partial interface is enabled by + feature policy for global if and only if the original + interface definition is. +
      3. +
    3. **Interface member**: the interface member is enabled by + feature policy for global if and only if the interface or + partial interface the member is declared on is. +
      4. +
    +
    3. +
+

Whether a construct is enabled by feature policy for + global influences whether it is [exposed] in a given ECMAScript + global environment.

+
+

IANA Considerations

@@ -861,3 +1115,21 @@

Privacy and Security

[http-equiv]: https://html.spec.whatwg.org/#attr-meta-http-equiv [meta-content]: https://html.spec.whatwg.org/#attr-meta-content [pragma directives]: https://html.spec.whatwg.org/#attr-meta-http-equiv-content-security-policy +[extended attribute]: https://heycam.github.io/webidl/#dfn-extended-attribute +[take an identifier]: https://heycam.github.io/webidl/#dfn-xattr-identifier +[global name]: https://heycam.github.io/webidl/#dfn-global-name +[exposed]: https://heycam.github.io/webidl/#dfn-exposed +[cookie attribute]: https://html.spec.whatwg.org/#dom-document-cookie +[domain attribute]: https://html.spec.whatwg.org/#dom-document-domain +[top-level browsing context]: https://html.spec.whatwg.org/#top-level-browsing-context +[nested browsing context]: https://html.spec.whatwg.org/#nested-browsing-context +[document.write]: https://html.spec.whatwg.org/#dom-document-write +[document.writeln]: https://html.spec.whatwg.org/#dom-document-writeln +[Geolocation interface]: https://www.w3.org/TR/geolocation-API/#geolocation_interface +[NavigatorUserMedia interface]: https://w3c.github.io/mediacapture-main/#navigatorusermedia +[RTCPeerConnection interface]: http://w3c.github.io/webrtc-pc/#rtcpeerconnection-interface +[Notification interface]: https://www.w3.org/TR/notifications/#notification +[PaymentRequest interface]: https://www.w3.org/TR/payment-request/#paymentrequest-interface +[PushManager interface]: https://w3c.github.io/push-api/#idl-def-PushManager +[requestMIDIAccess method]: http://webaudio.github.io/web-midi-api/#requestMIDIAccess +[vibrate method]: https://w3c.github.io/vibration/#idl-def-navigator-vibrate(vibratepattern)