index.bs

<pre class="metadata">
Title: Feature Policy
Shortname: feature-policy
Level: 1
Status: CG-DRAFT
Group: WICG
URL: https://wicg.github.io/feature-policy/
Editor: Ian Clelland, Google, iclelland@google.com
Abstract: This specification defines a mechanism that allows developers to selectively enable and disable use of various browser features and APIs.
Repository: https://github.com/wicg/feature-policy/
Markup Shorthands: css no, markdown yes
</pre>
<pre class="link-defaults">
spec:dom; type:interface; for:/; text:Document
spec:html; type:dfn; for:/; text:origin
spec:fetch; type:dfn; for:Response; text:response
spec:html; type:dfn; for:/; text:browsing context
spec:html; type:element; text:script
spec:html; type:element; text:link
spec:html; type:method; text:getUserMedia()
spec:html; type:dfn; text:paymentrequest
spec:fetch; type:dfn; text:name
spec:fetch; type:dfn; text:value
</pre>
<section>
  <h2 id="introduction">Introduction</h2>
  <p>The web-platform provides an ever-expanding set of features and APIs,
  offering richer functionality, better developer ergonomics, and improved
  performance. However, a missing piece is the ability for the developer to
  selectively enable, disable, or modify the behavior of some of these browser
  features and APIs within their application:</p>
  <ol>
    <li>The developer may want to selectively *disable* access to certain
    browser features and APIs to "lock down" their application, as a security
    or performance precaution, to prevent own and third-party content executing
    within their application from introducing unwanted or unexpected behaviors
    within their application.</li>
    <li>The developer may want to selectively *enable* access to certain
    browser features and APIs which may be disabled by default - e.g. some
    features may be disabled by default in embedded context unless explicitly
    enabled; some features may be subject to other policy requirements.</li>
    <li>The developer may want to use the policy to assert a promise to a
    client or an embedder about the use—or lack of thereof—of certain features
    and APIs. For example, to enable certain types of "fast path" optimizations
    in the browser, or to assert a promise about conformance with some
    requirements set by other embedders - e.g. various social networks, search
    engines, and so on.</li>
  </ol>
  <p>This specification defines a feature policy mechanism that addresses the
  above use cases.</p>
</section>
<section>
  <h2 id="examples">Examples</h2>
  <div class="example">
    <p>SecureCorp Inc. wants to disable use of Vibration and Geolocation APIs
    within their application. It can do so by delivering the following HTTP
    response header to define a feature policy:</p>
    <pre>
      <a href="#feature-policy-header">Feature-Policy</a>: vibrate 'none'; geolocation 'none'</pre>
    <p>By specifying the "<code>'none'</code>"keyword for the origin list, the
    specified features will be disabled for all browsing contexts, regardless of
    their origin.</p>
  </div>
  <div class="example">
    <p>SecureCorp Inc. wants to disable use of Geolocation API within all
    browsing contexts except for its own origin and those whose origin is
    "<code>https://example.com</code>". It can do so by delivering the
    following HTTP response header to define a feature policy:</p>
    <pre>
      <a href="#feature-policy-header">Feature-Policy</a>: geolocation 'self' https://example.com</pre>
    <p>The <a>allowlist</a> is a list of one or more origins, which can include
    the application's origin, optionally with the keyword "<code>'self'</code>",
    and any third-party origin.</p>
  </div>
  <div class="example">
    <p>SecureCorp Inc. is hosting an application on
    "<code>https://example.com</code>" and wants to disable camera and
    microphone input on its own origin but enable it for a specific embedee
    ("<code>https://other.com</code>"). It can do so by delivering the
    following HTTP response header to define a feature policy:</p>
    <pre><a href="#feature-policy-header">Feature-Policy</a>: camera https://other.com; microphone https://other.com</pre>
    <p>Some features are disabled by default in embedded contexts. The policy
    allows the application to selectively enable such features for specified
    origins.</p>
  </div>
  <div class="example">
    <p>FastCorp Inc. wants to disable geolocation for all cross-origin child
    frames, except for a specific iframe. It can do so by delivering the
    following HTTP response header to define a feature policy:</p>
    <pre><a href="#feature-policy-header">Feature-Policy</a>: geolocation 'self'</pre>
    <p>and including an "<code>allow</code>" attribute on the iframe
    element:</p>
    <pre>&lt;iframe src="https://other.com/map" <a href="#iframe-allow-attribute">allow</a>="geolocation"&gt;&lt;/iframe&gt;</pre>
    <p>Iframe attributes can selectively enable features in certain frames, and
    not in others, even if those contain documents from the same origin.</p>
  </div>
</section>
<section>
  <h2 id="other-and-related-mechanisms">Other and related mechanisms</h2>
  <p>[[HTML5]] defines a <{iframe/sandbox}> attribute for <{iframe}> elements
  that allows developers to reduce the risk of including potentially untrusted
  content by imposing restrictions on content's abilities - e.g. prevent it
  from submitting forms, running scripts and plugins, and more. The
  [=sandbox=] directive defined by [[CSP2]] extends this capability to any
  resource, framed or not, to ask for the same set of restrictions - e.g. via an
  HTTP response header (<code>Content-Security-Policy: sandbox</code>). These
  mechanisms enable the developer to:</p>
  <ul>
    <li>Set and customize a sandbox policy on any resource via CSP.</li>
    <li>Set and customize individual sandbox policies on each
    <code>iframe</code> element within their application.</li>
  </ul>
  <p>However, there are several limitations to the above mechanism: the
  developer cannot automatically apply a policy across all contexts, which
  makes it hard or impossible to enforce consistently in some cases (e.g. due
  to third-party content injecting frames, which the developer does not
  control); there is no mechanism to selectively enable features that may be
  off by default; the sandbox mechanism automatically disables all sandbox
  features, and requires the developer to opt back in to each of them, so it is
  impossible to extend the set of sandbox features without significant
  compatibility risk.</p>
  <p>Feature Policy is intended to be used in combination with the sandbox
  mechanism (i.e. it does not duplicate feature controls already covered by
  sandbox), and provides an extensible mechanism that addresses the above
  limitations.</p>
</section>
<section>
  <h2 id="framwork">Framework</h2>
  <section>
    <h3 id="features">Policy-controlled Features</h3>
    <p>A <dfn export
    data-lt="policy-controlled feature">policy-controlled feature</dfn> is an
    API or behaviour which can be enabled or disabled in a document by referring
    to it in a <a>feature policy</a>.
    <div class="note">For brevity, policy-controlled features will often be
    referred to in this document simply as "Features". Unless otherwise
    indicated, the term "feature" refers to <a>policy-controlled features</a>.
    Other specifications, defining such features, should use the longer term to
    avoid any ambiguity.</div>
    <p><a>Policy-controlled features</a> are identified by tokens, which are
    character strings used in <a>policy directives</a>.
    <p>Each <a>policy-controlled feature</a> has a <a>default allowlist</a>,
    which defines whether that feature is available to top-level documents, and
    how access to that feature is inherited by cross-origin frames.</p>
    <p>A user agent has a set of <dfn>supported features</dfn>, which is the set
    of <a data-lt="policy-controlled feature">features</a> which it allows to be
    controlled through policies. User agents are not required to support every
    <a data-lt="policy-controlled feature">feature</a>.</p>
    <div class="note">
      The <a>policy-controlled features</a> themselves are not themselves part
      of this framework. A non-normative list of currently-defined features is
      maintained as a
      <a href="https://github.com/WICG/feature-policy/blob/gh-pages/features.md">companion
      document</a> alongside this specification.
    </div>
  </section>
  <section>
    <h3 id="policies">Policies</h3>
    <p>A {{Document}} has a <dfn>feature policy</dfn>, which consists of:</p>
    <ul>
      <li>A set of <a data-lt="inherited policy set">inherited policies</a>.
      </li>
      <li>A <a data-lt="declared policy">declared policy</a>.
      </li>
    </ul>
    <p>An <dfn>empty feature policy</dfn> has an <a>inherited policy set</a>
    which contains 'Enabled' for every <a>policy-controlled feature</a>
    available, and a <a>declared policy</a> which is an empty map.</p>
  </section>
  <section>
    <h3 id="inherited-policies">Inherited policies</h3>
    <p>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 <a>policy-controlled feature</a>. This inherited policy set
    determines the initial state (enabled or disabled) of each feature, and
    whether it can be controlled by a <a>declared policy</a> in the document.
    </p>
    <p>In a {{Document}} in a [=top-level browsing context=], the inherited
    feature set is based on defined defaults for each feature.</p>
    <p>In a {{Document}} in a [=nested browsing context=], the inherited feature
    set is based on the parent document's feature policy, as well as any
    <a href="#iframe-allow-attribute">allow attributes</a> defined on the
    browsing context container.</p>
    <p>An <dfn data-lt="inherited policy|inherited policies">inherited
    policy</dfn> declares a <a data-lt="policy-controlled feature">feature</a>
    as Enabled or Disabled.</p>
    <p>An <dfn>inherited policy set</dfn> for a {{Document}} is the set of
    <a>inherited policies</a> for each <a
    data-lt="policy-controlled feature">feature</a> available in that scope.</p>
  </section>
  <section>
    <h3 id="declared-policies">Declared policies</h3>
    <p>A <dfn data-lt="declared policy|declared feature policy">declared
    policy</dfn> is an ordered map from
    <a data-lt="policy-controlled feature">features</a> to <a>allowlists</a>.
    </p>
    <p>A {{Document}} is considered <dfn>feature-policy-aware</dfn> if it has a
    <a>declared policy</a> which is not empty.</p>
    <p>A {{Document}} which is not <a>feature-policy-aware</a> is considered
    <dfn>feature-policy-oblivious</dfn>.</p>
  </section>
  <section>
    <h3 id="header-policies">Header policies</h3>
    <p>A <dfn>header policy</dfn> is a list of <a>policy directives</a>
    delivered via an HTTP header with the document. This forms the document's
    <a>feature policy</a>'s <a>declared policy</a>.</p>
  </section>
  <section>
    <h3 id="container-policies">Container policies</h3>
    <p>In addition to the <a>header policy</a>, each frame has a <dfn>container
    policy</dfn>, which is a <a>policy directive</a>, which may be empty. The
    <a>container policy</a> can set by attributes on the browsing context
    container.</p>
    <p>The <a>container policy</a> for a frame influences the <a>inherited
    policy</a> of any document loaded into that frame. (See <a href=
    "#define-inherited-policy"></a>)</p>
    <div class="note">
      Currently, the <a>container policy</a> cannot be set directly, but is
      indirectly set by <code>iframe</code> "<a href=
      "#iframe-allowfullscreen-attribute"><code>allowfullscreen</code></a>",
      "<a href=
      "#iframe-allowpaymentrequest-attribute"><code>allowpaymentrequest</code></a>",
      and "<a href="#iframe-allow-attribute"><code>allow</code></a>"
      attributes. Future revisions to this spec may introduce a mechanism to
      explicitly declare the full <a>container policy</a>.
    </div>
  </section>
  <section>
    <h3 id="policy-directives">Policy directives</h3>
    <p>A <dfn data-lt="policy directive|policy directives">policy
    directive</dfn> is an ordered map, mapping <a>policy-controlled features</a>
    to corresponding <a>allowlists</a> of origins.</p>
    <p>A <a>policy directive</a> is represented in HTTP headers and HTML
    attributes as its ASCII serialization.</p>
  </section>
  <section>
    <h3 id="allowlists">Allowlists</h3>
    <p>A feature policy <dfn lt="allowlist|allowlists">allowlist</dfn> is
    conceptually a set of [=origins=]. An <a>allowlist</a> may be either:
    <ul>
      <li><dfn>The special value <code>*</code></dfn>, which represents every
      origin, or</li>
      <li>An <a>ordered set</a> of [=origins=]</li>
    </ul>
    <div class="note">
      The keywords <code>'self'</code>, <code>'src'</code>, and
      <code>'none'</code> 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.
    </div>
    <p>To determine whether an <a>allowlist</a> <dfn>matches</dfn> an origin
    <var>origin</var>, run these steps:
    <ol>
      <li>If the <a>allowlist</a> is <a>the special value <code>*</code></a>,
      then return true.</li>
      <li>Otherwise, for each <var>item</var> in the <a>allowlist</a>:
        <ol>
	  <li>If <var>item</var> is [=same origin-domain=] with
	  <var>origin</var>, then return true.</li>
	</ol>
      </li>
      <li>return false.</li>
    </ol>
  </section>
  <section>
    <h3 id="default-allowlists">Default Allowlists</h3>
    <p>Every <a>policy-controlled feature</a> has a <dfn export lt=
    "default allowlist|default allowlists">default allowlist</dfn>. The
    <a>default allowlist</a> controls the origins which are allowed to access
    the feature when used in a top-level document with no declared policy, and
    also determines whether access to the feature is automatically delegated to
    child documents.</p>
    <p>The <a>default allowlist</a> for a <a
    data-lt="policy-controlled feature">feature</a> is one of these values:</p>
    <dl>
      <dt><code>*</code></dt>
      <dd>The feature is allowed at the top level by default, and when allowed,
      is allowed by default to documents in child frames.</dd>
      <dt><code>'self'</code></dt>
      <dd>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.</dd>
      <dt>'none'</dt>
      <dd>The feature is disallowed at the top level by default, and is also
      disallowed by default to documents in child frames.</dd>
    </dl>
  </section>
</section>
<section>
  <h2 id="serialization">Feature Policy Serialization</h2>
  <section>
    <h3 id="ascii-serialization">ASCII serialization</h3>
    <p><a>Policy Directives</a> are represented in HTTP headers and in HTML
    attributes as ASCII text.</p>
    <pre class="abnf">
      <dfn>serialized-feature-policy</dfn> = <a>serialized-policy-directive</a> *(";" <a>serialized-policy-directive</a>)
      <dfn>serialized-policy-directive</dfn> = <a>feature-identifier</a> RWS <a>allow-list</a>
      <dfn>feature-identifier</dfn> = 1*( ALPHA / DIGIT / "-")
      <dfn>allow-list</dfn> = <a>allow-list-value</a> *(RWS <a>allow-list-value</a>)
      <dfn>allow-list-value</dfn> = <a>serialized-origin</a> / "*" / "'self'" / "'src'" / "'none'"
    </pre>
    <p><dfn><code>serialized-origin</code></dfn> is the
    <a>serialization of an origin</a>. 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.</p>
    <div class="note">
      The string "<code>'self'</code>" 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 feature policy.
    </div>
  </section>
</section>
<section>
  <h2 id="delivery">Delivery</h2>
  <section>
    <h3 id="feature-policy-http-header-field">Feature-Policy HTTP Header
    Field</h3>
    <p>The <dfn lt="feature-policy-header">Feature-Policy</dfn> HTTP header
    field can be used in the [=response=] (server to client) to communicate the
    <a>feature policy</a> that should be enforced by the client.</p>
    <p>The header's value is the <a href="#ascii-serialization"></a> of one or
    more <a>policy directive</a>s:.</p>
    <pre class="abnf">
      FeaturePolicy = <a>serialized-feature-policy</a> *("," <a>serialized-feature-policy</a>)
    </pre>
    <p>When the user agent receives a <code>Feature-Policy</code> header field,
    it MUST <a href="#process-response-policy">process</a> and <a>enforce</a>
    the serialized policy as described in <a href=
    "#integration-with-html"></a>.</p>
  </section>
  <section>
    <h3 id="iframe-allow-attribute">The <code>allow</code> attribute of the
    <code>iframe</code> element</h3>
    <pre class="idl">
partial interface HTMLIFrameElement {
    [CEReactions] attribute DOMString allow;
};</pre>
    <p><{iframe}> elements have an "<code>allow</code>" attribute, which
    contains an <a href="#serialized-policy-directive">ASCII-serialized policy
    directive</a>.</p>
    <p>The allowlist for the features named in the attribute may be empty; in
    that case, the default value for the allowlist is <code>'src'</code>, which
    represents the origin of the URL in the iframe's <{iframe/src}> attribute.
    </p>
    <p>When not empty, the "<code>allow</code>" attribute will result in adding
    an <a>allowlist</a> for each recognized
    <a data-lt="policy-controlled feature">feature</a> to the frame's
    <a>container policy</a>, when it is constructed.</p>
  </section>
  <section>
    <h3 id="legacy-attributes">Additional attributes to support legacy
    features</h3>
    <p>Some <a data-lt="policy-controlled feature">features</a> controlled by
    Feature Policy have existing iframe attributes defined. This specification
    redefines these attributes to act as declared policies for the iframe
    element.</p>
    <section>
      <h4 id="iframe-allowfullscreen-attribute">allowfullscreen</h4>
      <p>The "<code>allowfullscreen</code>" iframe attribute controls access to
      {{requestFullscreen()}}.</p>
      <p>If the iframe element has an "<code>allow</code>" attribute whose
      value contains the token "<code>fullscreen</code>", then the
      "<code>allowfullscreen</code>" attribute must have no effect.</p>
      <p>Otherwise, the presence of an "<code>allowfullscreen</code>" attribute
      on an iframe will result in adding an <a>allowlist</a> of <code>*</code>
      for the "<code>fullscreen</code>" feature to the frame's <a>container
      policy</a>, when it is constructed.</p>
      <div class="note">
        This is different from the behaviour of <code>&lt;iframe
        allow="fullscreen"&gt;</code>, and is for compatibility with existing
        uses of <code>allowfullscreen</code>. If
        <code>allow="fullscreen"</code> and <code>allowfullscreen</code> are
        both present on an iframe element, then the more restrictive allowlist
        of <code>allow="fullscreen"</code> will be used.
      </div>
    </section>
    <section>
      <h4 id="iframe-allowpaymentrequest-attribute">allowpaymentrequest</h4>
      <p>The "<code>allowpaymentrequest</code>" iframe attribute controls
      access to <a>paymentrequest</a>.</p>
      <p>If the iframe element has an "<code>allow</code>" attribute whose
      value contains the token "<code>payment</code>", then the
      "<code>allowpaymentrequest</code>" attribute must have no effect.</p>
      <p>Otherwise, the presence of an "<code>allowpaymentrequest</code>"
      attribute on an iframe will result in adding an <a>allowlist</a> of
      <code>*</code> for the "<code>payment</code>" feature to the frame's
      <a>container policy</a>, when it is constructed.</p>
      <div class="note">
        This is different from the behaviour of <code>&lt;iframe
        allow="payment"&gt;</code>, and is for compatibility with existing uses
        of <code>allowpaymentrequest</code>. If <code>allow="payment"</code>
        and <code>allowpaymentrequest</code> are both present on an iframe
        element, then the more restrictive allowlist of
        <code>allow="payment"</code> will be used.
      </div>
    </section>
    <section>
      <h4 id="iframe-allowusermedia-attribute">allowusermedia</h4>
      <p>The "<code>allowusermedia</code>" iframe attribute controls
      access to <a method>getUserMedia()</a>.</p>
      <p>If the iframe element has an "<code>allow</code>" attribute whose
      value contains the token "<code>payment</code>", then the
      "<code>allowusermedia</code>" attribute must have no effect.</p>
      <p>Otherwise, the presence of an "<code>allowusermedia</code>" attribute
      on an iframe will result in adding an <a>allowlist</a> of <code>*</code>
      for each of the "<code>camera</code>" and "<code>microphone</code>"
      features to the frame's <a>container policy</a>, when it is
      constructed.</p>
      <div class="note">
        This is different from the behaviour of <code>&lt;iframe
        allow="camera; microphone"&gt;</code>, and is for compatibility with
	existing uses of <code>allowusermedia</code>. If <code>allow="camera;
	microphone"</code> and <code>allowusermedia</code> are both present on
	an iframe element, then the more restrictive allowlist of
        <code>allow="camera; microphone"</code> will be used. Similarly, if only
	one of <code>allow="camera"</code> or <code>allow="microphone"</code> is
	present, then the more restrictive allowlist will be used for that
	feature, while the other will use the less restrictive <code>*</code>.
      </div>
    </section>
  </section>
</section>
<section>
  <h2 id="integrations">Integrations</h2>
  <p>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.</p>
  <section>
    <h3 id="integration-with-html">Integration with HTML</h3>
    <ol>
      <li>
        {{Document}} objects have a <a>Feature Policy</a>, which is initially
	<a data-lt="empty feature policy">empty</a>.
      </li>
      <li>Replace the existing step 12 of "Create a new browsing context" with
      with the following step:
        <ul>
          <li>
            Execute the <a href="#initialize-for-document">Initialize document's Feature Policy</a> algorithm on the {{Document}} object.
          </li>
        </ul>
      </li>
      <li>Replace the existing step 8 of "Initialising a new
      <code>Document</code> object" with the following step:
        <ul>
          <li>
            Execute the <a href="#initialize-from-response">Initialize document's Feature Policy from response</a> algorithm on the {{Document}} object and the response used to generate the document.
          </li>
        </ul>
      </li>
      <li>A <a>feature policy</a> is <dfn data-lt="enforce">enforced</dfn> for
      a {{Document}} by setting it as the {{Document}}'s <a>Feature Policy</a>.
      </li>
      <li>
        <p>The "[=allowed to use=]" algorithm is replaced with the following:
	</p>

        <p>To determine whether a {{Document}} object <var>document</var>
        is <dfn>allowed to use</dfn> the policy-controlled-feature
        <var>feature</var>, run these steps:</p>
        <ol>
         <li><p>If <var>document</var> has no [=browsing context=], then return
	 false.</p></li>
         <li><p>If <var>document</var>'s [=browsing context=]'s [=active
	 document=] is not <var>document</var>, then return false.</p></li>
         <li><p>If <var>document</var>'s <a>feature policy</a> <a
	 href="#is-feature-enabled">enables <var>feature</var> for the origin of
         <var>document</var></a>, then return true.<p></li>
         <li><p>Return false.</p></li>
        </ol>
      </li>
      <li><p>The <a href="#iframe-allow-attribute">allow attribute</a> is added
      to the IDL for the <{iframe}> element, with the description:</p>
      <p>The allow attribute, when specified, determines the <a>container
      policy</a> that will be used when the <a>feature policy</a> for the
      <{iframe}>'s [=nested browsing context=] is initialized. Its value must be
      the <a href="#ascii-serialization"></a> of a <a>policy directive</a>.</p>
      </li>
      <li><p>The description of the behavior of the <{iframe/allowfullscreen}>,
      <{iframe/allowpaymentrequest}> and <{iframe/allowusermedia}> attributes is
      changed to refer to this specification:
      <p>The <{iframe/allowfullscreen}> attribute is a boolean attribute. When
      specified, it indicates that {{Document}} objects in the <{iframe}>
      element's [=browsing context=] should be initialized with a <a>feature
      policy</a> which allows the <code>fullscreen</code> feature to be used
      from any origin. This is enforced by the <a
      href="#process-feature-policy-attributes">Process feature policy
      attributes</a> algorithm. Note that this will only allow use of the
      <code>fullscreen</code> feature if the <{iframe}> element's [=node
      document=] is also <a>allowed to use</a> <code>fullscreen</code>.
      <p>The <{iframe/allowpaymentrequest}> attribute is a boolean attribute.
      When specified, it indicates that {{Document}} objects in the <{iframe}>
      element's [=browsing context=] should be initialized with a <a>feature
      policy</a> which allows the <code>payment</code> feature to be used
      to make payment requests from any origin. This is enforced by the <a
      href="#process-feature-policy-attributes">Process feature policy
      attributes</a> algorithm. Note that this will only allow use of the
      <code>PaymentRequest</code> interface if the <{iframe}> element's [=node
      document=] is also <a>allowed to use</a> the feature.
      <p>The <{iframe/allowusermedia}> attribute is a boolean attribute. When
      specified, it indicates that {{Document}} objects in the <{iframe}>
      element's [=browsing context=] should be initialized with a <a>feature
      policy</a> which allows the <code>camera</code> and
      <code>microphone</code> features to be used to call
      <code>getUserMedia()</code> from any origin. This is enforced by the <a
      href="#process-feature-policy-attributes">Process feature policy
      attributes</a> algorithm. Note that this will only allow use of the
      <code>getUserMedia()</code> interface if the <{iframe}> element's [=node
      document=] is also <a>allowed to use</a> the feature.
      </li>
      <li>The <a
      href="https://html.spec.whatwg.org/multipage/iframe-embed-object.html#set-the-allow*-flags">set
      the allow* flags</a> algorithm is removed, as it is no longer referenced.
      </li>
    </ol>
    <div class="issue">
      Monkey-patching! As soon as we know that this is the direction we wish to
      pursue, upstream all of this.
    </div>
  </section>
</section>
<section>
  <h2 id="algorithms">Algorithms</h2>
  <section>
    <h3 id="process-response-policy">Process response policy</h3>
    <p>Given a [=response=] (<var>response</var>) and an [=origin=]
    (<var>origin</var>), this algorithm returns a <a>declared feature
    policy</a>.</p>
    <ol>
      <li>Abort these steps if the <var>response</var>’s <a
      for="response">header list</a> does not contain a [=header=] whose
      [=name=] is "<code>Feature-Policy</code>".
      </li>
      <li>Let <var>header</var> be the concatenation of the [=value=]s of all
      [=header=] fields in <var>response</var>’s <a
      for="response">header list</a> whose name is
      "<code>Feature-Policy</code>", separated by U+002C (,) (according to
      [RFC7230, 3.2.2]).</li>
      <li>Let <var>feature policy</var> be the result of executing <a href=
      "#parse-header"></a> on <var>header</var> and <var>origin</var>.
      </li>
      <li>Return <var>feature policy</var>.</li>
    </ol>
  </section>
  <section>
    <h3 id="parse-header">Parse header from <var>value</var> and
    <var>origin</var></h3>
    <p>Given a string (<var>value</var>) and an [=origin=] (<var>origin</var>)
    this algorithm will return a <a>declared feature policy</a>.</p>
    <ol>
      <li>Let <var>policy</var> be an empty ordered map.</li>
      <li>For each <var>element</var> returned by <a
      lt="split on commas">splitting <var>value</var> on commas</a>:
        <ol>
          <li>Let <var>directive</var> be the result of executing <a href=
          "#parse-policy-directive"></a> on <var>element</var> and
          <var>origin</var>
          </li>
          <li>Run <a href="#merge-directive-with-declared-policy"></a> on <var>
            directive</var> and <var>policy</var>.
          </li>
        </ol>
      </li>
      <li>Return <var>policy</var>.</li>
    </ol>
  </section>
  <section>
    <h3 id="parse-policy-directive">Parse policy directive from
    <var>value</var> and <var>origin</var></h3>
    <p>Given a string (<var>value</var>) and an [=origin=] (<var>origin</var>)
    this algorithm will return a <a>policy directive</a>.</p>
    <ol>
      <li>Let <var>directive</var> be an empty ordered map.</li>
      <li>For each <var>serialized-declaration</var> returned by <a
      lt="strictly split">strictly splitting <var>value</var> on the delimiter
      U+003B (;)</a>:
        <ol>
	  <li>Let <var>tokens</var> be the result of <a
	  lt="split on ascii whitespace">splitting
	  <var>serialized-declaration</var> on ASCII whitespace.</a></li>
	  <li>If <var>tokens</var> is an empty list, then continue.</li>
          <li>Let <var>feature-name</var> be the first element of
	  <var>tokens</var>.</li>
          <li>If <var>feature-name</var> does not identify any recognized
          <a>policy-controlled feature</a>, then continue.</li>
          <li>Let <var>feature</var> be the <a>policy-controlled feature</a>
	  identified by <var>feature-name</var>.</li>
          <li>Let <var>targetlist</var> be the remaining elements, if any, of
	  <var>tokens</var>.
          <li>Let <var>allowlist</var> be a new <a>allowlist</a>.
          </li>
          <li>If any element of <var>targetlist</var> is the string
	  "<code>*</code>", set <var>allowlist</var> to <a>the special value
	  <code>*</code></a>.</li>
          <li>Otherwise:
	    <ol>
	      <li>Set <var>allowlist</var> to an new <a>ordered set</a>.</li>
	      <li>For each <var>element</var> in <var>targetlist</var>:
                <ol>
                  <li>If <var>element</var> is an <a>ASCII case-insensitive</a>
		  match for the string "<code>'self'</code>", let result be
		  <var>origin</var>.</li>
                  <li>Otherwise, let <var>result</var> be the result of
		  executing the <a>URL parser</a> on <var>element</var>.</li>
                  <li>If <var>result</var> is not failure:
                    <ol>
                      <li>Let <var>target</var> be the origin of
                      <var>result</var>.</li>
                      <li>If <var>target</var> is not an opaque origin, append
                      <var>target</var> to <var>allowlist</var>.</li>
                    </ol>
                  </li>
                </ol>
              </li>
            </ol>
          </li>
          <li>Set <var>directive</var>[<var>feature</var>] to
	  <var>allowlist</var>.</li>
        </ol>
      </li>
      <li>Return <var>directive</var></li>
    </ol>
  </section>
  <section>
    <h3 id="merge-directive-with-declared-policy">Merge directive with declared
    policy</h3>
    <p>Given a policy directive (<var>directive</var>) and a declared policy
    (<var>policy</var>), this algorithm will modify <var>policy</var> to
    account for the new directive.</p>
    <ol>
      <li>For each <var>feature</var> → <var>allowlist</var> of
      <var>directive</var>:
        <ol>
          <li>If <var>policy</var> does not contain an allowlist for
          <var>feature</var>, then set <var>policy</var>[<var>feature</var>] to
	  <var>allowlist</var>.</li>
        </ol>
      </li>
    </ol>
  </section>
  <section>
    <h3 id="process-feature-policy-attributes">Process feature policy
    attributes</h3>
    <p>Given an element (<var>element</var>), this algorithm returns a
    <a>container policy</a>, which may be empty.</p>
    <ol>
      <li>Let <var>policy</var> be a new <a>policy directive</a>.
      </li>
      <li>Let <var>container policy</var> be the result of running <a href=
      "#parse-allow-attribute">Parse allow attribute</a> on the value of
        <var>element</var>'s <code>allow</code> attribute, with <var>container
	origin</var> set to the origin of <var>element</var>'s node document,
	and <var>target origin</var> set to the origin of the URL in
	<var>element</var>'s <code>src</code> attribute.
      </li>
      <li>If <var>element</var> is an <{iframe}> element:
        <ol>
          <li>If <var>element</var>'s <code>allowfullscreen</code> attribute is
          specified, and <var>container policy</var> does not contain an
	  allowlist for <code>fullscreen</code>,
            <ol>
              <li>Construct a new declaration for <code>fullscreen</code>, whose
              allowlist is <a>the special value <code>*</code></a>.</li>
              <li>Add <var>declaration</var> to <var>container policy</var>.
	      </li>
            </ol>
          </li>
          <li>If <var>element</var>'s <code>allowpaymentrequest</code>
          attribute is specified, and <var>container policy</var> does not
	  contain an allowlist for <code>payment</code>,
            <ol>
              <li>Construct a new declaration for <code>payment</code>, whose
              allowlist is <a>the special value <code>*</code></a>.</li>
              <li>Add <var>declaration</var> to <var>container policy</var>.
	      </li>
            </ol>
          </li>
          <li>If <var>element</var>'s <code>allowusermediarequest</code>
          attribute is specified:
	    <ol>
	      <li>If <var>container policy</var> does not contain an allowlist
	      for <code>camera</code>,
                <ol>
                  <li>Construct a new declaration for <code>camera</code>, whose
                  allowlist is <a>the special value <code>*</code></a>.</li>
                  <li>Add <var>declaration</var> to <var>policy</var>.</li>
                </ol>
              </li>
	      <li>If <var>policy</var> does not contain an allowlist for
	      <code>microphone</code>,
                <ol>
                  <li>Construct a new declaration for <code>microphone</code>,
                  allowlist is <a>the special value <code>*</code></a>.</li>
                  <li>Add <var>declaration</var> to <var>container policy</var>.
		  </li>
                </ol>
              </li>
            </ol>
          </li>
        </ol>
      </li>
      <li>Return <var>container policy</var>.</li>
    </ol>
  </section>
  <section>
    <h3 id="parse-allow-attribute">Parse allow attribute</h3>
    <p>Given a string (<var>value</var>), and two origins
    (<var>container origin</var> and <var>target origin</var>), this algorithm
    returns a <a>policy directive</a>.
    </p>
    <ol>
      <li>Let <var>directive</var> be an empty ordered map.</li>
      <li>For each <var>serialized-declaration</var> returned by <a
      lt="strictly split">strictly splitting <var>value</var> on the delimiter
      U+003B (;)</a>:
        <ol>
	  <li>Let <var>tokens</var> be the result of <a
	  lt="split on ascii whitespace">splitting
	  <var>serialized-declaration</var> on ASCII whitespace.</a></li>
	  <li>If <var>tokens</var> is an empty list, then continue.</li>
          <li>Let <var>feature-name</var> be the first element of
	  <var>tokens</var>.</li>
          <li>If <var>feature-name</var> does not identify any recognized
          <a>policy-controlled feature</a>, then continue.</li>
          <li>Let <var>feature</var> be the <a>policy-controlled feature</a>
	  identified by <var>feature-name</var>.</li>
          <li>Let <var>targetlist</var> be the remaining elements, if any, of
	  <var>tokens</var>.
          <li>Let <var>allowlist</var> be a new <a>allowlist</a>.
          </li>
          <li>If any element of <var>targetlist</var> is the string
	  "<code>*</code>", set <var>allowlist</var> to <a>the special value
	  <code>*</code></a>.</li>
          <li>Otherwise:
	    <ol>
	      <li>Set <var>allowlist</var> to an new <a>ordered set</a>.</li>
              <li>If <var>targetlist</var> is empty, append <var>target
	      origin</var> to <var>allowlist</var>.
	      <li>For each <var>element</var> in <var>targetlist</var>:
                <ol>
                  <li>If <var>element</var> is an <a>ASCII case-insensitive</a>
		  match for "<code>'self'</code>", let result be <var>container
		  origin</var>.</li>
                  <li>If <var>element</var> is an <a>ASCII case-insensitive</a>
		  match for "<code>'src'</code>", let result be <var>target
		  origin</var>.</li>
		  <li>Otherwise, let <var>result</var> be the result of
		  executing the <a>URL parser</a> on <var>element</var>.</li>
                  <li>If <var>result</var> is not failure:
                    <ol>
                      <li>Let <var>target</var> be the origin of
                      <var>result</var>.</li>
                      <li>If <var>target</var> is not an opaque origin, append
                      <var>target</var> to <var>allowlist</var>.</li>
                    </ol>
                  </li>
                </ol>
              </li>
            </ol>
          </li>
          <li>Set <var>directive</var>[<var>feature</var>] to
	  <var>allowlist</var>.</li>
        </ol>
      </li>
      <li>Return <var>directive</var></li>
    </ol>
  </section>
  <section>
    <h3 id="initialize-for-document">Initialize <var>document</var>'s Feature
    Policy</var></h3>
    <p>Given a Document object (<var>document</var>), this algorithm
    initialises <var>document</var>'s <a>Feature Policy</a></p>
    <ol>
      <li>Let <var>inherited policies</var> be a new ordered map.</li>
      <li>Let <var>declared policies</var> be a new ordered map.</li>
      <li>For each <var>feature</var> supported,
        <ol>
          <li>Let <var>isInherited</var> be the result of running <a href=
          "#define-inherited-policy"></a> on <var>feature</var> and
          <var>document</var>'s browsing context.
          </li>
          <li>Set <var>inherited policies</var>[<var>feature</var>] to
            <var>isInherited</var>.</li>
        </ol>
      </li>
      <li>Let <var>policy</var> be a new <a>feature policy</a>, with inherited
      policy set <var>inherited policies</var> and declared policy set
      <var>declared policies</var>.
      </li>
      <li>
        <a>Enforce</a> the policy <var>policy</var> on <var>document</var>.
      </li>
    </ol>
  </section>
  <section>
    <h3 id="initialize-from-response">Initialize <var>document</var>'s Feature
    Policy from <var>response</var></h3>
    <p>Given a [=response=] (<var>response</var>) and a Document
    (<var>document</var>), this algorithm populates <var>document</var>'s
    <a>Feature Policy</a></p>
    <ol>
      <li>Initialize <var>document</var>'s Feature Policy</li>
      <li>Let <var>inherited policies</var> be <var>document</var>'s Feature
      Policy's inherited policy set.</li>
      <li>Let <var>declared policies</var> be a new ordered map.</li>
      <li>Let <var>d</var> be the result of running <a
      href="#process-response-policy">Process response policy</a> on
      <var>response</var> and <var>document</var>'s origin.</li>
      <li>For each <var>feature</var> → <var>allowlist</var> of <var>d</var>:
        <ol>
          <li>If <var>inherited policies</var>[<var>feature</var>] is true, then
	  set <var>declared policies</var>[<var>feature</var>] to
	  <var>allowlist</var>.</li>
        </ol>
      </li>
      <li>Let <var>policy</var> be a new <a>feature policy</a>, with inherited
      policy set <var>inherited policies</var> and declared policy set
      <var>declared policies</var>.
      </li>
      <li>
        <a>Enforce</a> the policy <var>policy</var> on <var>document</var>.
      </li>
    </ol>
  </section>
  <section>
    <h3 id="define-inherited-policy">Define an inherited policy for
    <var>feature</var></h3>
    <p>Given a string (<var>feature</var>) and a browsing context
    (<var>context</var>), this algorithm returns the <a>inherited policy</a>
    for that feature.</p>
    <ol>
      <li>If <var>context</var> is a [=nested browsing context=]:
        <ol>
          <li>Let <var>parent</var> be <var>context</var>'s parent browsing
          context's active document.</li>
          <li>Let <var>origin</var> be <var>parent</var>'s [=origin=]</li>
          <li>Let <var>container policy</var> be the result of running
            <a href="#process-feature-policy-attributes"></a> on
            <var>context</var>'s browsing context container.
          </li>
          <li>If <var>feature</var> is a key in <var>container policy</var>:
            <ol>
              <li>If the <a>allowlist</a> for <var>feature</var> in
              <var>container policy</var> <a>matches</a> <var>origin</var>, and
              <var>parent</var>'s <a>inherited policy</a> for
              <var>feature</var> is Enabled, return Enabled.
              </li>
              <li>Otherwise return Disabled.</li>
            </ol>
          </li>
          <li>Otherwise, if feature is enabled in <var>parent</var> for
	  <var>origin</var>, return Enabled.
          </li>
          <li>Otherwise, return Disabled.</li>
        </ol>
      </li>
      <li>Otherwise, return Enabled.</li>
    </ol>
  </section>
  <section>
    <h3 id="is-feature-enabled">Is <var>feature</var> enabled in
    <var>document</var> for <var>origin</var>?</h3>
    <p>Given a feature (<var>feature</var>), a Document object
    (<var>document</var>), and an [=origin=] (<var>origin</var>), this algorithm
    returns "<code>Disabled</code>" if <var>feature</var> should be considered
    disabled, and "<code>Enabled</code>" otherwise.</p>
    <ol>
      <li>Let <var>policy</var> be <var>document</var>'s <a>Feature Policy</a>
      </li>
      <li>If <var>policy</var>'s <a>inherited policy</a> for <var>feature</var>
      is Disabled, return "<code>Disabled</code>".</li>
      <li>If <var>feature</var> is present in <var>policy</var>'s <a>declared
      policy</a>:
        <ol>
          <li>If the <a>allowlist</a> for <var>feature</var> in
          <var>policy</var>'s <a>declared policy</a> <a>matches</a>
          <var>origin</var>, then return "<code>Enabled</code>".
          </li>
          <li>Otherwise return "<code>Disabled</code>".</li>
        </ol>
      </li>
      <li>If <var>feature</var>'s <a>default allowlist</a> is
      <code>*</code>, return "<code>Enabled</code>".
      </li>
      <li>If <var>feature</var>'s <a>default allowlist</a> is
      <code>'self'</code>, and <var>origin</var> is [=same origin-domain=]
      with <var>document</var>'s origin, return "<code>Enabled</code>".
      </li>
      <li>Return "<code>Disabled</code>".</li>
    </ol>
  </section>
</section>
<section>
  <h2 id="iana-considerations">IANA Considerations</h2>
  <p>The permanent message header field registry should be updated with the
  following registration [[!RFC3864]]:</p>
  <dl>
    <dt>Header field name</dt>
    <dd>Feature-Policy</dd>
    <dt>Applicable protocol</dt>
    <dd>http</dd>
    <dt>Status</dt>
    <dd>standard</dd>
    <dt>Author/Change controller</dt>
    <dd>W3C</dd>
    <dt>Specification document</dt>
    <dd>
      <a href="">Feature Policy API</a>
    </dd>
  </dl>
</section>
<section id="privacy" class="informative">
  <h2 id="privacy-and-security">Privacy and Security</h2>
  <p class="issue">TODO</p>
</section>