tree: 5dbe954f14951398a585e9a50d4fb24320c5ce2b [path history] [tgz]
  1. OWNERS
  2. README.md
  3. feature_policy.cc
  4. feature_policy.typemap
  5. feature_policy_mojom_traits.cc
  6. feature_policy_mojom_traits.h
  7. feature_policy_unittest.cc
  8. policy_value.cc
third_party/blink/common/feature_policy/README.md

Feature Policy Guide

How to add a new feature to feature policy

Feature policy (see spec) is a mechanism that allows developers to selectively enable and disable various browser features and APIs (e.g, “vibrate”, “fullscreen”, “usb”, etc.). A feature policy can be defined via a HTTP header and/or an iframe “allow” attribute.

Below is an example of a header policy (note that the header should be kept in one line, split into multiple for clarity reasons):

Feature-Policy: vibrate 'none'; geolocation 'self' https://example.com; camera *
  • vibrate is disabled for all browsing contexts;
  • geolocation is disabled for all browsing contexts except for its own origin and those whose origin is “https://example.com”;
  • camera is enabled for all browsing contexts.

Below is an example of a container policy:

<iframe allowpaymentrequest allow='vibrate; fullscreen'></iframe>

OR

<iframe allowpaymentrequest allow="vibrate 'src'; fullscreen 'src'"></iframe>
  • payment is enabled (via allowpaymentrequest) on all browsing contexts within the iframe;
  • vibrate and fullscreen are enabled on the origin of the URL of the iframe's src attribute.

Combined with a header policy and a container policy, inherited policy defines the availability of a feature. See more details for how to define an inherited policy for feature

Adding a new feature to feature policy

A step-to-step guide with examples.

Shipping features behind a flag

There are currently two runtime-enabled flags: FeaturePolicy (status: stable) and FeaturePolicyExperimentalFeatures (status: experimental). If the additional feature is unshipped, or if the correct behaviour with feature policy is undetermined, consider shipping the feature behind a flag (i.e., FeaturePolicyExperimentalFeatures).

Define new feature
  1. Feature policy features are defined in third_party/blink/public/common/feature_policy/feature_policy_feature.h. Add the new feature enum with a brief decription about what the feature does in the comment, right above LAST_FEATURE

  2. Append the new feature enum with a brief description as well in third_party/blink/public/mojom/feature_policy/feature_policy.mojom

  3. Update third_party/blink/public/mojom/feature_policy/feature_policy.mojom_traits.h to include the new feature

  4. Update third_party/blink/renderer/platform/feature_policy/feature_policy.cc: Add your ("feature-name", FeatureEnumValue) mapping to GetDefaultFeatureNameMap() (note: “feature-name” is the string web developers will be using to define the policy in the HTTP header and iframe “allow” attribute).

  • If shipping behind the flag (FeaturePolicyExperimentalFeatures): Add the mapping inside the if (RuntimeEnabledFeatures::FeaturePolicyExperimentalFeaturesEnabled()) stament;
  • Otherwise: Add the mapping above the if statment.
Integrate the feature behaviour with feature policy
  1. Add a case for the feature in IsSupportedInFeaturePolicy() (which checks if feature policy is enabled and the feature is supported in feature policy):
  • If shipping behind the flag (FeaturePolicyExperimentalFeatures):

    return RuntimeEnabledFeatures::FeaturePolicyExperimentalFeaturesEnabled();

  • Otherwise:

    return true;

  1. Implement the behaviour of the new feature for the 3 cases:
  • Default behaviour without feature policy i.e,

    if (!IsSupportedInFeaturePolicy(...)) { ... }

  • When feature policy is enabled and feature is enabled by feature policy; i.e,

    if (!IsSupportedInFeaturePolicy(...)) { if (frame->IsFeatureEnabled(...)) { ... } }

  • When feature policy is enabled and feature is disabled by feature policy. i.e,

    if (IsSupportedInFeaturePolicy(...)) { if (!frame->IsFeatureEnabled(...)) { ... } }

  1. Examples:
  • vibrate: NavigatorVibration::vibrate()
  • payment: AllowedToUsePaymentRequest()
  • usb: USB::getDevices()
Write web-platform-tests

To test the new feature with feature policy, refer to third_party/blink/web_tests/external/wpt/feature-policy/README.md for instructions on how to use the feature policy test framework.

Contacts

For more questions, please feel free to reach out to: loonybear@chromium.org iclelland@chromium.org