Safety
Document-Policy vs Permissions-Policy for Page Features
July 17, 2023
Document-Policy vs Permissions-Policy for page features is two structured-header policies, not one misspelled header. Permissions-Policy (and legacy Feature-Policy) allowlists powerful APIs: camera, microphone, geolocation, payment, and related ch-* Client Hints. Document-Policy configures document-level behaviors such as force-load-at-top, unsized-media, and js-profiling — knobs for layout and profiling, not 'who may use the camera.' Marketing sites should lock unused Permissions-Policy features first. Document-Policy is optional hardening. RoastMyOpsec reads Permissions-Policy on the landing HTML as part of the free header pack. It does not score Document-Policy, does not prompt for device permissions, and does not enable js-profiling.
The practical difference
Permissions-Policy answers 'may this origin (or iframe) use this powerful API?' Document-Policy answers 'how should this document behave for these named features?' Mixing them up is how teams paste a Document-Policy from a blog and think camera is off.
iframe allow= is a third control for children. It does not replace either header on the parent. See Feature-Policy vs Permissions-Policy for the rename.
How to choose what to ship
Homepage: Permissions-Policy that disables unused device APIs. Checkout that needs payment: allow it on that route. Document-Policy: add force-load-at-top if you care about scroll restoration attacks on fragments; skip js-profiling in production. Do not copy an experimental policy from a lab origin onto the brand CDN without a browser matrix.
| Header | Typical job | Roast today | Takeaway |
|---|---|---|---|
| Permissions-Policy | Camera, geo, payment, many ch-* | Read on landing HTML | Lock unused APIs |
| Feature-Policy | Legacy grammar | Not a substitute | See Feature-Policy vs Permissions-Policy |
| Document-Policy | Document configuration features | Not scored | Optional; not a camera lock |
| iframe allow= | Child frame APIs | Not parsed | Complement, not a parent policy |
What the roast can prove
Permissions-Policy on the primary response can surface in the header pack. Missing Document-Policy is not a finding. Confirm device APIs in templates. Pair with Client Hints if you also Accept-CH high-entropy fields.
Common mistakes
The first mistake is Document-Policy with no Permissions-Policy and calling the site 'locked down.'
The second mistake is enabling js-profiling on production HTML.
The third mistake is treating Document-Policy as CSP.
Free audit the URL you own
RoastMyOpsec is a defensive public-surface roast: headers, cookies, sensitive paths, and more — no exploit payloads. Start with the free audit, then open the vault if the blurred findings look expensive.
Free audit nowFAQ
- Does Document-Policy replace Permissions-Policy?
- No. They name different features. Disable unused device APIs with Permissions-Policy.
- Should brochure sites set Document-Policy?
- Only if you need a listed document feature. Missing it is not a roast F.
- Does RoastMyOpsec score Document-Policy?
- No. It reads Permissions-Policy on the landing response. No device prompts.