Skip to content

COEP reporting documentation#39880

Merged
hamishwillee merged 9 commits intomdn:mainfrom
hamishwillee:coep_coop_violation_report
Mar 6, 2026
Merged

COEP reporting documentation#39880
hamishwillee merged 9 commits intomdn:mainfrom
hamishwillee:coep_coop_violation_report

Conversation

@hamishwillee
Copy link
Collaborator

@hamishwillee hamishwillee commented Jun 10, 2025

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

NOTE - Modified to just cover COEP. Will do COOP in a separate case. The way reporting is done may be slightly different based on https://github.com/mdn/content/pull/39880/files#r2425080573

Doing COEP first because is easier.

NOTE, approach here is different to others COEPViolationReport is a whole report, not a body. I am going to do this for the other derived reports too - leaving Report and ReportBody as deprecated orphans. This reflects BCD and the spec change.

Fixes #39814

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

github-actions bot commented Jun 10, 2025

Preview URLs (3 pages)

External URLs (3)

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


URL: /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy-Report-Only
Title: Cross-Origin-Embedder-Policy-Report-Only (COEP) header

(comment last updated: 2026-03-06 00:26:17)

@github-actions github-actions bot added the size/l [PR only] 501-1000 LoC changed label Jun 16, 2025
@@ -0,0 +1,49 @@
---
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll again have to call on @camillelamy for help here, as I'm not sure what the answer here should be.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I wrote the spec for reporting in COOP and am much more familiar with the implementation, so this one I can answer.

For COOP, we try to see if a browsing context group would happen were we to enforce all the policies we're asked about.

In practice, we separate enforce/report-only mode (which can have different reporting endpoints).

For enforcement, we only compare with the other document enforced policy: we are reporting that a BCG switch did happen after all.

For report-only, this is a bit more complex. First, we check if the other document report-only policy would ensure that there would be no BCG swap. If that's the case, we won't send a report. Our rational is that developers might want to deploy COOP on several documents in their origin in report-only mode first, and we should not warn them about issues that would not happen if they switch all of their report-only policies to enforcement.

If the report-only don't match, then we check what would happen if we enforced the report-only policy of the document we're navigating to compared with the enforced policy of the current document. We also compare the report-only policy of the current document with the enforced policy of the document we're navigating to. If any of those would trigger a BCG swap, then we note that the documents would ned up in two different browsing contexts. We keep track of this information even if the documents navigate again, this is important for the access reporting. When the BCG switch would be triggered, we also send a report to the relevant endpoints of both the current document and the document we're navigating to. If there are no endpoints, then we don't send a response.

In your second example, you listed two report only policies so I am going to assume you meant unsafe-none as the enforced policy and same-origin-no-opener as the report-only one. In that case, you would get:

  • You get a navigation-from-response report on the endpoint of the opener, with disposition enforced and policy same-origin.
  • You get a navigation-to-response report on the enforced endpoint of the openee with disposition enforced and policy unsafe-none.
  • You get a navigation-to-response report on the report-only endpoint of the openee with disposition report-only and policy same-origin-no-opener.

Now if the openee report-only policy was same-origin, and it was same-origin with the opener, you would not get the third report-only report. But you would still get the first two. And if both documents were same-origin and had report-only same-origin COOP, you would not get any report at all. If only one of them had the report-only COOP, then you would get reports.

This gets a bit more complex for access reporting, as we're keeping track of whether any report-only COOP would have triggered a BCG swap. Then when an access happen, we check if the two documents would be in different BCGs if COOP had been enforced. But the BCG swap might have been triggered during a previous navigation. To give you an example:

  • You document has COOP report-only same-origin. It opens a popup with a cross-origin document. We record that all documents in the popup would be in a different BCG from the documents in the opener page if COOP was enforced. Accesses to the popup/from the popup are reported (provided they involve a same-origin document).
  • The popup navigates to another origin. There is no new BCG switch due to COOP, but we would still report accesses because the pages would still be in different BCGs.
  • The opener navigates to a non-COOP page. This would also trigger a BCG switch if COOP was enforced. We record this. However, we no longer have a reporting endpoint for COOP, so we don't send reports anymore.

@github-actions github-actions bot removed the size/m [PR only] 51-500 LoC changed label Jul 9, 2025
@hamishwillee hamishwillee force-pushed the coep_coop_violation_report branch from e1ad482 to f1c6588 Compare August 10, 2025 23:56
@hamishwillee
Copy link
Collaborator Author

FYI, I have not forgotten this. It's just not as high on the priority list as I would like. Won't be this month.

@hamishwillee hamishwillee force-pushed the coep_coop_violation_report branch 2 times, most recently from 411655e to 3538409 Compare October 10, 2025 00:21
@hamishwillee hamishwillee marked this pull request as ready for review November 23, 2025 22:20
@hamishwillee hamishwillee requested review from a team as code owners November 23, 2025 22:20
@hamishwillee hamishwillee requested review from dipikabh and sideshowbarker and removed request for a team November 23, 2025 22:20
@dipikabh dipikabh removed their request for review November 28, 2025 16:07
@dipikabh
Copy link
Contributor

@hamishwillee removing myself for now, please add me back if and when this needs an edit review.

@hamishwillee hamishwillee force-pushed the coep_coop_violation_report branch from cab4395 to 9e9dbee Compare February 17, 2026 20:43
@hamishwillee hamishwillee marked this pull request as draft February 20, 2026 03:16
@hamishwillee hamishwillee force-pushed the coep_coop_violation_report branch from 1a9c96e to 5c9a882 Compare February 20, 2026 05:51
@github-actions github-actions bot added size/m [PR only] 51-500 LoC changed and removed size/l [PR only] 501-1000 LoC changed labels Feb 20, 2026
@hamishwillee hamishwillee force-pushed the coep_coop_violation_report branch from 5c9a882 to 69ae01a Compare February 20, 2026 05:53
@hamishwillee hamishwillee marked this pull request as ready for review February 20, 2026 05:54
@hamishwillee
Copy link
Collaborator Author

@sideshowbarker FYI I've started the work turning the other interfaces into dictionaries in #43195.

There have been corresponding changes here for consistency. Specifically, most of the reporting is covered in the report object such as COEPViolationReport - there is boilerplate on the headers to reference this and only simple examples. This is to reduce duplication but still make reporting obvious from the headers.

@camillelamy
Copy link

@sideshowbarker @yoavweiss @camillelamy This documentation on COEP and COEP reporting is ready for review. I'd appreciate some sanity checking if you have time.

Sorry it took so long! I plan on looking at it again on Friday as doubtless there are some typos etc, but the broad story should be right. Note that this borrows from the structure of the other docs - the HTTP headers dicuss the reports, but the detail on how to get them and what the properties are is documented as part of the Reporting API in the relevant body object.

Thanks! I had a look and it looks good.

Co-authored-by: sideshowbarker <mike@w3.org>
@hamishwillee
Copy link
Collaborator Author

Thanks @sideshowbarker (and @camillelamy ) for review - I have accepted all suggestions.

@hamishwillee hamishwillee merged commit 2d0aa21 into mdn:main Mar 6, 2026
9 checks passed
@hamishwillee hamishwillee deleted the coep_coop_violation_report branch March 6, 2026 00:27
jdatapple pushed a commit to jdatapple/content that referenced this pull request Mar 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:HTTP HTTP docs Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

5 participants