Feature Policy

4.1. Features

A feature controlled by this framework is an API or behaviour which can be enabled or disabled in a document or web worker by referring to it in a feature policy.

Features have a feature name keyword, which is a token used in policy directives, and a default allowlist, which defines whether the feature is available to top-level documents, and how access to that feature is inherited by cross-origin frames.

A user agent has a set of supported features, which is the set of features which it allows to be controlled through policies. User agents are not required to support every feature.

Features themselves are not themselves part of this framework. A non-normative list of currently-defined features is included as an appendix to this specification.

4.2. Policies

A Document or WorkerGlobalScope has a feature policy, which consists of:

• A set of inherited policies.
• A declared policy.

4.3. Inherited policies

Each document in a frame tree inherits a set of policies from its parent frame, or in the case of the top-level document, from the defined defaults for each feature. This inherited policy set determines the initial state (enabled or disabled) of each feature, and whether it can be controlled by a declared policy in the document.

In a Document in a top-level browsing context, or in a WorkerGlobalScope, the inherited feature set is based on defined defaults for each feature.

In a Document in a nested browsing context, the inherited feature set is based on the parent document’s feature policy, as well as any allow attributes defined on the browsing context container.

An inherited policy for a feature is a boolean associated with that feature in a Document or WorkerGlobalScope. It can take the value Enabled or Disabled.

An inherited policy set for a Document or WorkerGlobalScope is the set of inherited policies for each feature available in that scope.

4.4. Declared policies

A declared policy is a set of policy directives, which may be the empty set.

The declared policy is represented in HTTP headers and HTML attributes as a JSON string.

A Document or WorkerGlobalScope is considered feature-policy-aware if it has a declared policy delivered via a Feature-Policy HTTP header.

A Document or WorkerGlobalScope is which is not feature-policy-aware is considered feature-policy-oblivious.

4.5. Header policies

A header policy is a declared policy delivered via an HTTP header with the document, or in an HTML meta element in the document’s HEAD. These form the document’s feature policy’s declared policy.

4.6. Container policies

In addition to the header policy, each frame has a container policy, which is a policy directive, which may be empty. The container policy can set by attributes on the browsing context container.

The container policy for a frame influences the inherited policy of any document loaded into that frame. (See §8.8 Define an inherited policy for feature)

4.7. Policy directives

A policy directive is a dictionary, mapping feature names to corresponding allowlists of origins.

The following sections define the set of known feature names. Future versions of this document may define additional such names, as user agents ignore policy directives with unrecognized names when parsing the policy.

4.8. Allowlists

A feature policy allowlist is a set of origins. An allowlist may be empty, in which case it does not match any origin, or it may contain a list of origins, or it may match every origin. When defining an allowlist in a policy, the special origin "self" may be used, which refers to the origin of document which the policy is associated with.

An allowlist matches an origin o if it matches every origin, or if it contains an origin which is same origin-domain with o.

4.9. Default Allowlists

Every feature controlled by policy has a default allowlist, which is an allowlist. The default allowlist controls the origins which are allowed to access the feature when used in a top-level document with no declared policy, and also determines whether access to a feature is automatically delegated to child documents.

Features are currently defined to have one of these three default allowlists:

["*"]

The feature is allowed at the top level by default, and when allowed, is allowed by default to documents in child frames.

["self"]

The feature is allowed at the top level by default, and when allowed, is allowed by default to same-origin domain documents in child frames, but is disallowed by default in cross-origin documents in child frames.

[]

The feature is disallowed at the top level by default, and is also disallowed by default to documents in child frames.

5.1. JSON serialization

Declared Policies are represented in HTTP headers and in HTML attributes as JSON text [RFC7159].

origin is the ASCII serialization of an origin.

feature-name is a JSON string.

6.1. Feature-Policy HTTP Header Field

The Feature-Policy HTTP header field can be used in the response (server to client) to communicate the feature policy that should be enforced by the client.

The header’s value is the §5.1 JSON serialization of the elements of the declared policy:

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

When the user agent receives a Feature-Policy header field, it MUST process and enforce the serialized policy as described in §7.1 Integration with HTML.

6.2. The meta element

A Document may deliver a policy via one or more HTML meta elements whose http-equiv attributes are an ASCII case-insensitive match for the string "Feature-Policy". For example:

<meta http-equiv="Feature-Policy" content='{"webrtc": [], "geolocation": ["https://example.com"]}'>

The meta policy is processed as defined in §7.1.1 Process meta policy and modifications to the content attribute of a meta element after the element has been parsed MUST be ignored.

To ensure that the policy can be applied before any scripts are able to execute within the Document's browsing context, the following restrictions apply to meta policy:

• The elements containing the meta policy MUST be serialized completely within the first 1024 bytes of the document.
• The elements containing the meta policy MUST appear before any script or link elements.

6.3. The allow attribute of the iframe element

partial interface HTMLIFrameElement {
    [CEReactions, SameObject, PutForwards=value] readonly attribute DOMTokenList allow;
};

iframe elements have an "allow" attribute, which contains an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are names of features. Unrecognized values must be ignored.

When not empty, the "allow" attribute will result in adding an allowlist for each recognized feature to the frame’s container policy, when it is contructed.

The allowlist will contain a single origin, which is the origin of URL in the iframe’s src attribute.

6.4. Additional attributes to support legacy features

Some features controlled by Feature Policy have existing iframe attributes defined. This specification redefines these attributes to act as declared policies for the iframe element.

7.1. Integration with HTML

1. Document and WorkerGlobalScope objects have a Feature Policy, which is populated via the §8.7 Initialize global’s Feature Policy from response algorithm that is called during the "Initialising a new Document object" and "Run a Worker" algorithms.
2. Replace the existing step 12 of "Initialising a new Document object" with the following step:
   • Initialize the feature policy for the Document
3. A feature policy is enforced for a Document or WorkerGlobalScope by setting it as the Document or WorkerGlobalScope's Feature Policy.

4. The "allowed to use" algorithm calls into §8.9 Is feature enabled in global for origin?, as follows:

   1. Replace the current steps #3 and #4 with the following step:
      • If Document’s feature policy enables the feature indicated by allowattribute for the origin of Document, then return true.

8.1. Process response policy

Given a response (response) and global object (global), this algorithm returns a declared feature policy.

1. Abort these steps if the response’s header list does not contain a header whose name is "Feature-Policy".
2. Let header be the concatenation of the values of all header fields in response’s header list whose name is "Feature-Policy", separated by commas (according to [RFC7230, 3.2.2]).
3. Add a leading "[" U+005B character, and a trailing "]" U+005D character to header.
4. Let feature policy be the result of executing §8.2 Parse header from value and origin on header and global’s origin.
5. Return feature policy.

8.2. Parse header from value and origin

Given a string (value) and an origin (origin) this algorithm will return a declared feature policy.

1. Let policy be an empty list.
2. Let list be the result of parsing value with a JSON Parser. If value cannot be parsed, return policy.
3. Note: If value can be parsed, list must be a valid JSON Array.
4. For each element in list:
   1. If element is not a JSON object, then continue.
   2. Let directive be the result of executing §8.3 Parse policy directive from value and origin on element and origin
   3. Run §8.4 Merge directive with declared policy on directive and policy.
5. Return policy.

8.3. Parse policy directive from value and origin

Given a JSON object (value) and an origin (origin) this algorithm will return a policy directive.

1. Let directive be a new dictionary, mapping features to allowlists.
2. For each key and associated targetlist in value:
   1. If key is not equal to the name of any recognized feature, then continue.
   2. Let feature be the feature named by key.
   3. If targetlist is not an array, then continue.
   4. Let allowlist be a new allowlist.
   5. If targetlist contains the string "*", set allowlist to match every origin.
   6. Otherwise, for each element in targetlist:
      1. If element is an ASCII case-insensitive match for "self", let result be origin.
      2. Otherwise, let result be the result of executing the URL parser on element.
      3. If result is not failure:
         1. Let target be the origin of result.
         2. If target is not an opaque origin, append target to allowlist.
   7. Insert allowlist into directive as the value for the key feature.
3. Return directive

8.4. Merge directive with declared policy

Given a policy direcive (directive) and a declared policy (policy), this algorithm will modify policy to account for the new directive.

1. For each feature and associated allowlist in directive:
   1. If policy does not contain an allowlist for feature, then add allowlist to policy as the allowlist for feature.

8.5. Process feature policy attributes

Given an element element, this algorithm returns a declared feature policy, which may be empty.

1. Let policy be a new policy directive.
2. Let valid-features be the result of running Parse allow attribute on the value of element’s allow attribute.
3. For each feature in valid-features:
   1. If policy does not contain an allowlist for feature:
      1. Construct a new declaration for feature, whose allowlist is origin.
      2. Add declaration to policy.
4. If element is an iframe element:
   1. If element’s allowfullscreen attribute is specified, and policy does not contain an allowlist for fullscreen,
      1. Construct a new declaration for fullscreen, whose allowlist matches all origins.
      2. Add declaration to policy.
   2. If element’s allowpaymentrequest attribute is specified, and policy does not contain an allowlist for payment,
      1. Construct a new declaration for payment, whose allowlist matches all origins.
      2. Add declaration to policy.
5. Return policy.

8.6. Parse allow attribute

Given a list, this algorithm returns a list of feature name keywords, 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 matches a defined feature name which is not present in valid-features,
      1. Append item to valid-features.
4. Return valid-features.

8.7. Initialize global’s Feature Policy from response

Given a response (response) and a global object (global), this algorithm populates global’s Feature Policy

1. Let inherited policies be a new ordered map.
2. Let declared policies be a new ordered map.
3. For each feature supported,
   1. Let isInherited be the result of running §8.8 Define an inherited policy for feature on feature and global.
   2. Set inherited policies[feature] to isInherited.
4. Let d be the result of executing §8.1 Process response policy on response and global.
5. For each directive in d:
   1. If inherited policies[ in inherited policies for directive’s feature is true, then append d to declared policies
6. Let policy be a new feature policy, with inherited policy set inherited policies and declared policy set declared policies.
7. Enforce the policy policy.

8.8. Define an inherited policy for feature

Given a string (feature) and a browsing context (context), this algorithm returns the inherited policy for that feature.

1. If context is a nested browsing context:
   1. Let parent be context’s parent browsing context’s active document.
   2. Let origin be parent’s origin
   3. Let container policy be the result of running §8.5 Process feature policy attributes on context’s browsing context container.
   4. If feature is a key in container policy:
      1. If the allowlist for feature in container policy matches origin, and parent’s inherited policy for feature is Enabled, return Enabled.
      2. Otherwise return Disabled.
   5. Otherwise, if feature is allowed by parent’s feature policy for origin, return Enabled.
   6. Otherwise, return Disabled.
2. Otherwise, return Enabled.

8.9. Is feature enabled in global for origin?

Given a string (feature) and a global object (global), and an origin (origin), this algorithm returns "Disabled" if feature should be considered disabled, and "Enabled" otherwise.

1. Let policy be global’s Feature Policy
2. If policy’s inherited policy for feature is Disabled, return "Disabled".
3. If feature is present in policy’s declared policy:
   1. If the allowlist for feature in policy’s declared policy matches origin, then return "Enabled".
   2. Otherwise return "Disabled".
4. If feature’s default allowlist is ["*"], return "Enabled".
5. If feature’s default allowlist is ["self"], and origin is same origin-domain with global’s active document’s origin, return "Enabled".
6. Return "Disabled".