From 5190a3d9dfc374a7408bfdad7c6d6abd0e2809e4 Mon Sep 17 00:00:00 2001 From: Mike Wasserman Date: Thu, 13 Jun 2024 22:19:12 +0000 Subject: [PATCH] Update features.md for `window-management` nee `window-placement` (#534) SHA: 7a2bc78e99c7cf3f268c9932ca02e3024238049d Reason: push, by clelland Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- index.html | 2954 +++++++++++++++++++++++++++------------------------- 1 file changed, 1555 insertions(+), 1399 deletions(-) diff --git a/index.html b/index.html index 3946bd0f..911ce83d 100644 --- a/index.html +++ b/index.html @@ -5,10 +5,9 @@ Permissions Policy - - + - + - - - - + - - - - - + - - +

Permissions Policy

-

Editor’s Draft,

+

Editor’s Draft,

More details about this document
@@ -845,7 +915,6 @@

Permissions Policy

Latest published version:
https://www.w3.org/TR/permissions-policy/
Feedback: -
public-webappsec@w3.org with subject line “[permissions-policy] … message topic …” (archives)
GitHub
Inline In Spec
Editor: @@ -854,7 +923,7 @@

Permissions Policy

-

Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

+

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

@@ -880,7 +949,7 @@

public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

-

This document is governed by the 2 November 2021 W3C Process Document.

+

This document is governed by the 03 November 2023 W3C Process Document.

@@ -896,12 +965,11 @@

Table of Contents

  • 4.1 Policy-controlled Features
  • 4.2 Policies
  • 4.3 Inherited policies -
  • 4.4 Declared policies -
  • 4.5 Header policies -
  • 4.6 Container policies -
  • 4.7 Policy directives -
  • 4.8 Allowlists -
  • 4.9 Default Allowlists +
  • 4.4 Header policies +
  • 4.5 Container policies +
  • 4.6 Policy directives +
  • 4.7 Allowlists +
  • 4.8 Default Allowlists
  • 5 Permissions Policy Serialization @@ -912,8 +980,8 @@

    Table of Contents

  • 6 Delivery
      -
    1. 6.1 Permissions-Policy HTTP Header - Field +
    2. 6.1 `Permissions-Policy` HTTP + Header Field
    3. 6.2 The allow attribute of the iframe element
    4. 6.3 Additional attributes to support legacy @@ -933,7 +1001,12 @@

      Table of Contents

  • 7.2 The permissionsPolicy object -
  • 8 Reporting +
  • + 8 Reporting +
      +
    1. 8.1 `Permissions-Policy-Report-Only` + HTTP Header Field +
  • 9 Algorithms
      @@ -944,22 +1017,30 @@

      Table of Contents

    1. 9.5 Create a Permissions Policy for a navigable
    2. 9.6 Create a Permissions Policy for a navigable from response
    3. 9.7 Define an inherited policy for feature in container at origin -
    4. 9.8 Is feature enabled in document for origin? -
    5. 9.9 Generate report for violation of permissions policy on settings -
    6. 9.10 Should request be allowed to use feature? +
    7. 9.8 Get feature value for origin +
    8. 9.9 Check permissions policy +
    9. 9.10 Is feature enabled in document for origin? +
    10. 9.11 Get the reporting endpoint for a feature +
    11. 9.12 Generate report for violation of permissions policy on settings +
    12. 9.13 Should request be allowed to use feature? +
    +
  • + 10 Changes to other specifications +
      +
    1. 10.1 Changes to the HTML specification
    -
  • 10 IANA Considerations +
  • 11 IANA Considerations
  • - 11 Privacy and Security + 12 Privacy and Security
      -
    1. 11.1 Exposure of cross-origin behavior -
    2. 11.2 Unanticipated behavior changes -
    3. 11.3 Exposure of embedding policy +
    4. 12.1 Exposure of cross-origin behavior +
    5. 12.2 Unanticipated behavior changes +
    6. 12.3 Exposure of embedding policy
  • - 12 Change log + 13 Change log
      -
    1. 12.1 Changes since FPWD +
    2. 13.1 Changes since FPWD
  • Conformance @@ -1051,6 +1132,44 @@

    2. those frames hosting content from http://example.com or SecureCorp itself will actually be granted the ability to use that API.

    +
    + +

    SecureCorp Inc. restructured its domains and now needs to needs to delegate + use of the Geolocation API to its origin ("https://example.com") + as well as three subdomains ("https://geo.example.com", + "https://geo2.example.com", and "https://new.geo2.example.com"). + This needs to be accomplished while still disabling the use of the Geolocation API + within all other browsing contexts. It can do this by delivering the following HTTP response header:

    +
    Permissions-Policy: geolocation=(self "https://example.com" "https://geo.example.com" "https://geo2.example.com" "https://new.geo2.example.com")
+
    +

    This works, but if SecureCorp Inc. feels safe delegating to any subdomains on + "https://example.com" the HTTP response header could instead be:

    +
    Permissions-Policy: geolocation=(self "https://example.com" "https://*.example.com")
+
    +

    Not only would the above header permit "https://geo.example.com", + "https://geo2.example.com", and "https://new.geo2.example.com" + to use the Geolocation API, but any other subdomains of "https://example.com" + could use it too. Note that "https://example.com" is not covered by the allowlist entry "https://*.example.com" and must also be added.

    +
    +
    + +

    SecureCorp Inc. restructured its services and now needs to needs to delegate + use of the Geolocation API to its origin ("https://example.com") + as well as three non-default ports ("https://example.com:444", + "https://example.com:445", and "https://example.com:446"). + This needs to be accomplished while still disabling the use of the Geolocation API + within all other browsing contexts. It can do this by delivering the following HTTP response header:

    +
    Permissions-Policy: geolocation=(self "https://example.com" "https://example.com:444" "https://example.com:445" "https://example.com:446")
+
    +

    This works, but if SecureCorp Inc. feels safe delegating to any ports on + "https://example.com" the HTTP response header could instead be:

    +
    Permissions-Policy: geolocation=(self "https://example.com:*")
+
    +

    Not only would the above header permit "https://example.com:444", + "https://example.com:444", and "https://example.com:445" + to use the Geolocation API, but any other ports on "https://example.com" + could use it too.

    +
    @@ -1110,109 +1229,136 @@

    4

    4.2. Policies

    -

    A permissions policy is a struct with the following items:

    - +

    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, and a declared - policy which is an empty map.

    + 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

    -

    An inherited - policy is an ordered map from features to either - "Enabled" or "Disabled".

    -

    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.

    +

    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.

    -

    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 policy-controlled feature. This inherited policy 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 traversable, the inherited +

    Upon both creation and navigation, Each Document inherits a set of + policies from its parent frame, or in the case of the Document in a top-level traversable, from the defined defaults for each policy-controlled feature. This inherited policy 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 traversable, the inherited policy is based on defined defaults for each feature.

    -

    In a Document in a child navigable, the inherited policy is based +

    In a Document in a child navigable, the inherited policy is based on the parent document’s permissions policy, as well as the child navigable's container policy.

    -

    4.4. Declared policies

    -

    A declared - policy is an ordered map from features to allowlists.

    -
    -
    -

    4.5. 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.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.6. Container policies

    +

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

    +

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

    Currently, the container policy cannot be set directly, but is - indirectly set by iframe "allowfullscreen", - and "allow" attributes. - Future revisions to this spec may introduce a mechanism to explicitly - declare the full container policy.
    + indirectly set by the iframe allowfullscreen, and allow attributes. Future revisions to this spec may introduce a + mechanism to explicitly declare the full container policy.
    -

    4.7. Policy directives

    +

    4.6. Policy directives

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

    + 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 sh-dictionary structure, and in and HTML + serialization of an sf-dictionary structure, and in and HTML attributes as its ASCII serialization.

    -

    4.8. Allowlists

    -

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

    +

    4.7. Allowlists

    +

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

    The keywords 'self', 'src', and 'none' can appear in the text representation of allowlists in headers and attribute strings. These keywords are always interpreted in context during parsing, and only the origins which they refer to are stored in the allowlist. The keywords themselves are not part of the allowlist.
    -

    To determine whether an allowlist matches an origin origin, run these steps:

    -
      -
    1. If the allowlist is the special value *, - then return true. -
    2. - Otherwise, for each item in the allowlist: -
        -
      1. If item is same origin-domain with origin, then return true. -
      -
    3. return false. -
    +
    +

    To determine whether an allowlist matches an origin origin, run these steps:

    +
      +
    1. +

      If the allowlist is the special value *, + then return true.

      +
    +

    Note: We are not using the CSP variant of wildcard matching as it requires the HTTPS scheme.

    +
      +
    1. +

      If the allowlist’s self-origin is not null and it is same origin-domain with origin, then return true.

      +
    2. +

      If the allowlist’s src-origin is not null and it is same origin-domain with origin, then return true.

      +
    3. +

      If origin is an opaque origin, return false.

      +
    4. +

      Let url be the result of calling the url parser on the serialization of origin.

      +
    5. +

      For each permissions-source-expression item in the allowlist’s expressions:

      +
        +
      1. +

        If the result of running Does url match expression in origin with redirect count? on url, item, origin, and 0 is true then return true.

        +
      +
    6. +

      Return false.

      +
    +
    -

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

    +

    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, and when allowed, is allowed by default to documents in child - navigables. +
    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, and when allowed, is allowed by default to same-origin domain - documents in child navigables, but is disallowed by default in - cross-origin documents in child navigables. +
    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.
    @@ -1226,29 +1372,26 @@

    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 = serialized-origin / "*" / "'self'" / "'src'" / "'none'" +allow-list-value = permissions-source-expression / "*" / "'self'" / "'src'" / "'none'" +permissions-source-expression = scheme-source / host-source -

    serialized-origin is the serialization of an origin. However, the code points U+0027 ('), - U+0021 (*), U+002C (,) and U+003B (;) MUST NOT appear in the serialization. - If they are required, they must be percent-encoded as "%27", "%2A", - "%2C" or "%3B", respectively.

    -
    The string "'self'" may be used as an origin in an allowlist. - When it is used in this way, it will refer to the origin of the document - which contains the permissions policy.
    +
    The string "'self'" may be used as an origin in an allowlist. When it is used in this way, it will refer to the origin of the Document which contains the permissions + policy.

    5.2. Structured header serialization

    Policy Directives in HTTP headers are represented as Structured - Fields. [HEADER-STRUCTURE] + Fields. [RFC8941]

    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 a supported - feature, then the Dictionary Member will be ignored by the processing steps.

    -

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

    +

    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 serialization of an origin

      +

      a String containing the ASCII permissions-source-expression

    • the Token *

    • @@ -1256,6 +1399,8 @@

      , 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 @@ -1265,46 +1410,42 @@

      6. Delivery

      -

      6.1. Permissions-Policy HTTP Header - Field

      +

      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 + 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 = sh-dictionary
+     
      `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 +

      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 +

      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.

      +

      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 +

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

      + specification redefines these attributes to influence the iframe's content navigable's container policy.

      6.3.1. allowfullscreen

      -

      The "allowfullscreen" iframe attribute controls access to requestFullscreen().

      -

      If the iframe element has an "allow" attribute whose - value contains the token "fullscreen", then the - "allowfullscreen" attribute must have no effect.

      -

      Otherwise, the presence of an "allowfullscreen" attribute - on an iframe will result in adding an allowlist of * for the "fullscreen" feature to the iframe element’s content navigable's container policy, when +

      The allowfullscreen iframe attribute controls access to requestFullscreen().

      +

      If the iframe element has an allow attribute whose value + contains the token "fullscreen", then the allowfullscreen attribute must have no effect.

      +

      Otherwise, the presence of an allowfullscreen attribute + on an iframe will result in adding an allowlist of * for the "fullscreen" feature to the iframe element’s content navigable's container policy, when it is constructed.

      This is different from the behaviour of <iframe allow="fullscreen">, and is for compatibility with existing @@ -1431,7 +1572,7 @@

      sequence<DOMString> getAllowlistForFeature(DOMString feature); }; -partial interface Document { +partial interface Document { [SameObject] readonly attribute PermissionsPolicy permissionsPolicy; }; @@ -1442,22 +1583,22 @@

      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:

      + an origin, whose value depends on the state of the PermissionsPolicy object’s associated node:

      -

      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, +

      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.

      +

      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:

        @@ -1475,7 +1616,7 @@

        Set result to an empty ordered set.

      1. -

        For each supported feature feature:

        +

        For each supported feature feature:

        1. Append feature to result.

          @@ -1493,7 +1634,7 @@

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

        2. -

          For each supported feature feature:

          +

          For each supported feature feature:

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

            @@ -1505,28 +1646,40 @@

            1. -

              Set result to an empty list

              +

              Set result to an empty list.

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

              + 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]

              +

              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 allowlist is the special value *, append "*" to result

              +

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

            9. -

              Otherwise, for each origin in allowlist:

              +

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

              1. -

                Append the serialization of origin to result

                +

                Append item to result

            10. Return result.

            -

            The observable policy for any Node is a permissions +

            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.

            @@ -1534,11 +1687,9 @@

            1. -

              Let inherited policy be a new ordered map.

              -
            2. -

              Let declared policy be a new ordered map.

              +

              Let inherited policy be an empty ordered map.

            3. -

              For each supported feature feature:

              +

              For each supported feature feature:

              1. Let isInherited be the result of running Define @@ -1547,18 +1698,18 @@

                Set inherited policy[feature] to isInherited.

            4. -

              Return a new permissions policy with inherited policy inherited policy and declared policy declared policy.

              +

              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 unique opaque origin.

              + 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 unique - opaque origin.

              + 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. @@ -1603,7 +1754,7 @@

              8.

              • featureId: The -string identifying the policy-controlled feature whose policy has +string identifying the policy-controlled feature whose policy has been violated. This string can be used for grouping and counting related reports.

              • @@ -1621,24 +1772,37 @@

                8. enforced in this case. disposition will be set to "enforce" if the policy was enforced, or "report" if the violation resulted only in this report being generated (with no further action taken by the user agent in response to the violation).

                -

                Note: There is currently no mechanism in place for enabling report-only -mode, so disposition will always -be set to "enforce".

              +
              +

              8.1. `Permissions-Policy-Report-Only` + HTTP Header Field

              +

              The `Permissions-Policy-Report-Only` + HTTP header field can be used in the response (server to client) to + communicate a permissions policy that should not be enforced by the + client, but instead should be used to trigger reports to be sent if any + policy declared within it would have been violated, had the policy been + active.

              +

              `Permissions-Policy-Report-Only` is a + structured header. Its value must be a 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.

              +

      9. Algorithms

      9.1. Process response policy

      - Given a response (response) and an origin (origin), this - algorithm returns a declared permissions policy. + Given a response (response), an origin (origin), and a boolean + (report-only), this algorithm returns a declared policy.
        +
      1. +

        Let header name be "Permissions-Policy-Report-Only" if report-only is True, or "Permissions-Policy" otherwise.

      2. Let parsed header be the result of executing get a structured -field value given "Permissions-Policy" and "dictionary" from response’s header list.

        +field value given header name and "dictionary" from response’s header list.

      3. -

        If parsed header is null, abort these steps.

        +

        If parsed header is null, return an empty ordered map.

      4. Let policy be the result of executing Construct policy from dictionary and origin on parsed header and origin.

        @@ -1650,20 +1814,24 @@

        <

        9.2. Construct policy from dictionary and origin

        - Given an ordered map (dictionary) and an origin (origin), this - algorithm will return a declared permissions policy. + Given an ordered map (dictionary) and an origin (origin), this + algorithm will return a declared policy.
        1. -

          Let policy be an empty ordered map.

          +

          Let declarations be an empty ordered map.

          +
        2. +

          Let reporting-config be an empty ordered map.

        3. -

          For each feature-name → value of dictionary:

          +

          For each feature-name → (value, params) of dictionary:

          1. -

            If feature-name does not identify any recognized policy-controlled feature, then continue.

            +

            If feature-name does not identify any recognized policy-controlled feature, then continue.

          2. -

            Let feature be the policy-controlled feature identified by feature-name.

            +

            Let feature be the policy-controlled feature identified by feature-name.

            +
          3. +

            If params["report-to"] exists, and is a string, then set reporting-config[feature] to params["report-to"].

          4. -

            Let allowlist be a new allowlist.

            +

            Let allowlist be a new allowlist.

          5. If value is the token *, or if value is a list which contains the token *, set allowlist to the special value *.

            @@ -1671,44 +1839,33 @@

            Otherwise:

            1. -

              Set allowlist to an new ordered set.

              -
            2. -

              If value is the token self, append origin to allowlist.

              +

              If value is the token self, let allowlist’s self-origin be origin.

            3. -

              If value is a list, then for each element in value:

              +

              Otherwise if value is a list, then for each element in value:

              1. -

                If element is the token self, append origin to allowlist.

                +

                If element is the token self, let allowlist’s self-origin 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.

                  -
                +

                If element is a valid permissions-source-expression, append element to allowlist’s expressions.

          6. -

            Set policy[feature] to allowlist.

            +

            Set declarations[feature] to allowlist.

        4. -

          Return policy.

          +

          Return «declarations, reporting-config».

        9.3. Parse policy directive

        - Given a string (value), an origin (container origin), and an - optional origin (target origin), this algorithm returns a policy + Given a string (value), an origin (container origin), and an + optional origin (target origin), this algorithm returns a policy directive.
        1. -

          Let directive be an empty ordered map.

          +

          Let directive be an empty ordered map.

        2. For each serialized-declaration returned by strictly splitting value on the delimiter U+003B (;):

          @@ -1717,45 +1874,55 @@

          Let tokens be the result of splitting serialized-declaration on ASCII whitespace.

        3. -

          If tokens is an empty list, then continue.

          +

          If tokens is an empty list, then continue.

        4. Let feature-name be the first element of tokens.

        5. -

          If feature-name does not identify any recognized policy-controlled feature, then continue.

          +

          If feature-name does not identify any recognized policy-controlled feature, then continue.

        6. -

          Let feature be the policy-controlled feature identified by feature-name.

          +

          Let feature be the policy-controlled feature identified by feature-name.

        7. Let targetlist be the remaining elements, if any, of tokens.

        8. -

          Let allowlist be a new allowlist.

          +

          Let allowlist be a new allowlist.

        9. If any element of targetlist is the string "*", set allowlist to the special value *.

        10. Otherwise:

          1. -

            Set allowlist to an new ordered set.

            -
          2. -

            If targetlist is empty and target origin is given, append target origin to allowlist.

            +

            If targetlist is empty and target origin is given, + let allowlist’s src-origin be target origin.

          3. For each element in targetlist:

            1. If element is an ASCII case-insensitive match for -"'self'", let result be container origin.

              +"'self'":

              +
                +
              1. +

                Let allowlist’s self-origin be container origin.

                +
              2. +

                Continue to the next element.

                +

            2. If target origin is given, and element is an ASCII -case-insensitive match for "'src'", let result be target origin.

              +case-insensitive match for "'src'":

              +
                +
              1. +

                Let allowlist’s src-origin be target origin.

                +
              2. +

                Continue to the next element.

                +
            3. -

              Otherwise, let result be the result of executing the URL -parser on element.

              +

              Let result be the result of executing the URL parser on element.

            4. If result is not failure:

              1. -

                Let target be the origin of result.

                +

                Let target be the origin of result.

              2. -

                If target is not an opaque origin, append target to allowlist.

                +

                If target is not an opaque origin, append the serialization of target to allowlist’s expressions.

          @@ -1770,27 +1937,22 @@

          9.4. Process permissions policy attributes

          - Given an element (element), this algorithm returns a container + Given an element (element), this algorithm returns a container policy, which may be empty.
            +
          1. +

            If element is not an iframe element, then return an empty policy + directive.

          2. Let container policy be the result of running Parse policy -directive on the value of element’s allow attribute, -with container origin set to the origin of element’s -node document, and target origin set to element’s declared origin.

            +directive given the value of element’s allow attribute, +the origin of element’s node document, and element’s declared origin.

          3. -

            If element is an iframe element:

            +

            If element’s allowfullscreen attribute is specified, and container policy does not contain an entry for the fullscreen feature.

            1. -

              If element’s allowfullscreen attribute is specified, -and container policy does not contain an allowlist for fullscreen:

              -
                -
              1. -

                Let declaration be a new declaration for fullscreen, whose -allowlist is the special value *.

                -
              2. -

                Add declaration to container policy.

                -
              +

              Set container policy[fullscreen] = the + special value *.

          4. Return container policy.

            @@ -1800,16 +1962,14 @@

            9.5. Create a Permissions Policy for a navigable

            - Given null or an element (container) and an origin (origin) this algorithm returns a new Permissions Policy. + Given null or an element (container) and an origin (origin) this algorithm returns a new Permissions Policy.
            1. -

              Assert: If not null, container is a navigable container.

              +

              Assert: If not null, container is a navigable container.

            2. -

              Let inherited policy be a new ordered map.

              +

              Let inherited policy be a new ordered map.

            3. -

              Let declared policy be a new ordered map.

              -
            4. -

              For each feature supported,

              +

              For each feature supported,

              1. Let isInherited be the result of running Define an @@ -1818,29 +1978,34 @@

                Set inherited policy[feature] to isInherited.

            5. -

              Let policy be a new permissions policy, with inherited policy inherited policy and declared policy declared policy.

              +

              Let policy be a new permissions policy, with inherited policy inherited policy and declared policy «[], []».

            6. Return policy.

        -

        9.6. Create a Permissions Policy for a navigable from response

        +

        9.6. Create a Permissions Policy for a navigable from response

        - Given null or a navigable container (container), an origin (origin), and a response (response), this algorithm returns a new Permissions Policy. + Given null or a navigable container (container), an origin (origin), a response (response), and an optional boolean + (report-only), with a default value of False, this algorithm returns a new permissions policy.

        1. Let policy be the result of running Create a Permissions Policy for a navigable given container and origin.

        2. Let d be the result of running Process response -policy on response and origin.

          +policy given response, origin and report-only.

        3. -

          For each feature → allowlist of d:

          +

          For each feature → allowlist of d’s declarations:

          1. -

            If policy’s inherited policy[feature] is true, then set policy’s declared policy[feature] to allowlist.

            +

            If policy’s inherited + policy[feature] is true, then set policy’s declared policy’s declarations[feature] to allowlist.

          +
        4. +

          Set policy’s declared + policy[feature]'s reporting configuration to d’s reporting configuration.

        5. Return policy.

        @@ -1849,81 +2014,179 @@

        9.7. Define an inherited policy for feature in container at origin

        - Given a feature (feature), null or a navigable container (container), and an origin for a document in that container - (origin), this algorithm returns the inherited policy for that - feature. + Given a feature (feature), null or a navigable container (container), and an origin for a Document in + that container (origin), this algorithm returns the inherited policy value for feature.

        1. If container is null, return "Enabled".

        2. -

          If the result of executing Is feature -enabled in document for origin? on feature, container’s node document, and container’s node document''s origin -is "Disabled", return "Disabled".

          +

          If the result of executing Get feature value for +origin on feature, container’s node document, and container’s node document’s origin is +"Disabled", return "Disabled".

          +
        3. +

          If the result of executing Get feature value for +origin on feature, container’s node document, and origin is "Disabled", return "Disabled".

          +
        4. +

          Let container policy be the result of running Process +permissions policy attributes on container.

          +
        5. +

          If feature exists in container policy:

          +
            +
          1. +

            If the allowlist for feature in container policy matches origin, return "Enabled".

            +
          2. +

            Otherwise return "Disabled".

            +
          +
        6. +

          If feature’s default allowlist is *, return +"Enabled".

        7. -

          If the result of executing Is feature -enabled in document for origin? on feature, container’s node document, and origin is "Disabled", -return "Disabled".

          +

          If feature’s default allowlist is 'self', and origin is same origin with container’s node document’s origin, return "Enabled".

          +
        8. +

          Otherwise return "Disabled".

          +
        +
        +

        +
        +

        9.8. Get feature value for origin

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

        +
          +
        1. +

          Let policy be document’s permissions 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 policy’s declared + policy’s declarations[feature] matches origin, then return "Enabled".

            +
          2. +

            Otherwise return "Disabled".

            +
          +
        4. +

          Return "Enabled".

          +
        +
        +
        +
        +

        9.9. Check permissions policy

        +
        + To check a permissions policy, given permissions policy (policy), a feature (feature), an origin (origin) and another origin (document origin), this algorithm returns "Disabled" if feature should be considered disabled, and "Enabled" + otherwise. +
        1. -

          Let container policy be the result of running Process -permissions policy attributes on container.

          +

          If policy’s inherited policy for feature is "Disabled", return "Disabled".

        2. -

          If feature is a key in container policy:

          +

          If feature is present in policy’s declared policy:

          1. -

            If the allowlist for feature in container policy matches origin, return "Enabled".

            +

            If policy’s declared + policy’s declarations[feature] matches origin, then return "Enabled".

          2. Otherwise return "Disabled".

        3. -

          If feature’s default allowlist is *, return +

          If feature’s default allowlist is *, return "Enabled".

        4. -

          If feature’s default allowlist is 'self', and origin is same origin with container’s node document’s -origin, return "Enabled".

          +

          If feature’s default allowlist is 'self', and origin is same origin with document origin, return +"Enabled".

        5. -

          Otherwise return "Disabled".

          +

          Return "Disabled".

        -

        9.8. Is feature enabled in document for origin?

        +

        9.10. Is feature enabled in document for origin?

        - Given a feature (feature), a Document object - (document), and an origin (origin), this algorithm - returns "Disabled" if feature should be considered - disabled, and "Enabled" otherwise. + Given a feature (feature), a Document object + (document), an origin (origin), and an optional boolean (report), + with a default value of True, this algorithm returns "Disabled" + if feature should be considered disabled, and "Enabled" + otherwise. If report is True, then it will also generate and queue a + report if the feature is not enabled in either document’s permissions policy or document’s report-only + permissions policy

        +

        Note: The default value of True for report means that most permissions + policy checks will generate a violation report if the feature is not + enabled. This is the expected result, as most checks are for an actual + attempted use of the feature. If a call to this algorithm is performed just + to query the state of a feature, and does not represent an actual attempt to + use the feature, then report should be set to False.

        1. -

          Let policy be document’s Permissions Policy

          +

          Let policy be document’s permissions policy.

          +
        2. +

          Let report-only policy be document’s report-only + permissions policy.

          +
        3. +

          Let result be the result of calling Check permissions + policy, given policy, feature, origin, and document’s origin.

        4. -

          If policy’s inherited policy for feature is Disabled, return -"Disabled".

          +

          Let report-only result be the result of calling Check + permissions policy, given report-only policy, feature, origin, + and document’s origin.

        5. -

          If feature is present in policy’s declared policy:

          +

          If report is True:

          1. -

            If the allowlist for feature in policy’s declared -policy matches origin, then return -"Enabled".

            +

            Let settings be document’s environment settings object.

          2. -

            Otherwise return "Disabled".

            +

            If result is "Disabled":

            +
              +
            1. +

              Let endpoint be the result of calling Get the + reporting endpoint for a feature given feature and policy.

              +
            2. +

              Call Generate report for violation of permissions + policy on settings given feature, settings, + "Enforce", and endpoint.

              +
            +
          3. +

            Else, if report-only result is "Disabled":

            +
              +
            1. +

              Let report-only endpoint be the result of calling Get the reporting endpoint for a feature given feature and report-only policy.

              +
            2. +

              Call Generate report for violation of permissions + policy on settings given feature, settings, + "Report", and report-only endpoint.

              +
        6. -

          If feature’s default allowlist is *, return -"Enabled".

          +

          Return result

          +
        +
        +
        +
        +

        9.11. Get the reporting endpoint for a feature

        +
        + Given a feature (feature) and a permissions policy (policy), + this algorithm returns a string naming the endpoint to send violation + reports to, or null if no such endpoint has been declared in policy. +
        1. -

          If feature’s default allowlist is 'self', and origin is same origin with document’s origin, return -"Enabled".

          +

          Let config be policy’s declared policy's reporting configuration.

        2. -

          Return "Disabled".

          +

          If config[feature] exists, return config[feature].

          +
        3. +

          Return null.

        -

        9.9. Generate report for violation of permissions policy on settings

        +

        9.12. Generate report for violation of permissions policy on settings

        - Given a feature (feature), an environment settings object (settings), and an optional string (group), this algorithm generates a report about the violation of the policy for feature. + Given a feature (feature), an environment settings object (settings), a string (disposition), and a string-or-null (endpoint), + this algorithm generates a report about the violation of the + policy for feature.

        1. Let body be a new PermissionsPolicyViolationReportBody, initialized @@ -1941,29 +2204,26 @@

          columnNumber

          null

          -
          disposition +
          disposition
          -

          "enforce"

          +

          disposition

        2. If the user agent is currently executing script, and can extract the source file’s URL, line number, and column number from settings, then set body’s sourceFile, lineNumber, and columnNumber accordingly.

        3. -

          If group is omitted, set group to "default".

          -
        4. -

          Execute generate and queue a report with body, -"permissions-policy-violation", group, and settings.

          +

          Execute generate and queue a report with body, +"permissions-policy-violation", endpoint, and settings.

        -

        Note: This algorithm should be called when a permissions policy has - been violated.

        -

        9.10. Should request be allowed to use feature?

        +

        9.13. Should request be allowed to use feature?

        - Given a feature (feature) and a request (request), this - algorithm returns true if the request should be allowed to use feature, and false otherwise. + Given a feature (feature) and a request (request), + this algorithm returns true if the request should be allowed to + use feature, and false otherwise.

        1. @@ -1980,7 +2240,7 @@

          origin.

        2. -

          Let result be the result of executing Is feature +

          Let result be the result of executing Is feature enabled in document for origin? on feature, document, and origin.

        3. If result is "Enabled", return true.

          @@ -1991,7 +2251,26 @@

          10. IANA Considerations

          +

          10. Changes to other specifications

          +
          +

          10.1. Changes to the HTML specification

          + Every Document has a report-only permissions + policy, which is a permissions policy, which is initially empty. +

          In 7.5.1 + Shared document creation infrastructure, after step 3, insert the + following step:

          +
            +
          1. +

            Let reportOnlyPermissionsPolicy be the result of calling Create a Permissions Policy for a navigable from + response given navigationParams’s navigable’s container, + navigationParams’s origin, navigationParams’s response, and True.

            +
          +

          And in the same section, in step 10, set the new Document's

          + report-only permissions policy to reportOnlyPermissionsPolicy. +
          +

        +
        +

        11. IANA Considerations

        The permanent message header field registry should be updated with the following registration [RFC3864]:

        @@ -2004,11 +2283,11 @@

        Author/Change controller
        W3C
        Specification document -
        Permissions Policy API +
        https://www.w3.org/TR/permissions-policy/

        -

        11. Privacy and Security

        +

        12. Privacy and Security

        This specification standardizes a mechanism for an embedding page to set a policy which will be enforced on an embedded page. Similar to iframe sandbox, this can be done without the express permission of the embedded page, which means that behaviors of existing features can be changed @@ -2026,8 +2305,8 @@

        -

        11.1. Exposure of cross-origin behavior

        -

        Features should be designed such that a violation of the policy in a +

        12.1. Exposure of cross-origin behavior

        +

        Features should be designed such that a violation of the policy in a framed document is not observable by documents in other frames. For instance, a hypothetical feature which caused a event to be fired in the embedding document if it is used while disabled by policy, could be used to extract @@ -2041,7 +2320,7 @@

        src attribute of the <iframe> element will cause the observable policy to be updated.

        -

        11.2. Unanticipated behavior changes

        +

        12.2. Unanticipated behavior changes

        The Permissions Policy mechanism grants a document the ability to control which features will and will not be availble in a subframe at the time it is loaded. When a feature represents an existing, long-standing behavior of the @@ -2090,7 +2369,7 @@

        -

        11.3. Exposure of embedding policy

        +

        12.3. Exposure of embedding policy

        Care has been taken to limit the information which an page can infer about the behavior of cross-origin pages which it embeds. It may be possible in some scenarios however, for the embedded page to infer information about its @@ -2103,8 +2382,8 @@

        -

        12. Change log

        -

        12.1. Changes since FPWD

        +

        13. Change log

        +

        13.1. Changes since FPWD

        • Expose new algorithms to create a Feature Policy before document is created. Link

          @@ -2151,34 +2430,37 @@

          , like this:

          Note, this is an informative note.

          -

          Conformant Algorithms

          -

          Requirements phrased in the imperative as part of algorithms +

          +

          Conformant Algorithms

          +

          Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

          -

          Conformance requirements phrased as algorithms or specific steps +

          Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

          +

      Index

      Terms defined by this specification

    • empty permissions policy, in § 4.2 +
    • expressions, in § 4.7
    • featureId +
    • Permissions-Policy-Report-Only, in § 8.1
    • PermissionsPolicyViolationReportBody, in § 8
    • Permissions policy violation reports, in § 8 +
    • permissions-source-expression, in § 5.1
    • policy-controlled feature, in § 4.1 -
    • policy directive, in § 4.7 -
    • policy directives, in § 4.7 +
    • policy directive, in § 4.6 +
    • policy directives, in § 4.6
    • policy object - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Terms defined by reference

      • [CSP3] defines the following terms:
          -
        • sandbox +
        • does url match expression in origin with redirect count? +
        • host-source +
        • sandbox +
        • scheme-source
      • [DOM] defines the following terms:
          -
        • Document -
        • Element -
        • Node -
        • document -
        • element -
        • node document +
        • Document +
        • Element +
        • Node +
        • document +
        • element +
        • node document +
        • origin
      • [FETCH] defines the following terms:
          -
        • get a structured field value -
        • origin -
        • request -
        • response -
        • window +
        • get a structured field value +
        • header list +
        • origin +
        • request +
        • response +
        • window
      • [FULLSCREEN] defines the following terms:
          -
        • requestFullscreen() -
        -
      • - [HEADER-STRUCTURE] defines the following terms: -
          -
        • sh-dictionary +
        • requestFullscreen()
      • [HTML] defines the following terms:
          -
        • HTMLIFrameElement -
        • Window -
        • WorkerGlobalScope -
        • WorkletGlobalScope -
        • associated document -
        • child navigable -
        • content navigable -
        • descendant navigables -
        • environment settings object -
        • iframe -
        • navigable container -
        • same origin -
        • same origin-domain -
        • sandbox -
        • sandboxed origin browsing context flag -
        • serialization of an origin -
        • src -
        • srcdoc -
        • top-level traversable +
        • HTMLIFrameElement +
        • Window +
        • WorkerGlobalScope +
        • WorkletGlobalScope +
        • active document +
        • allow +
        • allowfullscreen +
        • associated document +
        • child navigable +
        • content navigable +
        • descendant navigables +
        • environment settings object +
        • iframe +
        • navigable +
        • navigable container +
        • opaque origin +
        • parent +
        • permissions policy +
        • same origin +
        • same origin-domain +
        • sandbox +
        • sandboxed origin browsing context flag +
        • serialization of an origin +
        • src +
        • srcdoc +
        • top-level traversable
      • [INFRA] defines the following terms:
          -
        • ascii case-insensitive -
        • ordered map -
        • ordered set -
        • split on ascii whitespace -
        • strictly split +
        • append +
        • ascii case-insensitive +
        • contain +
        • continue +
        • exist +
        • for each (for list) +
        • for each (for map) +
        • item +
        • list +
        • ordered map +
        • set +
        • split on ascii whitespace +
        • strictly split +
        • string +
        • struct
      • [PERMISSIONS] defines the following terms:
          -
        • feature +
        • feature
      • [REPORTING-1] defines the following terms:
          -
        • ReportBody -
        • body -
        • generate and queue a report -
        • report -
        • report type -
        • visible to reportingobservers +
        • ReportBody +
        • body +
        • generate and queue a report +
        • report +
        • report type +
        • visible to reportingobservers +
        +
      • + [RFC8941] defines the following terms: +
          +
        • sf-dictionary
      • [URL] defines the following terms:
          -
        • origin -
        • url parser +
        • origin +
        • url parser
      • [WEBIDL] defines the following terms:
          -
        • DOMString -
        • Exposed -
        • SameObject -
        • boolean -
        • long -
        • sequence +
        • DOMString +
        • Exposed +
        • SameObject +
        • boolean +
        • long +
        • sequence

      References

      @@ -2736,8 +2693,6 @@

      N
      Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
      [FULLSCREEN]
      Philip Jägenstedt. Fullscreen API Standard. Living Standard. URL: https://fullscreen.spec.whatwg.org/ -
      [HEADER-STRUCTURE] -
      Mark Nottingham; Poul-Henning Kamp. Structured Field Values for HTTP. Draft. URL: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-18
      [HTML]
      Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
      [INFRA] @@ -2750,6 +2705,8 @@

      N
      S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
      [RFC3864]
      G. Klyne; M. Nottingham; J. Mogul. Registration Procedures for Message Header Fields. September 2004. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc3864 +
      [RFC8941] +
      M. Nottingham; P-H. Kamp. Structured Field Values for HTTP. February 2021. Proposed Standard. URL: https://httpwg.org/specs/rfc8941.html
      [URL]
      Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
      [WEBIDL] @@ -2800,367 +2757,10 @@

      ↵ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ⚠MDN
      -

      Headers/Feature-Policy

      +

      Headers/Feature-Policy

      In only one current engine.

      FirefoxNoneSafariNoneChrome60+ @@ -3172,66 +2772,235 @@

      Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

      +
      +

      Headers/Permissions-Policy

      +

      In only one current engine.

      +
      + FirefoxNoneSafariNoneChrome88+ +
      + Opera?Edge88+ +
      + Edge (Legacy)?IENone +
      + Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile? +
      +
      - - + + + - + \ No newline at end of file + function previousHighlightIndex(algoName, varName) { + return indexNames.get(algoName+"///"+varName); + } + function nameFromIndex(index) { + return "selected" + index; + } +} + \ No newline at end of file