Wiki · Concept · Last reviewed June 25, 2026

Document Policy

Document Policy is a WICG web-platform framework for configuring document behavior through policy headers, required iframe policies, and report-only testing.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser security, document policy, reporting, iframes, agents

Definition

Document Policy is a Web Incubator Community Group draft for configuring web platform behavior at the document level. The draft describes it as a framework for designing configurable features and allowing web developers to configure those features as part of site deployment. It is not the same as Permissions Policy, although the two mechanisms grew from related browser policy work.

The key unit is a configuration point: a named web platform behavior or API setting that can be enabled, disabled, or configured. Unlike Permissions Policy, whose features are boolean and mainly about delegation to frames, Document Policy can model configuration values with boolean, integer, float, or enum types. That makes it suited to behavior constraints that are not simply "allowed" or "blocked."

How It Works

The draft defines several delivery surfaces. Document-Policy is a response header for the policy enforced on the current document. Document-Policy-Report-Only lets a site test a policy and receive reports without enforcement. Require-Document-Policy is a response header for communicating a minimum required policy to nested content. Sec-Required-Document-Policy is a request header that advertises the policy a returned nested document must satisfy.

Document Policy uses Structured Headers dictionary syntax. A directive names either a configuration point or the special token *. Directives can include a report-to parameter, tying violations to reporting endpoints. The draft also sketches an iframe policy attribute, which would allow an embedder to impose a required policy on nested content.

The required-policy flow is the most important agent-governance idea. If a frame has a required policy, the outgoing document request advertises that requirement. If the response does not contain a compatible policy, the fetch can fail. This is related to embedded enforcement patterns in content security policy, but aimed at document behavior rather than only resource origin rules.

Agent Context

Document Policy matters for browser agents because agents increasingly work inside nested, tool-rich web pages. A coding workspace may embed previews, documentation, dashboards, terminal panes, payment forms, and model-generated widgets. A policy that constrains document behavior or requires nested content to accept a condition can turn a vague page failure into auditable evidence.

For an agent, the wrong response is to treat every failed frame as a network problem. The failure may mean the embedder required a document behavior contract and the embedded response did not accept it. A careful agent runtime should surface that fact before retrying through a proxy, opening the frame in a new tab, or using a server-side fetch that bypasses the browser boundary.

Governance Use

Governance use begins with separating policy intent from policy support. The site owner may intend to restrict a behavior, but actual enforcement depends on browser implementation and on whether the relevant configuration point is defined and supported. Reviewers should record both the declared policy text and the observed browser behavior.

For AI-mediated browsing, Document Policy belongs beside Reporting API, Content Security Policy, Permissions Policy, iframe sandboxing, and origin isolation. Each mechanism answers a different question. Document Policy is about configurable document behavior and required policies for nested documents; it is not a general grant of user authority.

Limits

Document Policy is a draft, not a universal browser guarantee. The WICG document itself contains open issues and integration notes, and the configuration points are expected to be defined by the specifications for the underlying APIs or behaviors. A site should not claim compliance merely because it emits a header that a browser ignores.

It also does not replace server authorization, user consent, secure coding, or agent tool permissions. A required policy can prevent a nonconforming nested document from loading in a supporting browser. It cannot decide whether a user should trust the embedder, whether the embedded party is legitimate, or whether a model should act on information inside the frame.

Minimum Evidence Record

For an incident or audit, preserve the top-level URL, nested frame URL with secrets removed, exact Document-Policy, Document-Policy-Report-Only, Require-Document-Policy, and Sec-Required-Document-Policy values, iframe policy value if present, browser and version, reporting endpoint name, task identifier, agent action, and whether the frame load failed or produced a report.

Source Discipline

Use the WICG Document Policy draft for claims about the model, headers, report-only mode, required policies, and iframe policy attribute. Use the WICG explainer for historical motivation and design framing. Use W3C Permissions Policy separately when comparing delegation-oriented browser feature control. Avoid treating Chrome status pages, browser experiments, or old Feature Policy references as proof of broad interoperable support.

Spiralist Reading

Spiralism reads Document Policy as a contract surface for the page's behavior, not a moral statement about the page. It lets a document say: these are the conditions under which this behavior may occur here.

The agent-era lesson is that contracts should remain visible. When an automated browser meets a required policy, the system should preserve the condition rather than silently route around it. A broken embed can be a useful refusal, not just a defect.

Sources

Return to Wiki