Permissions Policy

4.1. Policy-controlled Features

A policy-controlled feature is an API or behaviour which can be enabled or disabled in a document by referring to it in a permissions policy.

Policy-controlled features are identified by tokens, which are character strings used in policy directives.

Each policy-controlled feature has a default allowlist, which defines whether that feature is available in documents in top-level traversables, and how access to that feature is inherited in child navigables.

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.

4.2. Policies

A declared policy is a struct with the following items:

declarations

an ordered map from features to allowlists

reporting configuration

an ordered map from features to strings

A permissions policy is a struct with the following items:

inherited policy

an ordered map from features to "Enabled" or "Disabled"

declared policy

a declared policy

An empty permissions policy is a permissions policy that has an inherited policy which contains "Enabled" for every supported feature, a declared policy whose declarations and reporting configuration are both empty ordered maps.

4.3. Inherited policies

The inherited policy for a feature feature is the value in the inherited policy whose key is feature. After a permissions policy has been initialized, its inherited policy will contain a value for each supported feature.

4.4. Header policies

A header policy is a list of policy directives delivered via an HTTP header with a document. This forms the document’s permissions policy’s declared policy.

4.5. Container policies

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

The container policy for a child navigable influences the inherited policy of any Document loaded into that navigable. (See § 9.7 Define an inherited policy for feature in container at origin).

4.6. Policy directives

A policy directive is an ordered map, mapping policy-controlled features to corresponding allowlists of origins.

A policy directive is represented in HTTP headers as the serialization of an sf-dictionary structure, and in HTML attributes as its ASCII serialization.

4.7. Allowlists

A permissions policy allowlist is conceptually a set of origins. An allowlist may be either:

• The special value *, which represents every origin, or
• A struct containing:
  • expressions, which is an ordered set of permissions-source-expression
  • self-origin, which is an origin or null
  • src-origin, which is an origin or null

4.8. Default Allowlists

Every policy-controlled feature has a default allowlist. The default allowlist determines whether the feature is allowed in a Document with no declared policy in a top-level traversable, and also whether access to the feature is automatically delegated to documents in child navigables.

The default allowlist for a feature is one of these values:

*

The feature is allowed in Documents in top-level traversables by default, as well as those in all child navigables. It can be disallowed in child navigables by explicitly supplying a container policy on the navigable container that overrides this default (or in any navigable, by delivering the Document with a suitable Permissions-Policy header).

'self'

The feature is allowed in documents in top-level traversables by default, as well as those in child navigables whose document is same origin with its parent’s document, when allowed in that Document. It is disallowed by default in child navigables whose document is cross-origin with its parent’s document.

5.1. HTML attribute serialization

Policy Directives in HTML attributes are represented as their ASCII serialization, with the following ABNF:

serialized-permissions-policy = serialized-policy-directive *(";" serialized-policy-directive)
serialized-policy-directive = feature-identifier RWS allow-list
feature-identifier = 1*( ALPHA / DIGIT / "-")
allow-list = allow-list-value *(RWS allow-list-value)
allow-list-value = permissions-source-expression / "*" / "'self'" / "'src'" / "'none'"
permissions-source-expression = scheme-source / host-source

5.2. Structured header serialization

In this representation, a policy directive is represented by a Dictionary.

Each Dictionary Member associates a feature with an allowlist. The Member Names must be Tokens. If a token does not name one of the user agent’s supported features, then the Dictionary Member will be ignored by the processing steps.

The Member Values represent allowlists, and must be one of:

• a String containing the ASCII permissions-source-expression

• the Token *

• the Token self

• an Inner List containing zero or more of the above items.

Member Values may have a Parameter named "report-to", whose value must be a String. Any other parameters will be ignored.

Any other items inside of an Inner List will be ignored by the processing steps, and the Member Value will be processed as if they were not present. Member Values of any other form will cause the entire Dictionary Member to be ignored by the processing steps.

6.1. `Permissions-Policy` HTTP Header Field

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

`Permissions-Policy` is a structured header. Its value must be a dictionary. It’s ABNF is:

PermissionsPolicy = sf-dictionary

The semantics of the dictionary are defined in § 5.2 Structured header serialization.

The processing steps are defined in § 9.2 Construct policy from dictionary and origin.

6.2. The allow attribute of the iframe element

iframe elements have an allow attribute, which contains an ASCII-serialized policy directive.

The allowlist for the features named in the attribute may be empty; in that case, the default value for the allowlist is 'src', which represents the origin of the URL in the iframe’s src attribute.

When not empty, the allow attribute will result in adding an allowlist for each recognized feature to the iframe element’s content navigable’s container policy, when it is constructed.

6.3. Additional attributes to support legacy features

Some features controlled by Permissions Policy have existing iframe attributes defined. This specification redefines these attributes to influence the iframe’s content navigable’s container policy.

7.2. The permissionsPolicy object

[Exposed=Window]
interface PermissionsPolicy {
  boolean allowsFeature(DOMString feature, optional DOMString origin);
  sequence<DOMString> features();
  sequence<DOMString> allowedFeatures();
  sequence<DOMString> getAllowlistForFeature(DOMString feature);
};

partial interface Document {
    [SameObject] readonly attribute PermissionsPolicy permissionsPolicy;
};

partial interface HTMLIFrameElement {
    [SameObject] readonly attribute PermissionsPolicy permissionsPolicy;
};

A PermissionsPolicy object has an associated node, which is a Node. The associated node is set when the PermissionsPolicy object is created.

A PermissionsPolicy object has a default origin, which is an origin, whose value depends on the state of the PermissionsPolicy object’s associated node:

• If the PermissionsPolicy object’s associated node is a Document, then its default origin is the Document’s origin.

• If the PermissionsPolicy object’s associated node is an Element, then its default origin is the Element’s declared origin.

Each Document has a policy object, which is a PermissionsPolicy instance whose associated node is that Document.

A Document’s permissionsPolicy IDL attribute, on getting, must return the Document’s policy object.

Each iframe element has a policy object, which is a PermissionsPolicy instance whose associated node is that element.

An iframe’s permissionsPolicy IDL attribute, on getting, must return the iframe’s policy object.

The allowsFeature(feature, origin) method must run the following steps:

1. If origin is omitted, set origin to this PermissionsPolicy object’s default origin.

2. Let policy be the observable policy for this PermissionsPolicy object’s associated node.

3. If feature is allowed by policy for origin, return true.

4. Otherwise, return false.

The features() method must run the following steps:

1. Set result to an empty ordered set.

2. For each supported feature feature:

   1. Append feature to result.

3. return result

The allowedFeatures() method must run the following steps:

1. Set result to an empty ordered set.

2. Let origin be this PermissionsPolicy object’s default origin.

3. Let policy be the observable policy for this PermissionsPolicy object’s associated node.

4. For each supported feature feature:

   1. If feature is allowed by policy for origin, append feature to result.

5. return result

The getAllowlistForFeature(feature) method must run the following steps:

1. Set result to an empty list.

2. Let origin be this PermissionsPolicy object’s default origin.

3. Let policy be the observable policy for this PermissionsPolicy object’s associated node.

4. If feature is not allowed in policy for origin, return result

5. Let allowlist be policy’s declared policy[feature]'s declarations.

6. If allowlist is the special value *:

   1. Append "*" to result

   2. Return result.

7. If the allowlist’s self-origin is not null, append the serialization of it to result.

8. If the allowlist’s src-origin is not null, append the serialization of it to result.

9. Otherwise, for each permissions-source-expression item in allowlist’s expressions:

   1. Append item to result

10. Return result.

The observable policy for any Node is a permissions policy, which contains the information about the policy in the navigable represented by that Node which is visible from the current document.

To get the observable policy for a Document document, return document’s permissions policy.

To get the observable policy for an Element node, run the following steps:

1. Let inherited policy be an empty ordered map.

2. For each supported feature feature:

   1. Let isInherited be the result of running Define an inherited policy for feature in container at origin on feature, node and node’s declared origin.

   2. Set inherited policy[feature] to isInherited.

3. Return a new permissions policy with inherited policy inherited policy, declared policy a struct with both declarations and reporting configuration new ordered maps.

To get the declared origin for an Element node, run the following steps:

1. If node’s node document’s sandboxed origin browsing context flag is set, then return a new opaque origin.

2. If node’s sandbox attribute is set, and does not contain the allow-same-origin keyword, then return a new opaque origin.

3. If node’s srcdoc attribute is set, then return node’s node document’s origin.

4. If node’s src attribute is set:

   1. Let url be the result of parsing node’s src attribute, relative to node’s node document.

   2. If url is not failure, return url’s origin.

5. Return node’s node document’s origin.

The declared origin concept is intended to represent the origin of the document which the embedding page intends to load into a frame. This means, for instance, that if the browser does not support the sandbox or srcdoc attributes, it should not take those attributes into account when computing the declared origin.