diff --git a/index.bs b/index.bs index 0da4172a..5e0700b8 100644 --- a/index.bs +++ b/index.bs @@ -159,6 +159,20 @@ spec:fetch; type:dfn; text:value
  • A declared policy.
    • +

    The feature policy for a {{Document}} or {{WorkerGlobalScope}} + determines whether a feature is allowed or disallowed in that + context.

    +

    A feature which is disallowed should be disabled, or be made + unavailable for use in the Document or web worker. Each feature may have a + different mechanism for being disabled when disallowed, which should + be defined in that feature's specification.

    +

    A feature is allowed if it is not disallowed.

    +

    A feature may be allowed by default in a {{Document}} or + {{WorkerGlobalScope}}. If a feature is allowed by default, then it + is allowed if no other policy disallows it.

    +

    A feature may be disallowed by default in a {{Document}} or + {{WorkerGlobalScope}}. If a feature is disallowed by default, then it + is disallowed unless explicitly allowed by policy.

    Inherited policies

    @@ -257,16 +271,18 @@ spec:fetch; type:dfn; text:value allowlists:

    *
    -
    The feature is allowed at the top level by default, and when allowed, - is allowed by default to documents in child frames.
    +
    The feature is allowed by default in top-level documents. If + allowed in a frame, the feature is allowed by default in that + frame's children.
    '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 allowed by default in top-level documents. If + allowed in a frame, the feature is allowed by default in + same-origin documents in child frames, and is disallowed by default + in cross-origin documents in child frames.
    'none'
    -
    The feature is disallowed at the top level by default, and is also - disallowed by default to documents in child frames.
    +
    The feature is disallowed by default in top-level documents, + and is also disallowed by default in documents in child frames. +
    @@ -380,6 +396,35 @@ partial interface HTMLIFrameElement { +
    +

    Combining Policies from different sources

    +

    To determine the effective feature policy for a given document, several + pieces of information are required:

    + +

    If the document is in a frame, then this is also required:

    + +

    Then, for each supported feature, we go through these steps:

    +
      +
    1. Use the parent's policy and the container policy to define the + inherited policy for the new document. + For each feature, if it is allowed by the parent for the new document's origin, + and not disallowed by the container policy, then it is enabled in the inherited policy. Otherwise, it is disabled.
      2. +
    2. Use the inherited policy and the document's header policy to determine the + effective policy for the new document. + For each feature, if it is disabled in the inherited policy, then its allowlist will be empty. + If it is enabled, and there is a declaration for that feature in the header policy, then its allowlist will be the declared list from the header. + If it is enabled, and there is no declaration for that feature in the header policy, then its allowlist will be the default allowlist for the feature (with 'self' replaced with the origin of the document). +
      3. +
    +

    Integrations

    This document defines a set of algorithms which other specifications will diff --git a/index.html b/index.html index b8498fc5..131f7100 100644 --- a/index.html +++ b/index.html @@ -1423,7 +1423,7 @@

    Feature Policy

    -

    Draft Community Group Report,

    +

    Draft Community Group Report,

    This version: @@ -1494,29 +1494,30 @@

    Table of Contents

  • 6.3.2 allowpaymentrequest +
  • 7 Combining Policies from different sources
  • - 7 Integrations + 8 Integrations
      -
    1. 7.1 Integration with HTML +
    2. 8.1 Integration with HTML
  • - 8 Algorithms + 9 Algorithms
      -
    1. 8.1 Process response policy -
    2. 8.2 Parse header from value and origin -
    3. 8.3 Parse policy directive from value and origin -
    4. 8.4 Merge directive with declared +
    5. 9.1 Process response policy +
    6. 9.2 Parse header from value and origin +
    7. 9.3 Parse policy directive from value and origin +
    8. 9.4 Merge directive with declared policy -
    9. 8.5 Process feature policy +
    10. 9.5 Process feature policy attributes -
    11. 8.6 Parse allow attribute -
    12. 8.7 Initialize global’s Feature +
    13. 9.6 Parse allow attribute +
    14. 9.7 Initialize global’s Feature Policy from response -
    15. 8.8 Define an inherited policy for feature -
    16. 8.9 Is feature enabled in global for origin? +
    17. 9.8 Define an inherited policy for feature +
    18. 9.9 Is feature enabled in global for origin?
    -
  • 9 IANA Considerations -
  • 10 Privacy and Security +
  • 10 IANA Considerations +
  • 11 Privacy and Security
  • Conformance
  • Index @@ -1666,6 +1667,17 @@

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

    The feature policy for a Document or WorkerGlobalScope determines whether a feature is allowed or disallowed in that + context.

    +

    A feature which is disallowed should be disabled, or be made + unavailable for use in the Document or web worker. Each feature may have a + different mechanism for being disabled when disallowed, which should + be defined in that feature’s specification.

    +

    A feature is allowed if it is not disallowed.

    +

    A feature may be allowed by default in a Document or WorkerGlobalScope. If a feature is allowed by default, then it + is allowed if no other policy disallows it.

    +

    A feature may be disallowed by default in a Document or WorkerGlobalScope. If a feature is disallowed by default, then it + is disallowed unless explicitly allowed by policy.

    • 4.3. Inherited policies

    @@ -1693,7 +1705,7 @@

    4.5. Header policies

    -

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

    +

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

    4.6. Container policies

    @@ -1701,7 +1713,7 @@

    , 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 + policy of any document loaded into that frame. (See §9.8 Define an inherited policy for feature)

    Currently, the container policy cannot be set directly, but is indirectly set by iframe "allowfullscreen", @@ -1743,16 +1755,16 @@

    :

    * -
    The feature is allowed at the top level by default, and when allowed, - is allowed by default to documents in child frames. +
    The feature is allowed by default in top-level documents. If + allowed in a frame, the feature is allowed by default in that + frame’s children.
    '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 allowed by default in top-level documents. If + allowed in a frame, the feature is allowed by default in + same-origin documents in child frames, and is disallowed by default in cross-origin documents in child frames.
    'none' -
    The feature is disallowed at the top level by default, and is also - disallowed by default to documents in child frames. +
    The feature is disallowed by default in top-level documents, + and is also disallowed by default in documents in child frames.

    @@ -1783,13 +1795,13 @@

    6.

    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.

    + 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 ASCII serialization of one or more policy directives:.

    FeaturePolicy = serialized-feature-policy *("," serialized-feature-policy)

    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.

    + it MUST process and enforce the serialized policy as described in §8.1 Integration with HTML.

    6.2. The allow attribute of the iframe element

    @@ -1847,16 +1859,42 @@

    7. Integrations

    +

    7. Combining Policies from different sources

    +

    To determine the effective feature policy for a given document, several + pieces of information are required:

    +
      +
    • The default allowlists for all features supported by the user agent +
    • The header policy for the document +
    • The origin of the document +
    +

    If the document is in a frame, then this is also required:

    +
      +
    • The feature policy of the document in the parent frame +
    • The container policy defined for the document’s frame by its parent. +
    +

    Then, for each supported feature, we go through these steps:

    +
      +
    1. Use the parent’s policy and the container policy to define the inherited policy for the new document. + For each feature, if it is allowed by the parent for the new document’s origin, + and not disallowed by the container policy, then it is enabled in the inherited policy. Otherwise, it is disabled. +
    2. Use the inherited policy and the document’s header policy to determine the + effective policy for the new document. + For each feature, if it is disabled in the inherited policy, then its allowlist will be empty. + If it is enabled, and there is a declaration for that feature in the header policy, then its allowlist will be the declared list from the header. + If it is enabled, and there is no declaration for that feature in the header policy, then its allowlist will be the default allowlist for the feature (with 'self' replaced with the origin of the document). +
    +
    +
    +

    8. Integrations

    This document defines a set of algorithms which other specifications will use in order to implement the restrictions which Feature Policy defines. The integrations are outlined here for clarity, but those external documents are the normative references which ought to be consulted for detailed information.

    -

    7.1. Integration with HTML

    +

    8.1. Integration with HTML

      -
    1. Document and WorkerGlobalScope objects have a Feature Policy, which is populated via the §8.7 Initialize global’s Feature +
    2. Document and WorkerGlobalScope objects have a Feature Policy, which is populated via the §9.7 Initialize global’s Feature Policy from response algorithm that is called during the "Initialising a new Document object" and "Run a Worker" algorithms. @@ -1865,16 +1903,16 @@

    3. Initialize the feature policy for the Document -
    4. A feature policy is enforced for - a Document or WorkerGlobalScope by setting it as the Document or WorkerGlobalScope's Feature Policy. +
    5. A feature policy is enforced for + a Document or WorkerGlobalScope by setting it as the Document or WorkerGlobalScope's Feature Policy.
    6. -

      The "allowed to use" algorithm calls into §8.9 Is feature enabled in +

      The "allowed to use" algorithm calls into §9.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 +
        • If Document’s feature policy enables the feature indicated by allowattribute for the origin of Document, then return true.
        @@ -1885,9 +1923,9 @@

    -

    8. Algorithms

    +

    9. Algorithms

    -

    8.1. Process response policy

    +

    9.1. Process response policy

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

      @@ -1898,13 +1936,13 @@

      Add a leading "[" U+005B character, and a trailing "]" U+005D character to header. -
    1. Let feature policy be the result of executing §8.2 Parse header from value and +
    2. Let feature policy be the result of executing §9.2 Parse header from value and origin on header and global’s origin.
    3. Return feature policy.

    -

    8.2. Parse header from value and origin

    +

    9.2. Parse header from value and origin

    This section is out of date; the header format is no longer JSON.

    Given a string (value) and an origin (origin) @@ -1918,16 +1956,16 @@

    §8.3 Parse policy directive from +
  • Let directive be the result of executing §9.3 Parse policy directive from value and origin on element and origin -
  • Run §8.4 Merge directive with declared +
  • Run §9.4 Merge directive with declared policy on directive and policy.
  • Return policy.

    • -

    8.3. Parse policy directive from value and origin

    +

    9.3. Parse policy directive from value and origin

    This section is out of date; the header format is no longer JSON.

    Given a JSON object (value) and an origin (origin) this algorithm will return a policy @@ -1963,7 +2001,7 @@

    -

    8.4. Merge directive with declared +

    9.4. Merge directive with declared policy

    Given a policy direcive (directive) and a declared policy (policy), this algorithm will modify policy to @@ -1977,7 +2015,7 @@

    8.5. Process feature policy +

    9.5. Process feature policy attributes

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

      @@ -2018,7 +2056,7 @@

      8.6. Parse allow attribute

      +

      9.6. Parse allow attribute

      Given a list, this algorithm returns a list of feature name keywords, which may be empty.

        @@ -2039,36 +2077,36 @@

    -

    8.7. Initialize global’s Feature +

    9.7. Initialize global’s Feature Policy from response

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

    + (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 +
      2. Let isInherited be the result of running §9.8 Define an inherited policy for feature on feature and global.
      3. Set inherited policies[feature] to isInherited.
      -
    4. Let d be the result of executing §8.1 Process response policy on response and global. +
    5. Let d be the result of executing §9.1 Process response policy on response and global.
    6. For each feature -> allowlist of d:
      1. If inherited policies[feature] is true, then set declared policies[feature] to allowlist.
      -
    7. Let policy be a new feature policy, with inherited +
    8. Let policy be a new feature policy, with inherited policy set inherited policies and declared policy set declared policies.
    9. Enforce the policy policy.

    -

    8.8. Define an inherited policy for feature

    +

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

    + (context), this algorithm returns the inherited policy for that feature.

    1. If context is a nested browsing context: @@ -2076,29 +2114,29 @@

      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 +
    4. Let container policy be the result of running §9.5 Process feature policy attributes on context’s browsing context container.
    5. 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. If the allowlist for feature in container policy matches origin, and parent’s inherited policy for feature is Enabled, return Enabled.
      3. Otherwise return Disabled.
      -
    6. Otherwise, if feature is allowed by parent’s feature policy for origin, return Enabled. +
    7. Otherwise, if feature is allowed by parent’s feature policy for origin, return Enabled.
    8. Otherwise, return Disabled.

  • Otherwise, return Enabled.
    • -

    8.9. Is feature enabled in global for origin?

    +

    9.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. Let policy be global’s Feature Policy +
    4. If policy’s inherited policy for feature is Disabled, return "Disabled".
    5. If feature is present in policy’s declared policy: @@ -2114,7 +2152,7 @@

    -

    9. IANA Considerations

    +

    10. IANA Considerations

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

    @@ -2131,7 +2169,7 @@

    -

    10. Privacy and Security

    +

    11. Privacy and Security

    TODO

    @@ -2285,6 +2323,8 @@

    Index

    Terms defined by this specification

    @@ -2412,33 +2454,61 @@

    #feature-nameReferenced in: + + + + @@ -2455,12 +2525,12 @@

    4.3. Inherited policies
  • 4.4. Declared policies
  • 4.5. Header policies -
  • 8.1. Process response policy -
  • 8.2. Parse header from value and +
  • 9.1. Process response policy +
  • 9.2. Parse header from value and origin -
  • 8.5. Process feature policy +
  • 9.5. Process feature policy attributes -
  • 8.9. Is feature enabled in +
  • 9.9. Is feature enabled in global for origin? (2) @@ -2496,9 +2566,9 @@

    5.1. ASCII serialization
  • 6.1. Feature-Policy HTTP Header Field -
  • 8.3. Parse policy directive from +
  • 9.3. Parse policy directive from value and origin -
  • 8.5. Process feature policy +
  • 9.5. Process feature policy attributes @@ -2514,20 +2584,20 @@

    6.3.1. allowfullscreen
  • 6.3.2. allowpaymentrequest -
  • 8.3. Parse policy directive from +
  • 9.3. Parse policy directive from value and origin -
  • 8.8. Define an inherited policy for +
  • 9.8. Define an inherited policy for feature -
  • 8.9. Is feature enabled in +
  • 9.9. Is feature enabled in global for origin? @@ -2536,7 +2606,7 @@

    4.1. Policy-controlled Features
  • 4.9. Default Allowlists (2) -
  • 8.9. Is feature enabled in +
  • 9.9. Is feature enabled in global for origin? (2) @@ -2584,7 +2654,7 @@

    6.1. Feature-Policy HTTP Header Field -
  • 8.7. Initialize global’s Feature +
  • 9.7. Initialize global’s Feature Policy from response