Document-Policy header, per-document rules and reports

Document-Policy sets per-document configuration points such as js-profiling, with optional violation reporting.

Document-Policy configures behavior and feature constraints for a single document through named configuration points, for example enabling the JS Self-Profiling API with js-profiling. Unlike Permissions-Policy, it is not delegated to subframes in the same way, so it is a per-document set of guardrails.

Experimental

Document-Policy is a WICG Community Group draft, not a W3C standard, and is implemented only in Chromium, where most configuration points sit behind flags; only js-profiling is enabled by default. The set of configuration points is implementation-defined and can change, so do not rely on a fixed directive list.

The usable configuration today enables the JS Self-Profiling API:

Document-Policy: js-profiling

How Document-Policy works

The header is a structured-field dictionary of configuration points. Each point has a typed value, a boolean (?0 off, ?1 on), an integer, a float, or an enum, and each point governs one behavior of the document. Which points exist is defined by the browser, not a fixed standard registry.

How to configure Document-Policy

Configuration point	Status	What it does
`js-profiling`	🧪 Experimental	Enables the JS Self-Profiling API. The one configuration point enabled by default in Chromium.
`include-js-call-stacks-in-crash-reports`	🧪 Experimental	Gates whether crash reports include JavaScript call stacks.

Document-Policy is a WICG draft, implemented only in Chromium, and most of its configuration points sit behind flags. The two points above are the ones worth knowing today; treat any longer list as unstable, and confirm a point works in your target browsers before relying on it.

Report-only mode

Reporting-Endpoints: doc-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Document-Policy-Report-Only: js-profiling;report-to=doc-endpoint

Each point can carry a report-to parameter; *;report-to=endpoint sets a default endpoint for all points, and report-to=none disables reporting for a point. The draft defines Document-Policy-Report-Only, but end-to-end report delivery in Chromium is not confirmed, so verify that reports actually arrive before you build on them.

What it protects against

Today, less than the name suggests. The two usable configuration points gate diagnostics rather than block attacks: js-profiling controls whether a document can profile its own JavaScript, and include-js-call-stacks-in-crash-reports controls whether crash reports carry call stacks. The value of the header is opting into those capabilities deliberately, per document.

Insecure configurations to avoid

Leaving a known-risky configuration point unconstrained defeats the purpose, and, as with any reporting feature, pointing report-to at a host you do not control leaks report data. Constrain the points you care about explicitly rather than assuming a safe default.

Known bypasses and limitations

There is no normative registry of configuration points, support is Chromium-only, and the policy is not delegated to subframes the way Permissions-Policy is, so it governs the document it is set on rather than a whole frame tree.

Risks

Because the feature set is unstable, a point you depend on may change or be removed between browser versions. Keep constraints in Report-Only where you can, and watch the reports before enforcing.

Recommendation

Document-Policy: js-profiling

Treat Document-Policy as experimental. Adopt only the two configuration points that work in Chromium today, js-profiling and include-js-call-stacks-in-crash-reports, and only behind testing in your target browsers. Prefer Document-Policy-Report-Only where it is available; the draft defines it, but end-to-end delivery in Chromium is unconfirmed, so confirm reports arrive before relying on them.

Reporting

A per-point report-to parameter routes that point's violations to a named endpoint, and the browser emits the document-policy-violation report. One related point, include-js-call-stacks-in-crash-reports, enriches the crash report with a JS stack, as covered in browser crash and unresponsive reports. CentralCSP collects the stream.

Browser support

Chromium-based browsers only; experimental, with no normative registry of configuration points.

Sources

WICG, Document Policy

Document-Policy