COEP and COOP reporting documentation

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

@@ -0,0 +1,42 @@
+---
+title: "COEPViolationReportBody: blockedURL property"
+short-title: blockedURL
+slug: Web/API/COEPViolationReportBody/blockedURL
+page-type: web-api-instance-property
+browser-compat: api.COEPViolationReportBody.blockedURL
+---
+
+{{APIRef("Reporting API")}}
+
+The **`blockedURL`** read-only property of the {{domxref("COEPViolationReportBody")}} interface returns the URL of the resource that was blocked from loading by an enforced COEP violation, or would be blocked if a report-only policy was enforced.
+
+## Value
+
+An string containing a URL value.
+
+## Examples
+
+### Get the URL of the resource that triggered the report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe COEP violation reports, then log the value of `blockedURL` to the console.
+
+```js
+const options = {
+  types: ["coep"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coep
+  console.log(firstReport.body.blockedURL); // URL of the violating resource
+}, options);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,49 @@
+---
+title: "COEPViolationReportBody: disposition property"
+short-title: disposition
+slug: Web/API/COEPViolationReportBody/disposition
+page-type: web-api-instance-property
+browser-compat: api.COEPViolationReportBody.disposition
+---
+
+{{APIRef("Reporting API")}}
+
+The **`disposition`** read-only property of the {{domxref("COEPViolationReportBody")}} dictionary indicates whether the policy violation was enforced, blocking loading of the associated resource, or just reported.
+
+## Value
+
+A string that can have one of the following values:
+
+- `"enforce"`
+  - : The violation caused loading of the embedded resource to be blocked.
+    This is set for violations of policies set with {{httpheader("Cross-Origin-Embedder-Policy")}}.
+- `"reporting"`
+  - : The violation was reported without blocking the resource from loading.
+    This is set for violations of policies set with {{httpheader("Cross-Origin-Embedder-Policy-Report-Only")}}.
+
+## Examples
+
+### Get the disposition of a report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe COEP violation reports, then log the value of `disposition` to the console.
+
+```js
+const options = {
+  types: ["coep"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coep
+  console.log(firstReport.body.disposition);
+}, options);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,93 @@
+---
+title: COEPViolationReportBody
+slug: Web/API/COEPViolationReportBody
+page-type: web-api-interface
+browser-compat: api.COEPViolationReportBody
+---
+
+{{APIRef("Reporting API")}}
+
+The `COEPViolationReportBody` dictionary represents the {{domxref("Report.body","body")}} of a {{domxref("Report")}} that has a {{domxref("Report.type","type")}} of `coep`.
+
+Reports with this type are used by the [Reporting API](/en-US/docs/Web/API/Reporting_API) to notify of violations of COEP policies set with the HTTP headers {{httpheader("Cross-Origin-Embedder-Policy")}} and {{httpheader("Cross-Origin-Embedder-Policy-Report-Only")}}.
+A serialized version of the same report structure may also be sent to [reporting server endpoints](/en-US/docs/Web/API/Reporting_API#reporting_server_endpoints).
+
+> [!NOTE]
+> This object does not derive from {{domxref("ReportBody")}} (unlike some other {{domxref("Report.body")}} values).
+
+## Instance properties
+
+- {{domxref("COEPViolationReportBody.type")}} {{ReadOnlyInline}}
+  - : A string representing what kind of cross-origin embedding caused the violation.
+- {{domxref("COEPViolationReportBody.blockedURL")}} {{ReadOnlyInline}}
+  - : A string containing the URL of the blocked resource.
+- {{domxref("COEPViolationReportBody.disposition")}} {{ReadOnlyInline}}
+  - : A string indicating whether the violation was enforced or only reported.
+
+## Description
+
+A document's policies for loading and embedding cross-origin resources are configured and enforced using the {{httpheader("Cross-Origin-Embedder-Policy")}} HTTP header, and may also be reported but not enforced using the {{httpheader("Cross-Origin-Embedder-Policy-Report-Only")}} header.
+
+COEP policy violations may be reported using the [Reporting API](/en-US/docs/Web/API/Reporting_API) whenever a policy set by those headers blocks (or would block) the loading of a resource.
+
+A COEP policy violation report is represented by a {{domxref("Report")}} instance that has the {{domxref("Report.type","type")}} of `coep` and a {{domxref("Report.body","body")}} property that is an object of this type.
+Reports can be returned via the {{domxref("ReportingObserver")}} interface or serialized and sent in a `POST` to a [reporting server endpoint](/en-US/docs/Web/API/Reporting_API#reporting_server_endpoints).
+
+To send to a reporting server endpoint the {{httpheader("Cross-Origin-Embedder-Policy")}} and/or {{httpheader("Cross-Origin-Embedder-Policy-Report-Only")}} headers used to set the policy must include the `report-to` parameter with a valid reporting endpoint name.
+Valid endpoint names are defined using the {{httpheader("Reporting-Endpoints")}} header.
+
+There are two main 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.
+
+In both cases "incompatible" means that the parent embedder policy requires cross origin isolation but the embedder policy of the child resource does not provide those guarantees of isolation.
+If the resource isn't loaded into a child context (such as a frame), or if the parent does not require isolation, then the embedder policy of the loaded resource doesn't matter.
+
+## Examples
+
+### COEP report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe coep reports, then log the first report to the console.
+
+```js
+const options = {
+  types: ["coep"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coep
+  console.log(firstReport);
+}, options);
+```
+
+The logged report object for a COEP violation from loading an iframe might look like this:
+
+```json
+[
+  {
+    "type": "coep",
+    "url": "https://url-where-report-sent",
+    "body": {
+      "type": "navigation",
+      "blockedURL": "https://url-of-frame-that-was-blocked",
+      "disposition": "enforce"
+    }
+  }
+]
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{httpheader("Reporting-Endpoints")}}
+- [Reporting API](/en-US/docs/Web/API/Reporting_API)
+- [The Reporting API](https://developer.chrome.com/docs/capabilities/web-apis/reporting-api)

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

@@ -0,0 +1,47 @@
+---
+title: "COEPViolationReportBody: type property"
+short-title: type
+slug: Web/API/COEPViolationReportBody/type
+page-type: web-api-instance-property
+browser-compat: api.COEPViolationReportBody.type
+---
+
+{{APIRef("Reporting API")}}{{AvailableInWorkers}}
+
+The **`type`** read-only property of the {{domxref("COEPViolationReportBody")}} dictionary returns a value that indicates the cause of the violation, such as embedding a child resource or loading a dedicated worker.
+
+## Value
+
+A string that can have one of the following values:
+
+- `"navigation"`
+  - : The violation was caused by an {{htmlelement("iframe")}} or other child browsing context attempting to load a new document.
+- `"worker initialization"`
+  - : The violation was caused by a page attempting to load a dedicated worker.
+
+## Examples
+
+### Get the type of a COEP violation report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe COEP violation reports, then log the value of `type` to the console.
+
+```js
+const options = {
+  types: ["coep"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coep
+  console.log(firstReport.body.type); // navigation or worker initialization
+}, options);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,27 @@
+---
+title: "COOPViolationReportBody: columnNumber property"
+short-title: columnNumber
+slug: Web/API/COOPViolationReportBody/columnNumber
+page-type: web-api-instance-property
+browser-compat: api.COOPViolationReportBody.columnNumber
+---
+
+{{APIRef("Reporting API")}}
+
+The **`columnNumber`** read-only property of the {{domxref("COOPViolationReportBody")}} interface indicates the column number in the source file that triggered the [Cross-Origin-Opener-Policy (COEP)](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-OPener-Policy) violation.
+
+This property is used with {{domxref("COOPViolationReportBody.sourceFile")}} and {{domxref("COOPViolationReportBody.lineNumber")}} to indicate the location that triggered the violation.
+
+## Value
+
+An integer containing the column number that triggered the violation.
+
+## Examples
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,49 @@
+---
+title: "COOPViolationReportBody: disposition property"
+short-title: disposition
+slug: Web/API/COOPViolationReportBody/disposition
+page-type: web-api-instance-property
+browser-compat: api.COOPViolationReportBody.disposition
+---
+
+{{APIRef("Reporting API")}}
+
+The **`disposition`** read-only property of the {{domxref("COOPViolationReportBody")}} dictionary indicates whether the report is for an enforced or report-only policy violation.
+
+Policy violations are enforced if the policy was set with {{httpheader("Cross-Origin-Opener-Policy")}}, and report-only if set with {{httpheader("Cross-Origin-Embedder-Policy-Report-Only")}}.
+
+## Value
+
+A string that can have one of the following values:
+
+- `"enforce"`
+  - : The report is for policy violation that was enforced.
+- `"reporting"`
+  - : The report is for policy violation that was report-only.
+
+## Examples
+
+### Get the disposition of a report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe COOP violation reports, then log the value of `disposition` to the console.
+
+```js
+const options = {
+  types: ["coop"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coop
+  console.log(firstReport.body.disposition);
+}, options);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,47 @@
+---
+title: "COOPViolationReportBody: effectivePolicy property"
+short-title: effectivePolicy
+slug: Web/API/COOPViolationReportBody/effectivePolicy
+page-type: web-api-instance-property
+browser-compat: api.COOPViolationReportBody.effectivePolicy
+---
+
+{{APIRef("Reporting API")}}
+
+The **`effectivePolicy`** read-only property of the {{domxref("COOPViolationReportBody")}} dictionary indicates the COOP policy of the opened or opener document that triggered the report.
+It is present on all reports of type `coop`.
+
+Note that the term "effective" is used for the property because to indicate that it is a policy that is either enforced or reported.
+
+## Value
+
+A string that indicates the policy set in {{httpheader("Cross-Origin-Opener-Policy")}} or {{httpheader("Cross-Origin-Opener-Policy-Report-Only")}} for the document associated with the report.
+
+This will be one of the allowed directive values for [`Cross-Origin-Opener-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy#directives).
+
+## Examples
+
+### Get the effectivePolicy of a COOP violation report
+
+In this example we create a new {{domxref("ReportingObserver")}} to observe COEP violation reports, then log the value of `effectivePolicy` to the console.
+
+```js
+const options = {
+  types: ["coep"],
+  buffered: true,
+};
+
+const observer = new ReportingObserver((reports, observer) => {
+  const firstReport = reports[0];
+  console.log(firstReport.type); // coep
+  console.log(firstReport.body.effectivePolicy); // A COOP directive such as unsafe-none or same-site
+}, options);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}