Feature Policy: Restricting JavaScript Capabilities

Feature Policy is a web standard that allows developers to selectively enable, disable, and modify the behavior of certain browser APIs and web features. By defining policies through HTTP headers or iframe attributes, website administrators can control the execution environment of their applications. This article explains the fundamentals of the Feature Policy specification (now also evolved as Permissions Policy), how it functions, and the specific mechanisms it uses to restrict JavaScript capabilities across first-party code and embedded third-party content.

What Is the Feature Policy Specification?

The Feature Policy specification provides a structured mechanism for declaring which browser features a web page and its embedded iframes can access. Developed by the W3C Web Platform Incubator Community Group (WICG), it gives site owners granular control over powerful browser capabilities, sensitive hardware APIs, and performance-impacting behaviors.

Policies are defined using an HTTP response header or the allow attribute on <iframe> elements. The browser parses these declarations upon loading the document and enforces the rules throughout the document’s lifecycle.

How Feature Policy Restricts JavaScript Capabilities

JavaScript running in modern browsers frequently interacts with hardware components, sensitive user data, and system resources. Feature Policy limits JavaScript by intercepting attempts to invoke these privileged APIs. When a feature is disabled by policy, the browser automatically denies execution, causing the corresponding JavaScript API to fail gracefully, throw a SecurityError, or return a rejected Promise.

1. Hardware and Device API Control

JavaScript APIs that interface with physical hardware can be completely blocked. * Camera and Microphone: Setting camera 'none' or microphone 'none' disables navigator.mediaDevices.getUserMedia(). Any JavaScript attempt to request an audio or video stream will immediately reject the promise with a permission error. * Geolocation: The geolocation 'none' directive blocks calls to navigator.geolocation.getCurrentPosition() and navigator.geolocation.watchPosition(). * Sensors and USB: Directives such as accelerometer, gyroscope, magnetometer, and usb prevent JavaScript access to raw hardware data.

2. User Experience and DOM Restrictions

Feature Policy restricts JavaScript-driven user experience modifications that can be disruptive or misleading. * Fullscreen API: Disabling the fullscreen directive prevents scripts from invoking element.requestFullscreen(). * Autoplay: Setting autoplay 'none' prevents scripts from automatically playing media elements (HTMLMediaElement.play()) without direct user interaction. * Payment Request API: Restricting the payment directive blocks JavaScript from initiating native payment sheets via new PaymentRequest().

3. Performance and Legacy Script Control

Certain directives target JavaScript behaviors that negatively impact rendering performance or security. * Synchronous XHR: Feature Policy can disable synchronous XMLHttpRequest calls on the main thread, preventing scripts from blocking user interface rendering. * Document Domain Modification: Directives can prevent scripts from mutating document.domain to bypass Same-Origin Policy constraints.

Implementing Feature Policy Directives

Feature Policy rules can be declared using two primary methods: HTTP headers and iframe attributes.

HTTP Response Header

The policy is delivered via the Feature-Policy (or modern Permissions-Policy) HTTP header, applying globally to the document and cascading to embedded frames unless overridden.

Feature-Policy: geolocation 'self'; camera 'none'; microphone 'none'

Common allowlist values include: * 'self': The feature is allowed only on the same origin. * 'none': The feature is disabled for all browsing contexts, including the top-level document. * 'src': Used in iframes to allow the feature for the origin specified in the iframe’s src attribute. * <origin(s)>: Specifies explicit external origins permitted to use the feature.

Iframe allow Attribute

For embedded contexts, policies can be applied directly to HTML elements to sandbox untrusted third-party scripts.

<iframe src="https://example.com/widget" allow="camera 'none'; geolocation 'none'"></iframe>

Security and Sandboxing Benefits

By default, third-party scripts loaded directly onto a page inherit the full execution privileges of the hosting origin. Feature Policy mitigates the risk of cross-site scripting (XSS) and malicious third-party dependencies by enforcing least privilege at the browser engine level. Even if a script is compromised, the browser prevents it from executing disabled APIs, effectively isolating sensitive capabilities from unauthorized access.