COEP and COOP reporting documentation #39880

hamishwillee · 2025-06-10T05:59:13Z

COOP and COEP use the reporting API to report violations. This adds docs.

COEPViolationReportBody - report structure for COEP violations
COOPViolationReportBody - report structure for COOP violations
Update Reporting API docs everywhere to include links to these
Cross-Origin-Embedder-Policy-Report-Only - add report-to
Cross-Origin-Embedder-Policy - add report-to
Cross-Origin-Opener-Policy - add report-to
Cross-Origin-Opener-Policy-Report-Only - add report-to
BCD everywhere Reporting API Report body - how do I document the COEP body report? browser-compat-data#27021

Fixes #39814

github-actions · 2025-06-10T06:01:05Z

Preview URLs (13 pages)

Flaws (30)

Note! 4 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/COEPViolationReportBody
Title: COEPViolationReportBody
Flaw count: 3

macros:
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only

URL: /en-US/docs/Web/API/COEPViolationReportBody/disposition
Title: COEPViolationReportBody: disposition property
Flaw count: 1

macros:
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only

URL: /en-US/docs/Web/API/COOPViolationReportBody
Title: COOPViolationReportBody
Flaw count: 15

macros:
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy-Report-Only
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/referrer
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/property
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/openerURL
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/openedWindowURL
- and 10 more flaws omitted

URL: /en-US/docs/Web/API/COOPViolationReportBody/columnNumber
Title: COOPViolationReportBody: columnNumber property
Flaw count: 1

broken_links:
- /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-OPener-Policy is ill cased

URL: /en-US/docs/Web/API/COOPViolationReportBody/disposition
Title: COOPViolationReportBody: disposition property
Flaw count: 1

macros:
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only

URL: /en-US/docs/Web/API/COOPViolationReportBody/effectivePolicy
Title: COOPViolationReportBody: effectivePolicy property
Flaw count: 1

macros:
- Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy-Report-Only

URL: /en-US/docs/Web/API/COOPViolationReportBody/lineNumber
Title: COOPViolationReportBody: lineNumber property
Flaw count: 1

broken_links:
- /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-OPener-Policy is ill cased

URL: /en-US/docs/Web/API/COOPViolationReportBody/sourceFile
Title: COOPViolationReportBody: sourceFile property
Flaw count: 1

broken_links:
- /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-OPener-Policy is ill cased

URL: /en-US/docs/Web/API/COOPViolationReportBody/type
Title: COOPViolationReportBody: type property
Flaw count: 6

macros:
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/referrer
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/referrer
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/property
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/openerURL
- Can't resolve /en-US/docs/Web/API/COOPViolationReportBody/openedWindowURL
- and 1 more flaws omitted

External URLs (2)

URL: /en-US/docs/Web/API/COEPViolationReportBody
Title: COEPViolationReportBody

https://developer.chrome.com/docs/capabilities/web-apis/reporting-api (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/COOPViolationReportBody
Title: COOPViolationReportBody

https://developer.chrome.com/docs/capabilities/web-apis/reporting-api (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-06-17 08:29:20)

hamishwillee · 2025-06-10T06:04:13Z

files/en-us/web/api/coepviolationreportbody/index.md

+<!--
+- {{domxref("COEPViolationReportBody.destination")}} {{ReadOnlyInline}}
+  - : A string indicating the parent navigable for which loading was was blocked: `"iframe"`.
+-->


When I run https://wpt.live/html/cross-origin-embedder-policy/reporting-navigation.https.html I get

additional property destination on the report. This isn't in the spec.

@yoavweiss Do you know the story here? Normally we'd document the property here and in browser compatibility data. The question really is whether this is "coming in to the spec" or "didn't make it into the spec". Do we know the history?

I don't, but @camillelamy might

Thanks. My current plan is to mark this as non-standard in the browser compatibility data.

I will remove this from here unless @camillelamy is able to provide information - because there is no way for me to be canonical about it.
But since it is in compatibility data it is clear we haven't just forgotten about it.

I think Chrome has another potential value which is worker, when the issue is coming from a worker initialization being blocked. That said, I think what we're doing with COEP on workers is non optimal, so I wanted to raise the issue and modify that. That would remove the need for this field. So I think it is fine to mark it as non standard.

Ok I looked it up some more, and in Chrome destination is the type of resource being loaded, including iframes. But for subresources this can be different. I was not involved in the COEP spec nor in the implementation of COEP reporting in Chrome, so I am not sure of the intent of either here.

hamishwillee · 2025-06-10T06:05:13Z

files/en-us/web/api/coepviolationreportbody/index.md

+
+## Instance properties
+
+- {{domxref("COEPViolationReportBody.type")}} {{ReadOnlyInline}}


When I run https://wpt.live/html/cross-origin-embedder-policy/reporting-navigation.https.html I get another value for this than the values in the spec: corp.

@yoavweiss Do you know the story here? Is this value deprecated, going/coming?
Are there other values we know about?

Again, @camillelamy may know

Cool. Again, it's non-standard. In this case we might just not mention it at all unless we can get some information.

Ok, so it seems in Chrome we have three values corp, navigation and worker initialization. The comment above about worker initialization applies. However, I think it makes sense to distinguish between corp and navigation, and I am surprised it is not in the spec. corp is used when a subresource is blocked. navigation when a navigation is blocked. And worker initialization when a web worker script is blocked from loading (but I think this one should go away and the script should never be blocked but inherit COEP from its creator).

hamishwillee · 2025-06-10T06:07:49Z

files/en-us/web/api/coepviolationreportbody/index.md

+> [!NOTE]
+> This object does not derive from {{domxref("ReportBody")}} (unlike other {{domxref("Report.body")}} values).


This is necessary because until now we could say that a body was derived from ReportBody. But according to whatwg/html#11365 even if this is true, that will likely be an abstract dictionary.
Further, this object is not named in the spec. I have chosen this name.

FYI if Report also ends up being an abstract base dictionary we might even end up defining this as a "report" rather than a "reportbody". Too early to say.

Both Report and ReportBody are now specified as dictionaries: https://www.w3.org/TR/reporting-1/#interface-reporting-observer

But this is somewhat aspirational and isn't how they're implemented yet: https://issues.chromium.org/issues/424210695

@yoavweiss Thanks. This is going to make things complicated.

TLDR; I'm probably going to continue documenting this as COEPViolationReportBody and COOPViolationReportBody for now while we wait for the dust to settle. But will discuss in the writing team.

I'm trying to work out what compatibility data should do in mdn/browser-compat-data#27047 (comment) - it is messy because BCD doesn't document dictionaries, but on the other hand, they can only remove things 2 years after they are removed from the web platform. It is going to be confusing for all concerned.

For docs I'm not entirely certain what will happen. Generally Docs don't document dictionaries either, but if we do, we tend to document only the top level dictionaries.
Where I see us going in the longer term is having dictionaries such as CSPViolationReport, COEPViolationReport.
We could do this for the COEP/COOP reports because the spec doesn't indicate any derivation for them at all - it just refers to "an object".

hamishwillee · 2025-06-10T06:12:17Z

files/en-us/web/api/coepviolationreportbody/index.md

+There are two may causes of violations, which are indicated by the value of the {{domxref("Report.type","type")}} property.
+The first is a `navigation` violation, which is caused when an {{htmlelement("iframe")}} or other child browsing context attempts to load a new document or other resource that is not compatible with the embedder policy of its parent for cross origin isolation.
+The second is a `"worker initialization"` violation, which is when a page attempts to load a dedicated worker with an embedder policy that is not compatible with the page policy for cross origin isolation.


This is how I interpret the spec in https://html.spec.whatwg.org/multipage/browsers.html#embedder-policy-checks

Essentially COEP allows you to specify that there must be a resource loading policy or CORS on the thing to be embedded, and whatever it nests.
Ultimately the intent is to ensure that if you care about cross-origin isolation, you'll be able to set a policy that enforces it for emedded resources.

So a violation occurs if the thing that is loading requires cross-origin isolation and the thing to be loaded does not guarantee that.

@yoavweiss Can you sanity check this?

Apologies but I don't have a lot of context on this. Again @camillelamy is the authority here.

@camillelamy Can you please advise, or suggest someone else who might help. If not I guess I'll have to start adding issues to the spec.

So the issue here is that technically COEP applies even if the page does not have cross-origin isolation. I think it'd be better to be very precise about the checks happening:

A navigation violation happens when an iframe embedded in a document with either COEP require-corp or COEP credentialless loads a document that:

Has neither COEP require-corp or COEP credentialless.

Or is cross-origin with the embedder (the one with COEP reporting), and the document does not have a CORP header that allows embedding in the parent.

A worker initialization violation happens when a dedicated worker created by a document with either COEP require-corp or COEP credentialless tries to load a worker script with neither COEP require-corp or COEP credentialless headers. Again, I plan to file a spec bug to change this behavior so the COEP is inherited from teh creator and this kind of violation never happens.

hamishwillee · 2025-06-13T07:53:17Z

files/en-us/web/api/coopviolationreportbody/columnnumber/index.md

+
+## Value
+
+An integer containing the column number that triggered the violation.


For line, column, source file - Need to

Add example

Add info about what type (s) reports it can be returned in. I think they appear in "access-to-opener" reports (all of them)

hamishwillee · 2025-06-17T05:23:53Z

files/en-us/web/api/coopviolationreportbody/type/index.md

+
+The fields present in the report depend on the type.
+
+## Value


Hi @yoavweiss

A violation is triggered in a navigation if the policy causes the opened doc to be opened in a new BCG.
The violation report might have a body type of navigation-to-response or navigation-from-response, which are from the perspective of the opened and opener document.

What I think happens here is that if a resource with a COOP header and a reporting endpoint is opened and this causes a BCG switch then it sends a navigation-to-response.
If that same resource is the opener then it sends a navigation-from-response.

YOu don't both reports right - unless both opener and opened have a BCG (but they would then send just their type of message).

hamishwillee · 2025-06-17T05:56:55Z

files/en-us/web/api/coopviolationreportbody/disposition/index.md

@@ -0,0 +1,49 @@
+---


@yoavweiss

Do you happen to know the how HTTP enforcement and report-only headers interwork?

I think that

you can have Cross-Origin-Opener-Policy and/or Cross-Origin-Opener-Policy-Report-Only headers on any document.

The report(s) sent are from the perspective of the document with the policy and reporting endpoint.

Violations are determined by comparing that documents policy (which may be enforced or report only or both) and the enforced policy of the other document (you're always comparing the reporting/enforce policy in the current document to the actual policy of the other document).

So say I have an opener with a Cross-Origin-Opener-Policy: same-site that includes a reporting endpoint, and there is a navigation to another document that in this case has no policy (so a policy of unsafe-none and no reporting endpoint)

The policy will be evaluated and there is a violation because the opener is opened in a new BCD.

As per https://github.com/mdn/content/pull/39880/files#r2151347130 I think a report will be sent to the reporting endpoint of the opener of type navigation-from-response.

No report is sent for the opened.

Now consider the case where the opener still sets Cross-Origin-Opener-Policy: same-site but the opened sets Cross-Origin-Opener-Policy-Report-Only: same-site-no-opener and Cross-Origin-Opener-Policy-Report-Only: unsafe-none

There is a policy violation because the opened is opened in a new BCG.

I think a report will be sent to the reporting endpoint of the opener of type navigation-from-response.

I think a two reports will be sent to the reporting endpoint of the "opened" document of type navigation-from-response.

The first will be of disposition: enforced, and effectivePolicy unsafe-none

The second will be of disposition: reporting, and effectivePolicy same-site-no-opener

I think that is what the spec says, and it makes sense to me.

COEPViolationReportBody

3440257

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Jun 10, 2025

hamishwillee commented Jun 10, 2025

View reviewed changes

This was referenced Jun 10, 2025

COOP and COEP have no documentation of the report-to parameter #39814

Open

Reporting API Report body - how do I document the COEP body report? mdn/browser-compat-data#27021

Open

Report type types coep mdn/browser-compat-data#27047

Open

hamishwillee added 2 commits June 13, 2025 16:24

coepviolationreport - tidy up

d2208c0

COOP report properties

f5943ef

hamishwillee commented Jun 13, 2025

View reviewed changes

hamishwillee added 7 commits June 16, 2025 16:55

COEP report body index tidy

cb7a214

Fixes to line/column/source

458531a

disposition - fix

c8c6dd0

effectivePolicy - add

cae0435

previousResponseURL - create

5e991e4

type - add partial

e3854e2

COEP intro fixes

6a8516e

github-actions bot added the size/l [PR only] 501-1000 LoC changed label Jun 16, 2025

hamishwillee commented Jun 17, 2025

View reviewed changes

hamishwillee added 4 commits June 17, 2025 17:33

coop.disposition fix

109a815

COEP report index tidy

714c528

Fix next/prev response

59821c6

COOP violation report body - very very draft

56846cc


		## Instance properties

		- {{domxref("COEPViolationReportBody.type")}} {{ReadOnlyInline}}

		> [!NOTE]
		> This object does not derive from {{domxref("ReportBody")}} (unlike other {{domxref("Report.body")}} values).


		## Value

		An integer containing the column number that triggered the violation.


		The fields present in the report depend on the type.

		## Value

COEP and COOP reporting documentation #39880

Are you sure you want to change the base?

COEP and COOP reporting documentation #39880

Uh oh!

Conversation

hamishwillee commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hamishwillee commented Jun 10, 2025 •

edited

Loading

github-actions bot commented Jun 10, 2025 •

edited

Loading

hamishwillee Jun 17, 2025 •

edited

Loading