Document-Policy
Learn how Document-Policy configures per-document behaviours like disabling document.write and flagging oversized media.
Document-Policy is an experimental header that configures behaviours of the document itself, such as disallowing document.write, blocking synchronous XMLHttpRequest, or flagging oversized images. It is a hardening and quality mechanism rather than a primary security control, and it can run in an enforcing or a report-only mode.
What is Document-Policy?#
Document-Policy lets you set a list of configuration points that constrain how a single document behaves. Unlike Permissions-Policy, which delegates powerful features such as camera or geolocation to origins and frames, Document-Policy configures the document's own behaviours. Support is currently limited to Chromium browsers and the feature is considered experimental, so treat it as defense in depth rather than a required control.
- Configures per-document behaviours, not delegated features
- Each directive is a configuration point with a boolean or numeric value
- Chromium only, and still marked experimental
- Can enforce, or run in report-only mode to observe without breaking anything
Common configuration points#
Document-Policy accepts a structured list of directives. Support varies by browser and unknown directives are ignored.
- document-write=?0 disables document.write and document.writeln
- sync-xhr=?0 disables synchronous XMLHttpRequest
- unsized-media=?0 requires explicit width and height on media to reduce layout shift
- lossy-images-max-bpp and lossless-images-max-bpp flag oversized images by bytes per pixel
Report-Only mode#
Rather than enforcing a policy immediately, you can deploy Document-Policy-Report-Only to observe which configuration points would be violated. Reports are delivered through the Reporting API to the endpoint you name in the Reporting-Endpoints header, so you can measure impact before you enforce.
Because Document-Policy can change how existing pages behave, deploy Document-Policy-Report-Only first, review the reports, then switch to the enforcing header.
# Observe without enforcing
Reporting-Endpoints: default="https://example.com/reports"
Document-Policy-Report-Only: document-write=?0
# Enforce once you have validated impact
Document-Policy: document-write=?0Implementation Guide#
Set the header at your server or edge, combining the directives you want. Test thoroughly, since disabling behaviours like document.write can break third-party scripts.
# Apache
Header always set Document-Policy "document-write=?0, sync-xhr=?0"
# Nginx
add_header Document-Policy "document-write=?0, sync-xhr=?0" always;
# Node.js / Express
app.use((req, res, next) => {
res.setHeader('Document-Policy', 'document-write=?0, sync-xhr=?0');
next();
});Best Practices#
Adopt Document-Policy gradually and only where it adds value for your codebase.
- Deploy in report-only mode first and review reports before enforcing
- Enable one configuration point at a time so you can attribute breakage
- Remember support is Chromium only, so it complements rather than replaces other controls
- Pair it with a strong Content-Security-Policy for actual injection protection
Implementation Examples#
Disable document.write
Document-Policy: document-write=?0Blocks document.write and document.writeln
Explanation: Prevents scripts from injecting content with document.write, which is slow and a minor injection surface.
Report-only
Document-Policy-Report-Only: document-write=?0, sync-xhr=?0Observes violations without enforcing
Explanation: Sends reports to your Reporting-Endpoints default endpoint so you can measure impact before enforcing.
Key Directives#
document-write=?0
Disables document.write and document.writeln
document-write=?0sync-xhr=?0
Disables synchronous XMLHttpRequest
sync-xhr=?0unsized-media=?0
Requires explicit dimensions on media
unsized-media=?0References#
Test Your Document-Policy Configuration
Scan your site to check if Document-Policy is properly configured.