Add docs for HTTP Permissions-Policy header cross-origin-isolated…

… directive (mdn#36780)

* Add docs for HTTP `Permissions-Policy` header `cross-origin-isolated` directive

* fix typo

* Update index.md - add new form of intro

* Update files/en-us/web/http/headers/permissions-policy/cross-origin-isolated/index.md

* Update files/en-us/web/http/headers/permissions-policy/cross-origin-isolated/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* update text

* update

* Apply suggestions from code review

Co-authored-by: Joshua Chen <[email protected]>

* Update files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md

* Update files/en-us/web/api/performance/now/index.md

* Apply suggestions from code review

* Apply suggestions from code review

* Apply suggestions from code review

* Move most of the common instructions into the Window.crossOriginIsolated doc

* Tweeks/structure to match API template

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: skyclouds2001 <[email protected]>

---------

Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Joshua Chen <[email protected]>

files/en-us/web/api/performance/measureuseragentspecificmemory/index.md

@@ -12,14 +12,6 @@ browser-compat: api.Performance.measureUserAgentSpecificMemory
 
 The **`measureUserAgentSpecificMemory()`** method is used to estimate the memory usage of a web application including all its iframes and workers.
 
-## Description
-
-The browser automatically allocates memory when objects are created and frees it when they are not reachable anymore (garbage collection). This garbage collection (GC) is an approximation since the general problem of determining whether or not a specific piece of memory is still needed is impossible (see also [JavaScript Memory Management](/en-US/docs/Web/JavaScript/Memory_management)). Developers need to make sure that objects are garbage collected, memory isn't leaked, and memory usage doesn't grow unnecessarily over time leading to slow and unresponsive web applications. Memory leaks are typically introduced by forgetting to unregister an event listener, not closing a worker, accumulating objects in arrays, and more.
-
-The `measureUserAgentSpecificMemory()` API aggregates memory usage data to help you find memory leaks. It can be used for memory regression detection or for A/B testing features to evaluate their memory impact. Rather than make single calls to this method, it's better to make periodic calls to track how memory usage changes over the duration of a session.
-
-The `byte` values this API returns aren't comparable across browsers or between different versions of the same browser as these are highly implementation dependent. Also, how `breakdown` and `attribution` arrays are provided is up to the browser as well. It is best to not hardcode any assumptions about this data. This API is rather meant to be called periodically (with a randomized interval) to aggregate data and analyze the difference between the samples.
-
 ## Syntax
 
 ```js-nolint
@@ -97,23 +89,21 @@ An example return value looks like this:
 ### Exceptions
 
 - `SecurityError` {{domxref("DOMException")}}
-  - : Thrown if the security requirements for preventing cross-origin information leaks aren't fulfilled.
+  - : Thrown if the [security requirements](#security_requirements) for preventing cross-origin information leaks aren't fulfilled.
 
-## Security requirements
+## Description
+
+The browser automatically allocates memory when objects are created and frees it when they are not reachable anymore (garbage collection). This garbage collection (GC) is an approximation since the general problem of determining whether or not a specific piece of memory is still needed is impossible (see also [JavaScript Memory Management](/en-US/docs/Web/JavaScript/Memory_management)). Developers need to make sure that objects are garbage collected, memory isn't leaked, and memory usage doesn't grow unnecessarily over time leading to slow and unresponsive web applications. Memory leaks are typically introduced by forgetting to unregister an event listener, not closing a worker, accumulating objects in arrays, and more.
 
-Your site needs to be in a [secure context](/en-US/docs/Web/Security/Secure_Contexts).
+The `measureUserAgentSpecificMemory()` API aggregates memory usage data to help you find memory leaks. It can be used for memory regression detection or for A/B testing features to evaluate their memory impact. Rather than make single calls to this method, it's better to make periodic calls to track how memory usage changes over the duration of a session.
 
-Two headers need to be set to cross-origin isolate your site:
+The `byte` values this API returns aren't comparable across browsers or between different versions of the same browser as these are highly implementation dependent. Also, how `breakdown` and `attribution` arrays are provided is up to the browser as well. It is best to not hardcode any assumptions about this data. This API is rather meant to be called periodically (with a randomized interval) to aggregate data and analyze the difference between the samples.
 
-- [`Cross-Origin-Opener-Policy`](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) with `same-origin` as value (protects your origin from attackers)
-- [`Cross-Origin-Embedder-Policy`](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) with `require-corp` or `credentialless` as value (protects victims from your origin)
+## Security requirements
 
-```http
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
+To use this method your document must be in a [secure context](/en-US/docs/Web/Security/Secure_Contexts) and {{domxref("Window.crossOriginIsolated","cross-origin isolated","","nocode")}}.
 
-To check if cross origin isolation has been successful, you can test against the {{domxref("Window.crossOriginIsolated")}} property or the {{domxref("WorkerGlobalScope.crossOriginIsolated")}} property available to window and worker contexts:
+You can use the {{domxref("Window.crossOriginIsolated")}} and {{domxref("WorkerGlobalScope.crossOriginIsolated")}} properties to check if the document is cross-origin isolated:
 
 ```js
 if (crossOriginIsolated) {

files/en-us/web/api/performance/now/index.md

@@ -62,6 +62,21 @@ The specification (Level 2) requires that `performance.now()` should tick during
 
 More details can also be found in the specification issue [hr-time#115](https://github.com/w3c/hr-time/issues/115#issuecomment-1172985601).
 
+## Security requirements
+
+To offer protection against timing attacks and [fingerprinting](/en-US/docs/Glossary/Fingerprinting), `performance.now()` is coarsened based on whether or not the document is {{domxref("Window.crossOriginIsolated","cross-origin isolated","","nocode")}}.
+
+- Resolution in isolated contexts: 5 microseconds
+- Resolution in non-isolated contexts: 100 microseconds
+
+You can use the {{domxref("Window.crossOriginIsolated")}} and {{domxref("WorkerGlobalScope.crossOriginIsolated")}} properties to check if the document is cross-origin isolated:
+
+```js
+if (crossOriginIsolated) {
+  // Use measureUserAgentSpecificMemory
+}
+```
+
 ## Examples
 
 ### Using `performance.now()`
@@ -75,26 +90,6 @@ const t1 = performance.now();
 console.log(`Call to doSomething took ${t1 - t0} milliseconds.`);
 ```
 
-## Security requirements
-
-To offer protection against timing attacks and [fingerprinting](/en-US/docs/Glossary/Fingerprinting), `performance.now()` is coarsened based on site isolation status.
-
-- Resolution in isolated contexts: 5 microseconds
-- Resolution in non-isolated contexts: 100 microseconds
-
-Cross-origin isolate your site using the {{HTTPHeader("Cross-Origin-Opener-Policy")}} and
-{{HTTPHeader("Cross-Origin-Embedder-Policy")}} headers:
-
-```http
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
-
-These headers ensure a top-level document does not share a browsing context group with
-cross-origin documents. COOP process-isolates your document and potential attackers
-can't access to your global object if they were opening it in a popup, preventing a set
-of cross-origin attacks dubbed [XS-Leaks](https://github.com/xsleaks/xsleaks).
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/window/crossoriginisolated/index.md

@@ -10,7 +10,7 @@ browser-compat: api.crossOriginIsolated
 
 The **`crossOriginIsolated`** read-only property of the {{domxref("Window")}} interface returns a boolean value that indicates whether the document is cross-origin isolated.
 
-A cross-origin isolated document only shares its {{glossary("Browsing context","browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`).
+A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`).
 The relationship between a cross-origin opener of the document or any cross-origin popups that it opens are severed.
 The document may also be hosted in a separate OS process alongside other documents with which it can communicate by operating on shared memory.
 This mitigates the risk of side-channel attacks and cross-origin attacks referred to as [XS-Leaks](https://xsleaks.dev/).
@@ -19,19 +19,44 @@ Cross-origin isolated documents operate with fewer restrictions when using the f
 
 - {{JSxRef("SharedArrayBuffer")}} can be created and sent via a {{DOMxRef("Window.postMessage()")}} or a {{DOMxRef("MessagePort.postMessage()")}} call.
 - {{DOMxRef("Performance.now()")}} offers better precision.
-- {{DOMxRef("Performance.measureUserAgentSpecificMemory()")}} can be accessed.
+- {{DOMxRef("Performance.measureUserAgentSpecificMemory()")}} can be called.
 
 A document will be cross-origin isolated if it is returned with an HTTP response that includes the headers:
 
 - {{HTTPHeader("Cross-Origin-Opener-Policy")}} header with the directive `same-origin`.
 - {{HTTPHeader("Cross-Origin-Embedder-Policy")}} header with the directive `require-corp` or `credentialless`.
 
+Access to the APIs must also be allowed by the `Permissions-Policy` {{HTTPHeader("Permissions-Policy/cross-origin-isolated", "cross-origin-isolated")}}.
+Otherwise `crossOriginIsolated` property will return `false`, and the document will not be able to use the APIs listed above with reduced restrictions.
+
 ## Value
 
 A boolean value.
 
 ## Examples
 
+### Cross-origin isolating a document
+
+To cross-origin isolate a document:
+
+- Set the {{HTTPHeader("Cross-Origin-Opener-Policy")}} HTTP header to `same-origin`:
+
+  ```http
+  Cross-Origin-Opener-Policy: same-origin
+  ```
+
+- Set the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} HTTP header to `require-corp` or `credentialless`:
+
+  ```http
+  Cross-Origin-Embedder-Policy: require-corp
+  Cross-Origin-Embedder-Policy: credentialless
+  ```
+
+- The {{HTTPHeader("Permissions-Policy/cross-origin-isolated","cross-origin-isolated")}} directive of the {{HTTPHeader("Permissions-Policy")}} header must not block access to the feature.
+  Note that the default allowlist of the directive is `self`, so the permission will be granted by default to cross-origin isolated documents.
+
+### Checking if the document is cross-origin isolated
+
 ```js
 const myWorker = new Worker("worker.js");
 
@@ -51,3 +76,7 @@ if (window.crossOriginIsolated) {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("WorkerGlobalScope.crossOriginIsolated")}}

files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md

@@ -10,7 +10,7 @@ browser-compat: api.crossOriginIsolated
 
 The **`crossOriginIsolated`** read-only property of the {{domxref("WorkerGlobalScope")}} interface returns a boolean value that indicates whether the document is cross-origin isolated.
 
-A cross-origin isolated document only shares its {{glossary("Browsing context","browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`).
+A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`).
 The relationship between a cross-origin opener of the document or any cross-origin popups that it opens are severed.
 The document may also be hosted in a separate OS process alongside other documents with which it can communicate by operating on shared memory.
 This mitigates the risk of side-channel attacks and cross-origin attacks referred to as [XS-Leaks](https://xsleaks.dev/).
@@ -19,19 +19,44 @@ Cross-origin isolated documents operate with fewer restrictions when using the f
 
 - {{JSxRef("SharedArrayBuffer")}} can be created and sent via a {{DOMxRef("DedicatedWorkerGlobalScope.postMessage()")}} or a {{DOMxRef("MessagePort.postMessage()")}} call.
 - {{DOMxRef("Performance.now()")}} offers better precision.
-- {{DOMxRef("Performance.measureUserAgentSpecificMemory()")}} can be accessed.
+- {{DOMxRef("Performance.measureUserAgentSpecificMemory()")}} can be called.
 
 A document will be cross-origin isolated if it is returned with an HTTP response that includes the headers:
 
-- {{HTTPHeader("Cross-Origin-Opener-Policy")}} header with the directive `same-origin`
-- {{HTTPHeader("Cross-Origin-Embedder-Policy")}} header with the directive `require-corp` or `credentialless`
+- {{HTTPHeader("Cross-Origin-Opener-Policy")}} header with the directive `same-origin`.
+- {{HTTPHeader("Cross-Origin-Embedder-Policy")}} header with the directive `require-corp` or `credentialless`.
+
+Access to the APIs must also be allowed by the `Permissions-Policy` {{HTTPHeader("Permissions-Policy/cross-origin-isolated", "cross-origin-isolated")}}.
+Otherwise `crossOriginIsolated` property will return `false`, and the document will not be able to use the APIs listed above with reduced restrictions.
 
 ## Value
 
 A boolean value.
 
 ## Examples
 
+### Cross-origin isolating a document
+
+To cross-origin isolate a document:
+
+- Set the {{HTTPHeader("Cross-Origin-Opener-Policy")}} HTTP header to `same-origin`:
+
+  ```http
+  Cross-Origin-Opener-Policy: same-origin
+  ```
+
+- Set the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} HTTP header to `require-corp` or `credentialless`:
+
+  ```http
+  Cross-Origin-Embedder-Policy: require-corp
+  Cross-Origin-Embedder-Policy: credentialless
+  ```
+
+- The {{HTTPHeader("Permissions-Policy/cross-origin-isolated","cross-origin-isolated")}} directive of the {{HTTPHeader("Permissions-Policy")}} header must not block access to the feature.
+  Note that the default allowlist of the directive is `self`, so the permission will be granted by default to cross-origin isolated documents.
+
+### Checking if the document is cross-origin isolated
+
 ```js
 const myWorker = new Worker("worker.js");
 
@@ -51,3 +76,7 @@ if (self.crossOriginIsolated) {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Window.crossOriginIsolated")}}

files/en-us/web/http/headers/cross-origin-embedder-policy/index.md

@@ -40,18 +40,19 @@ Cross-Origin-Embedder-Policy: unsafe-none | require-corp | credentialless
 
 ## Examples
 
-### Certain features depend on cross-origin isolation
+### Features that depend on cross-origin isolation
 
-You can only access certain features like {{jsxref("SharedArrayBuffer")}} objects or {{domxref("Performance.now()")}} with unthrottled timers, if your document has a COEP header with a value of `require-corp` or `credentialless` set.
+Certain features, such as access to {{jsxref("SharedArrayBuffer")}} objects or using {{domxref("Performance.now()")}} with unthrottled timers, are only available if your document is {{domxref("Window.crossOriginIsolated","cross-origin isolated","","nocode")}}.
+
+To use these features in a document, you will need to set the COEP header with a value of `require-corp` or `credentialless`, and the {{HTTPHeader("Cross-Origin-Opener-Policy")}} header to `same-origin`.
+In addition the feature must not be blocked by {{HTTPHeader("Permissions-Policy/cross-origin-isolated","Permissions-Policy: cross-origin-isolated")}}.
 
 ```http
-Cross-Origin-Embedder-Policy: require-corp
 Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
 ```
 
-See also the {{HTTPHeader("Cross-Origin-Opener-Policy")}} header which you'll need to set as well.
-
-To check if cross origin isolation has been successful, you can test against the {{domxref("Window.crossOriginIsolated")}} property or the {{domxref("WorkerGlobalScope.crossOriginIsolated")}} property available to window and worker contexts:
+You can use the {{domxref("Window.crossOriginIsolated")}} and {{domxref("WorkerGlobalScope.crossOriginIsolated")}} properties to check if the features are restricted in window and worker contexts, respectively:
 
 ```js
 const myWorker = new Worker("worker.js");

files/en-us/web/http/headers/cross-origin-opener-policy/index.md

@@ -135,18 +135,19 @@ The table below shows the opener behaviour for the different directive values.
 
 ## Examples
 
-### Certain features depend on cross-origin isolation
+### Features that depend on cross-origin isolation
 
-Certain features like {{jsxref("SharedArrayBuffer")}} objects or {{domxref("Performance.now()")}} with unthrottled timers are only available if your document has a COOP header with the value `same-origin` set.
+Certain features, such as access to {{jsxref("SharedArrayBuffer")}} objects or using {{domxref("Performance.now()")}} with unthrottled timers, are only available if your document is {{domxref("Window.crossOriginIsolated","cross-origin isolated","","nocode")}}.
+
+To use these features in a document, you will need to set the COOP header to `same-origin` and the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} header to `require-corp` (or `credentialless`).
+In addition the feature must not be blocked by {{HTTPHeader("Permissions-Policy/cross-origin-isolated","Permissions-Policy: cross-origin-isolated")}}.
 
 ```http
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-See also the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} header which you'll need to set to `require-corp` or `credentialless` as well.
-
-To check if cross-origin isolation has been successful, you can test against the {{domxref("Window.crossOriginIsolated")}} property or the {{domxref("WorkerGlobalScope.crossOriginIsolated")}} property available to window and worker contexts:
+You can use the {{domxref("Window.crossOriginIsolated")}} and {{domxref("WorkerGlobalScope.crossOriginIsolated")}} properties to check if a document is cross-origin isolated, and hence whether or not the features are restricted:
 
 ```js
 const myWorker = new Worker("worker.js");