index.bs

<pre class="metadata">
Title: Document-Isolation-Policy
Status: CG-DRAFT
Group: WICG
ED: https://github.com/WICG/document-isolation-policy
Repository: https://github.com/WICG/document-isolation-policy
Shortname: coop-restrict-properties
Level: 1
Editor: Camille Lamy, Google, clamy@google.com
Abstract:
  This proposal explores a new header, "Document-Isolation-Policy", that
  enables crossOriginIsolation for the document, without relying on COOP and
  COEP. In turns, this gives access to COI-gated APIs such as SharedArrayBuffers.
Indent: 2
Work Status: exploring
Boilerplate: omit conformance
Markup Shorthands: css off, markdown on
WPT Display: inline
</pre>

<pre boilerplate="copyright">&copy;2024, Google, Inc. All rights reserved.</pre>

<pre class="biblio">
{
  "spectre": {
    "authors": [
      "Paul Kocher",
      "Jann Horn",
      "Anders Fogh",
      "Daniel Genkin",
      "Daniel Gruss",
      "Werner Haas",
      "Mike Hamburg",
      "Moritz Lipp",
      "Stefan Mangard",
      "Thomas Prescher",
      "Michael Schwarz",
      "Yuval Yarom"
    ],
    "href": "https://spectreattack.com/spectre.pdf",
    "title": "Spectre Attacks: Exploiting Speculative Execution"
  },

  "explainer": {
    "authors": [
      "Camille Lamy"
    ],
    "href": "https://github.com/WICG/document-isolation-policy",
    "title": "Document-Isolation-Policy explainer"
  },

  "WhyCoopCoep": {
    "authors": [
      "Eiji Kitamura",
      "Demenic Denicola"
    ],
    "href": "https://web.dev/why-coop-coep/",
    "title": "Why you need \"cross-origin isolated\" for powerful features"
  }
}
</pre>

<pre class="anchors">
urlPrefix: https://tc39.es/ecma262/; spec: ECMAScript
  text: SharedArrayBuffer; type: interface; url: sec-sharedarraybuffer-objects

urlPrefix: https://infra.spec.whatwg.org/; spec: Infra 
  text: append; type:dfn; url:set-append
  text: contain an entry; type:dfn; url:map-exist
  text: getting the value; type:dfn; url:map-get
  text: list-is-empty; type:dfn; url:list-is-empty
  text: list-remove; type:dfn; url:list-remove
  text: list-size; type:dfn; url:list-size
  text: map-empty; type:dfn; url:map-empty
  text: map-exists; type:dfn; url:map-exists
  text: map-size; type:dfn; url:map-size
  text: map-value; type:dfn; url:map-size
  text: remove entries; type:dfn; url:map-remove
  text: set; type:dfn; url:ordered-set

urlPrefix: https://html.spec.whatwg.org/C/; spec: html
  text: agent cluster key; type:dfn; url:agent-cluster-key
  text: browsing context; type:dfn; url:browsing-context
  text: browsing-context-group; type:dfn; url:browsing-context-group
  text: browsing context group; type:dfn; url:browsing-context-group
  text: browsing context group set; type:dfn; url:browsing-context-group-set
  text: Browsing context group switches due to cross-origin opener policy; type:dfn; url:browsing-context-group-switches-due-to-cross-origin-opener-policy
  text: COEP; type: dfn; url: coep
  text: COOP; type: dfn; url: cross-origin-opener-policies
  text: coop-enforcement-origin; type: dfn; url: coop-enforcement-origin
  text: current context is navigation source; type: dfn; url: coop-enforcement-source
  text: coop-same-origin; type: dfn; url: coop-same-origin
  text: coop-same-origin-allow-popups; type: dfn; url: coop-same-origin-allow-popups
  text: compatible with cross-origin isolation; type: dfn; url:compatible-with-cross-origin-isolation
  text: concept-document-bc; type:dfn; url:concept-document-bc
  text: concept-document-origin; type:dfn; url:concept-document-origin
  text: concept-document-policy-container; type: dfn; url: concept-document-policy-container
  text: concrete; type:dfn; url:cross-origin-isolation-concrete
  text: create a new browsing context and document; type:dfn; url:creating-a-new-browsing-context
  text: create and initialize a document object; type:dfn; url:initialise-the-document-object
  text: creating a new browsing context group and document; type:dfn; url:creating-a-new-browsing-context-group-and-document
  text: creating a new top-level browsing context and document; type:dfn; url:creating-a-new-top-level-browsing-context
  text: create a new top-level browsing context and document; type:dfn; url:creating-a-new-top-level-browsing-context
  text: create a new top-level traversable; type:dfn; url:creating-a-new-top-level-traversable
  text: Cross-Origin-Embedder-Policy; type: dfn; url: coep
  text: coep-unsafe-none; type: dfn; url: coep-unsafe-none
  text: coep-credentialless; type: dfn; url: coep-credentialless
  text: coep-require-corp; type: dfn; url: coep-require-corp
  text: Cross-Origin-Opener-Policy; type: dfn; url: cross-origin-opener-policies
  text: cross-origin opener policy; type: dfn; url: cross-origin-opener-policy
  text: cross-origin-opener-policy-value; type: dfn; url: cross-origin-opener-policy-value
  text: cross-origin opener policy enforcement result; type: dfn; url:coop-enforcement-result
  text: crossOriginIsolated; type:dfn; url:concept-settings-object-cross-origin-isolated-capability
  text: crossOriginGet; type:dfn; url:crossoriginget-(-o,-p,-receiver-)
  text: crossOriginGetOwnPropertyHelper; type:dfn; url:crossorigingetownpropertyhelper-(-o,-p-)
  text: crossOriginProperties; type:dfn; url:crossoriginproperties-(-o-)
  text: crossOriginSet; type:dfn; url:crossoriginset-(-o,-p,-receiver-)
  text: cross-origin isolation mode; type:dfn; url: bcg-cross-origin-isolation
  text: embedder-policy-report-only-value; type: dfn; url: embedder-policy-report-only-value
  text: embedder-policy-value; type:dfn; url:embedder-policy-value
  text: embedder-policy-value-2; type:dfn; url:embedder-policy-value-2
  text: environment; type:dfn; url:environment
  text: enforce a response's cross-origin opener policy; type:dfn; url:coop-enforce
  text: Grouping of browsing contexts; type:dfn; url:grouping-of-browsing-contexts
  text: Infrastructure for sequences of documents; type:dfn; url:infrastructure-for-sequences-of-documents
  text: initialize a worker global scope's policy container; type:dfn; url:initialize-worker-policy-container
  text: Integration with the JavaScript agent cluster formalism; type:dfn; url:integration-with-the-javascript-agent-cluster-formalism
  text: is origin-keyed; type:dfn; url:is-origin-keyed
  text: loading web pages supporting concepts; type:dfn; url:loading-web-pages-supporting-concepts
  text: logical; type:dfn; url:cross-origin-isolation-logical
  text: location-getownproperty; type:dfn; url:location-getownproperty
  text: matching-coop; type:dfn; url:matching-coop
  text: needs a browsing context group switch; type:dfn; url: coop-enforcement-bcg-switch
  text: navigation params; type:dfn; url:navigation-params
  text: navigation-params-hh; type:dfn; url:navigation-params-hh
  text: navigation-params-origin; type:dfn; url:navigation-params-origin
  text: coop-enforcement-bcg-switch; type:dfn; url:coop-enforcement-bcg-switch
  text: policy container; type: dfn; url: policy-container
  text: policy-container-embedder-policy; type: dfn; url: policy-container-embedder-policy
  text: popup sandboxing flag set; type: dfn; url: popup-sandboxing-flag-set
  text: queue a violation report for browsing context group switch when navigating to a COOP response; type:dfn; url:coop-violation-navigation-to
  text: Queue a violation report for browsing context group switch when navigating away from a COOP response; type:dfn; url:coop-violation-navigation-from
  text: obtaining a cross-origin embedder policy; type:dfn; url:obtain-an-embedder-policy
  text: obtain a cross-origin opener policy; type:dfn; url:obtain-coop
  text: obtain a browsing context to use for a navigation response; type:dfn; url:obtain-browsing-context-navigation
  text: obtain a similar-origin window agent; type:dfn; url:obtain-similar-origin-window-agent
  text: obtaining a similar-origin window agent; type:dfn; url:obtain-similar-origin-window-agent
  text: origin; type:dfn; url:concept-origin
  text: report-only value; type:dfn; url:coop-struct-report-only-value
  text: removing a top-level browsing context; type:dfn; url:bcg-remove
  text: response; type:dfn; url:concept-response
  text: same-origin-allow-popups; type:dfn; url:coop-same-origin-allow-popups
  text: same-origin-plus-coep; type:dfn; url:coop-same-origin-plus-coep
  text: shared abstract operations; type:dfn; url:shared-abstract-operations
  text: top-level browsing context; type:dfn; url:top-level-browsing-context
  text: same origin; type:dfn; url:same-origin
  text: unsafe-none; type:dfn; url:coop-unsafe-none
  text: virtual browsing context group id; type:dfn; url:virtual-browsing-context-group-id
  text: WindowProxy; type:dfn; url:the-window-proxy-exotic-object
  text: windowproxy-get; type:dfn; url:windowproxy-get
  text: windowproxy-getownproperty; type:dfn; url:windowproxy-getownproperty
  text: windowproxy-set; type:dfn; url:windowproxy-set
  text: windows; type:dfn; url:windows
  text: window open steps; type:dfn; url:window-open-steps
  text: would need a browsing context group switch due to report-only; type:dfn; url:coop-enforcement-bcg-switch-report-only
  <!--text: A; type:dfn; url:A-->
  <!--text: A; type:dfn; url:A-->

urlPrefix: https://webidl.spec.whatwg.org/#LegacyUnenumerableNamedProperties
  text: DOMException; type:dfn; url:dfn-DOMException
  text: LegacyUnenumerableNamedProperties; type:dfn; url:LegacyUnenumerableNamedProperties
  text: SecurityError; type:dfn; url:securityerror

urlPrefix: https://tc39.es/ecma262/#sec-execution-contexts
  text: javascript execution context; type:dfn; url:sec-execution-contexts

urlPrefix: https://httpwg.org/specs/rfc8941.html; spec: Structured-Fields
  text: structured headers; type:dfn; url:specify
  text: token; type:dfn; url:token

urlPrefix: https://fetch.spec.whatwg.org/; spec: Fetch
  text: cross-origin-resource-policy; type:dfn; url:http-cross-origin-resource-policy
  text: cross-origin resource policy internal check; type:dfn; url:cross-origin-resource-policy-internal-check
  text: http-network-or-cache fetch; type:dfn; url:concept-http-network-or-cache-fetch
  text: queue a cross-origin embedder policy corp violation report; type:dfn; url:queue-a-cross-origin-embedder-policy-corp-violation-report
  text: request-includes-credentials; type:dfn; url:response-request-includes-credentials
  text: redirect-tainted origin; type:dfn; url:concept-request-tainted-origin

</pre>

<pre class="link-defaults">
  spec:fetch; type:dfn; for:/; text:response
  spec:fetch; type:dfn; text:client
  spec:fetch; type:dfn; text:current url
  spec:fetch; type:dfn; text:mode
  spec:fetch; type:dfn; for:Request; text:request
  spec:fetch; type:dfn; for:response; text:header list
  spec:html; type:dfn; for:/; text:origin
  spec:html; type:dfn; for:Window; text:browsing context
  spec:html; type:dfn; text:environment
  spec:html; type:dfn; for:environment settings object; text:global object
  spec:url; type:dfn; for:/; text:url
  spec:url; type:dfn; text:scheme
</pre>

<style>
.monkey-patch {
    padding: .5em;
    border: thin solid #ddd;
    border: thin solid 1px;
    border-radius: .5em;
    margin: .5em calc(-0.5em - 1px);
    background-color: rgba(255, 255, 0, 0.03);
    backdrop-filter: blur(5px);
    box-shadow: 0px 5px 5px 0px rgba(0, 0, 0, 0.05);
}

.brief {
  line-height: 10%;
}

.customHighlight {
  padding-top:9px ;
  padding-bottom:9px ;
  background-color: rgba(255,255,0,0.3)
}

</style>

Introduction { #introduction }
============

<em>This section is not normative.</em>

Recommended readings {#recommended-readings}
--------------------
- The [[explainer]] for Document-Isolation-Policy.
- The [[Spectre]] vulnerability.
- The [=Cross-Origin-Opener-Policy=] ([=COOP=]) section of the HTML spec.
- The [=Cross-Origin-Embedder-Policy=] ([=COEP=]) section of the HTML spec.
- How and why [=Cross-Origin-Opener-Policy=] ([=COOP=]) and
  [=Cross-Origin-Embedder-Policy=] ([=COEP=]) are granting the
  [crossOriginIsolated](concept-settings-object-cross-origin-isolated-capability)
  capability. See [[WhyCoopCoep]].

# Integration with HMTL # {#dip-html}

This section defines a monkey-patch over [[!HTML]].

## Supporting concepts when loading web pages ## {#dip-supporting-concepts}

### Cross-origin-opener-policies ### {#dip}

Modify the definition of "[=same-origin-plus-coep=]":

<div class="monkey-patch">

This behaves the same as "same-origin", with the addition that it sets the
(new) [=top-level browsing context=]'s [=browsing context group|group=]'s
[=bcg-coi-key|agent cluster cross-origin isolation key=]'s [=cross-origin
isolation mode=] to one of "[=logical=]" or "[=concrete=]".

</div>

#### Browsing context group switches due to cross-origin opener policy #### {#dip-bcg-switch}

Modify step 4 of the [=obtain a browsing context to use for a navigation response=] algorithm:

<div class="monkey-patch">

4. If *navigationCOOP*'s value is "[=same-origin-plus-COEP=]", then:
  1. Let *crossOriginIsolationMode* be either "[=logical=]" or "[=concrete=]".
     The choice of which is implementation-defined.
  2. Set *newBrowsingContext*'s [=browsing context group|group=]'s
     [=bcg-coi-key|agent cluster cross-origin isolation key=] to
     {*coopEnforcementResult*'s [=origin=], *crossOriginIsolationMode*}. 

</div>

### Document Isolation Policies ### {#dip-dip}

Add a new subsection to the [=loading web pages supporting concepts=] section
of the HTML spec.

<div class="monkey-patch">

A <dfn lt="dip-value">document isolation policy value</dfn> is one of three
strings that controls [=agent cluster=] allocation and the fetching of
cross-origin resources without explicit permission from resource owners.

* "<dfn lt="dip-none">none</dfn>":
  This is the default value. When this value is used, cross-origin resources
  can be fetched without giving explicit permission through the [=CORS
  protocol=] or the '[=Cross-Origin-Resource-Policy=]' header. The document is
  assigned to a non cross-origin isolated [=agent cluster=].

* "<dfn lt="dip-isolate-and-require-corp">isolate-and-require-corp</dfn>":
  When this value is used, fetching cross-origin resources requires the
  server's explicit permission through the [=CORS protocol=] or the
  '[=Cross-Origin-Resource-Policy=]' header. The document is also assigned to a
  cross-origin isolated [=agent cluster=].

* "<dfn lt="dip-isolate-and-credentialless">isolate-and-credentialless</dfn>":
  When this value is used, fetching cross-origin no-CORS resources omits
  credentials. In exchange, an explicit '[=Cross-Origin-Resource-Policy=]'
  header is not required. Other requests sent with credentials require the
  server's explicit permission through the [=CORS protocol=] or the
  '[=Cross-Origin-Resource-Policy=]' header. The document is also assigned to a
  cross-origin isolated [=agent cluster=].

A <dfn lt="dip-struct">document isolation policy</dfn> consists of:
* A <dfn lt="dip-struct-value">value</dfn>, which is a [=dip-value|document
  isolation policy value=], initially "[=dip-none|none=].
* A <dfn lt="dip-reporting-endpoint">reporting endpoint</dfn>, initially the
  empty string.
* A <dfn lt="dip-report-only-value">report-only value</dfn>, which is a
  [=dip-value|document
  isolation policy value=], initially "[=dip-none|none=].
* A <dfn lt="dip-report-only-endpoint">report-only reporting endpoint</dfn>,
  initially the empty string.

To <dfn lt="obtain-coi-key">obtain a cross-origin agent cluster isolation
key</dfn> given null or a [=dip-struct|document isolation policy=]
*documentIsolationPolicy* and an [=origin=] *origin*:
1. If *documentIsolationPolicy* is null, return null.
2. If *documentIsolationPolicy*'s [=dip-struct-value|value=] is
   "[=dip-none|none=]", then return null.
3. Let *crossOriginIsolationMode* be either "[=logical=]" or "[=concrete=]".
   The choice of which is implementation-defined.
4. Let *crossOriginIsolationKey* be a new [=coi-agent-cluster-key|agent cluster
   cross-origin isolation key=].
5. Set *crossOriginIsolationKey* to {*origin*, *crossOriginIsolationMode*}. 
6. Return *crossOriginIsolationKey*.

#### The headers #### {#dip-headers}

The '<dfn lt="dip-header">Document-Isolation-Policy</dfn>' and
'<dfn lt="dip-report-only-header">Document-Isolation-Policy-Report-Only</dfn>'
HTTP response headers allow a server to declare a [=dip-struct|document isolation
policy=] for a [=document=]. These headers are [=structured headers=] whose values
must be [=token=].

The valid [=token=] values are the [=dip-value|document isolation policy
values=]. The token may also have attached [=parameters=]; of these, the
"report-to" parameter can have a [=valid URL string=] identifying an
appropriate reporting endpoint.

To <dfn lt="obtain-dip">obtain a document isolation policy</dfn> given a
[=response=] *response* and an [=environment=] *environment*:

1. Let *policy* be a new [=dip-struct|document isolation policy=].
2. If *environment* is a [=non-secure context=], then return *policy*.
3. Let *parsedItem* be the result of [=getting a structured field value=] with
   `Document-Isolation-Policy` and "item" from *response*'s [=header list=].
4. If *parsedItem* is non-null:
   1. If *parsedItem*[0] is
      "[=dip-isolate-and-require-corp|isolate-and-require-corp=]" or
      "[=dip-isolate-and-credentialless|isolate-and-credentialless=]", set
      *policy*'s [=dip-struct-value|value=] to *parsedItem*[0].
   2. If *parsedItem*[1]["report-to"] [=map-exists|exists=], then set *policy*'s
      [=dip-reporting-endpoint|reporting endpoint=] to
      *parsedItem*[1]["report-to"].
5. Set *parsedItem* be the result of [=getting a structured field value=] with
   `Document-Isolation-Policyi-Report-Only` and "item" from *response*'s
   [=header list=].
6. If *parsedItem* is non-null:
   1. If *parsedItem*[0] is
      "[=dip-isolate-and-require-corp|isolate-and-require-corp=]" or
      "[=dip-isolate-and-credentialless|isolate-and-credentialless=]", set
      *policy*'s [=dip-report-only-value|report-only value=] to
      *parsedItem*[0].
   2. If *parsedItem*[1]["report-to"] [=map-exists|exists=], then set
      *policy*'s [=dip-report-only-endpoint|report-only reporting endpoint=] to
      *parsedItem*[1]["report-to"].
7. Return policy.

</div>

### Policy containers ### {#dip-policy-containers}

Add the following members to the [=policy container=] struct:

<div class="monkey-patch">

* A <dfn lt="policy-container-dip">document isolation policy</dfn>, which is a
  [=dip-struct|document isolation policy=]. It is initially a new
  [=dip-struct|document isolation policy=].

* An <dfn lt="policy-container-coi-key">agent cluster cross-origin isolation
  key</dfn>, which is null or an [=coi-agent-cluster-key|agent cluster
  cross-origin isolation key=]. It is initially null. This
  [=coi-agent-cluster-key|agent cluster cross-origin isolation key=] is based
  on the [=dip-struct|document isolation policy=] of the document. It overrides the 
  [=bcg-coi-key|agent cluster cross-origin isolation key=] stored in the
  [=browsing context group=].

</div>

Add step 5 and 6 to the [=clone a policy container=] algorithm:

<div class="monkey-patch">

5. Set *clone*'s [=policy-container-dip|document isolation policy=] to a copy
   of *policyContainer*'s [=policy-container-dip|document isolation policy=].

6. Set *clone*'s [=policy-container-coi-key|agent cluster cross-origin
   isolation key=] to a copy of *policyContainer*'s
   [=policy-container-coi-key|agent cluster cross-origin isolation key=].

</div>

Add step 6 and 7 to the [=create a policy container from a fetch response =]:

<div class="monkey-patch">

6. If *environment* is non-null, then set *result*'s
   [=policy-container-dip|document isolation policy=] to the result of
   [=obtain-dip|obatining a document isolation policy=] given *response* and
   *environment*.

7. Set *result*'s [=policy-container-coi-key|agent cluster cross-origin
   isolation key=] to the result of [=obtain-coi-key|obtaining a cross-origin
   isolation key=] given *result*'s [=policy-container-dip|document isolation
   policy=] and *response*'s [=URL=]'s [=origin=].

</div>

Add step 3 to the [=initialize a worker global scope's policy container=]:

<div class="monkey-patch">

3. If *workerGlobalScope*'s [=owner set=]'s [=list-size|size=] is 1, then:
   1. Set *workerGlobalScope*'s [=policy container=]'s
      [=policy-container-dip|document isolation policy=] to *workerGlobalScope*'s
      [=owner set=][0]'s [=relevant settings object=]'s [=policy container=]'s
      [=policy-container-dip|document isolation policy=].
   2. Set *workerGlobalScope*'s [=policy container=]'s
      [=policy-container-coi-key|agent cluster cross-origin
      isolation key=] to *workerGlobalScope*'s [=owner set=][0]'s [=relevant
      settings object=]'s [=policy container=]'s
      [=policy-container-coi-key|agent cluster cross-origin isolation key=].

</div>


## Browsing contexts ## {#dip-browsing-contexts}

### Browsing contexts ### {#dip-bc}

<div class="monkey-patch">

Add a step 5 to the [=create a new browsing context and document=] algorithm:

5. Let *creatorAgentClusterCOIKey* be null.

</div>

Add a step 5.4 to the [=create a new browsing context and document=] algorithm:

<div class="monkey-patch">

5.4 Set *creatorAgentClusterCOIKey* to *creator*'s [=policy container=]'s
[=policy-container-coi-key|agent cluster cross-origin isolation key=].

</div>

Modify step 9 of the [=create a new browsing context and document=] algorithm:

<div class="monkey-patch">

9. Let *agent* be the result of obtaining a similar-origin window agent given
   *origin*, *group*, false, and *creatorAgentClusterCOIKey*.

</div>

### Grouping of browsing contexts ### {#dip-grouping-of-browsing-contexts}

Remove the following line:

<div class="monkey-patch">

A [=browsing context group=] has a cross-origin isolation mode, which is a
[=cross-origin isolation mode=]. It is initially "none".

</div>

Add the following line:

<div class="monkey-patch">

A [=browsing context group=] has an <dfn lt="bcg-coi-key">agent cluster
cross-origin isolation key</dfn>, which is null or an
[=coi-agent-cluster-key|agent cluster cross-origin isolation key=] . It is
initially null. It is set by [=Cross-Origin-Opener-Policy=], and is the default
[=coi-agent-cluster-key|agent cluster cross-origin isolation key=] for
documents inside the [=browsing context group=]. However, it can be overriden by the 
[=policy-container-coi-key|policy container's agent cluster cross-origin
isolation key=] when a document has a [=dip-struct|document isolation policy=].

</div>

## Document lifecycle ## {#dip-document-lifecycle}

### Shared document creation infrastructure ### {#dip-document-creation}

Modify step 8.4 of the [=create and initialize a Document object=] algorithm:

<div class="monkey-patch">

Let *agent* be the result of [=obtaining a similar-origin window agent=] given
*navigationParams*'s [=origin=], *browsingContext*'s [=browsing context
group|group=], *requestsOAC*, and *navigationParams*'s [=policy container=]'s
[=policy-container-coi-key|agent cluster cross-origin isolation key=].

</div>

## Agents and agent clusters ## {#dip-agent-clusters}

Add the following to the [=Integration with the JavaScript agent cluster
formalism=]:

<div class="monkey-patch">

An <dfn lt="coi-agent-cluster-key">agent cluster cross-origin isolation
key</dfn> is a [=tuple=] of an [=origin=] and a [=cross-origin isolation
mode=].

</div>

Change the definition of the [=agent cluster key=]:

<div class="monkey-patch">

An [=agent cluster key=] is either a [=site=], or a [=tuple origin=], or a
[=tuple=] of a [=tuple origin=] and an [=coi-agent-cluster-key|agent cluster
cross-origin isolation key=].

</div>

Modify the [=obtain a similar-origin window agent=] algorithm definition:

<div class="monkey-patch">

To [=obtain a similar-origin window agent=], given an [=origin=] *origin*, a
[=browsing context group=] *group*, a boolean *requestsOAC*, and null or an
[=coi-agent-cluster-key|agent cluster cross-origin isolation key=]
*agentClusterCOIKey*, run these steps:

</div>

Modify step 3 of the [=obtain a similar-origin window agent=] algorithm:
<div class="monkey-patch">

3. If *agentClusterCOIKey* is not *null*, then set *key* to {*origin*,
   *agentClusterCOIKey*}.
4. Otherwise, if *group's* [=bcg-coi-key|agent cluster cross-origin isolation
   key=] is not *null*, then set *key* to {*origin*, *group's* [=bcg-coi=key|agent
   cluster cross-origin isolation key=]}.

</div>

Modify steps 6.2 and 6.3 of the [=obtain a similar-origin window agent=] algorithm:

<div class="monkey-patch">

6.2 If *key* has an [=coi-agent-cluster-key|agent cluster cross-origin
isolation key=], set *agentCluster*'s [=cross-origin isolation mode=] to
*key*'s [=coi-agent-cluster-key|agent cluster cross-origin isolation key=]'s
[=cross-origin isolation mode=].

6.3 Set *agentCluster*'s [=is origin-keyed=] to false if *key* equals *site*; otherwise true.

</div>

# Integration with Fetch # {#dip-fetch}

This section defines a monkey-patch over [[!Fetch]].

## Requests ## {#dip-requests}

Add a new algorithm to the [=Requests=] part of Fetch:

<div class="monkey-patch">

To check if <dfn>Document-Isolation-Policy allows credentials</dfn>, given a
[=request=] *request*, run these steps:
1. If *request*’s [=mode=] is not "no-cors", then return true.
2. If *request*’s [=client=] is null, then return true.
3. If *request*’s [=client=]’s [=policy container=]’s
   [=policy-container-dip|document-isolation-policy=]’s [=dip-value|value=] is not
   "[=dip-isolate-and-credentialless|isolate-and-credentialless=]", then return true.
4. If *request*’s [=origin=] is [=same origin=] with *request*’s [=current
   URL=]’s [=origin=] and *request* does not have a [=redirect-tainted origin=],
   then return true.
5. Return false.

</div>

## 'Cross-Origin-Resource-Policy' header ## {#dip-corp}

Add a new enum definition to the [=Cross-Origin-Resource-Policy=] section of Fetch:

<div class="monkey-patch">

A <dfn lt="corp-check-result">cross-origin resource policy internal check result</dfn>
is one of five values:
* "<dfn lt="corp-check-allowed">allowed</dfn>"
* "<dfn lt="corp-check-blocked">blocked</dfn>"
* "<dfn lt="corp-check-blocked-coep">blocked-by-coep</dfn>"
* "<dfn lt="corp-check-blocked-dip">blocked-by-dip</dfn>"
* "<dfn lt="corp-check-blocked-coep-dip">blocked-by-coep-and-dip</dfn>"

</div>

Modify the [=cross-origin resource policy check=] algorithm:

<div class="monkey-patch">

4. Let *documentIsolationPolicy* be *settingsObject*’s [=policy container=]’s
   [=policy-container-dip|document-isolation-policy=].
5. Let *reportOnlyCheck* be the the result of the [=cross-origin resource
   policy internal check=] with *origin*,  *embedderPolicy*’s
   [=embedder-policy-report-only-value|report only value=],
   *documentIsolationPolicy*’s [=dip-report-only-value|report only value=],
   *response*, and *forNavigation*. 
6. If *reportOnlyCheck* is "[=corp-check-blocked-coep|blocked-by-coep=]" or
   "[=corp-check-blocked-coep-dip|blocked-by-coep-and-dip=]", then [=queue a
   cross-origin embedder policy CORP violation report=] with *response*,
   *settingsObject*, *destination*, and true.
7. If *reportOnlyCheck* is "[=corp-check-blocked-dip|blocked-by-dip=]" or
   "[=corp-check-blocked-coep-dip|blocked-by-coep-and-dip=]", then [=queue a
   document isolation policy CORP violation report=] with *response*,
   *settingsObject*, *destination*, and true.
8. Let *check* be the the result of the [=cross-origin resource
   policy internal check=] with *origin*,  *embedderPolicy*’s
   [=embedder-policy-value-2|value=], *documentIsolationPolicy*’s
   [=dip-struct-value|report value=], *response*, and *forNavigation*. 
9. If *check* is "[=corp-check-allowed|allowed=]", then return **allowed**.
10. If *check* is "[=corp-check-blocked-coep|blocked-by-coep=]" or
    "[=corp-check-blocked-coep-dip|blocked-by-coep-and-dip=]", then [=queue a
    cross-origin embedder policy CORP violation report=] with *response*,
    *settingsObject*, *destination*, and false.
11. If *reportOnlyCheck* is "[=corp-check-blocked-dip|blocked-by-dip=]" or
    "[=corp-check-blocked-coep-dip|blocked-by-coep-and-dip=]", then [=queue a
    document isolation policy CORP violation report=] with *response*,
    *settingsObject*, *destination*, and false.
12. Return **blocked**.

</div>

Modify the [=cross-origin resource policy internal check=] algorithm definition:

<div class="monkey-patch">

To perform a [=cross-origin resource policy internal check=], given an [=origin=]
*origin*, an [=embedder policy value=] *embedderPolicyValue*, a
[=dip-value|document isolation policy value=] *documentIsolationPolicyValue*, a
[=response=] *response*, and a boolean *forNavigation*, run these steps:

</div>

Modify the [=cross-origin resource policy internal check=] algorithm:

<div class="monkey-patch">

4. Let *checkResult* be a [=corp-check-result|cross-origin resource policy
   internal check result=] with value "[=corp-check-blocked|blocked=]".
6. If *policy* is null, then:
   1. Let *upgradeDueToCOEP* be false.
   2. Let *upgradeDueToDIP* be false.
   3. Switch on *embedderPolicyValue*:
      * "[=coep-unsafe-none|unsafe-none=]"
        1. Do nothing.
      * "[=coep-credentialless|credentialless=]"
        1. Set *upgradeDueToCOEP* to true if:
           * *response*’s [=request-includes-credentials=] is true, or
           * *forNavigation* is true.
      * "[=coep-require-corp|require-corp=]"
        1. Set *upgradeDueToCOEP* to true.
   4. Switch on *documentIsolationPolicyValue*:
      * "[=dip-none|dip-none=]"
        1. Do nothing.
      * "[=dip-isolate-and-credentialless|isolate-and-credentialless=]"
        1. Set *upgradeDueToDIP* to true if *response*’s
           [=request-includes-credentials=] is true.
      * "[=dip-isolate-and-require-corp|isolate-and-require-corp=]"
        1. Set *upgradeDueToDIP* to true.
   5. If *upgradeDueToCOEP* or *upgradeDueToDIP* is true, set *policy* to
      'same-origin'.
   6. If *upgradeDueToCOEP* is true, then:
      1. If *upgradeDueToDIP* is true, then set *checkResult* to
         "[=corp-check-blocked-coep-dip|blocked-by-coep-and-dip=]".
      2. Otherwise, set *checkResult* to
         "[=corp-check-blocked|blocked-by-coep=]". 
   7. Otherwise, if *upgradeDueToDIP* is true, then set *checkResult* to
         "[=corp-check-blocked-dip|blocked-by-dip=]".
7. Switch on *policy*:
   * null
   * `cross-origin`
     1. Set *checkResult* to "[=corp-check-allowed|allowed=]".
   * `same-origin`
     1. If *origin* is [=same origin=] with *response*’s [=URL=]’s [=origin=],
        then set *checkResult* to "[=corp-check-allowed|allowed=]".
   * `same-site`
     1. If all of the following are true
        * *origin* is [=schemelessly same site=] with *response*’s [=URL=]’s
          *origin*
        * *origin*’s [=scheme=] is "https" or *response*’s [=URL=]’s [=scheme=]
          is not "https"
     2. then set *checkResult* to "[=corp-check-allowed|allowed=]".
8. Return *checkResult*.

</div>

Add a new algorithm to the [=Cross-Origin-Resource-Policy=] section of Fetch:

<div class="monkey-patch">

To <dfn>queue a document isolation policy CORP violation report</dfn>, given a
[=response=] *response*, an [=environment settings object=] *settingsObject*, a
string *destination*, and a boolean *reportOnly*, run these steps:
1. Let *endpoint* be *settingsObject*’s [=policy container=]’s
   [=policy-container-dip|document-isolation-policy=]’s
   [=dip-report-only-endpoint|report only reporting endpoint=] if *reportOnly*
   is true and *settingsObject*’s [=policy container=]’s
   [=policy-container-dip|document-isolation-policy=]’s
   [=dip-reporting-endpoint|reporting endpoint=] otherwise.
2. Let *serializedURL* be the result of [=serializing a response URL for
   reporting=] with *response*.
3. Let *disposition* be "reporting" if reportOnly is true; otherwise "enforce".
4. Let *body* be a new object containing the following properties:
   <pre class=simpledef>
   "type": "corp"
   "blockedURL": serializedURL
   "destination": destination
   "disposition": disposition
   </pre>
5. [=Generate and queue a report=] for *settingsObject*’s [=global object=] given the "dip", *endpoint*, and *body*. 

</div>

## HTTP-network-or-cache fetch ## {#dip-http-fetch}

Add a step 8.5 to the [=HTTP-network-or-cache fetch=] algorithm:

<div class="monkey-patch">

5. If [=Document-Isolation-Policy allows credentials=] with *request* returns
   false, then set *includeCredentials* to false.

</div>

# Security considerations # {#dip-security}

<em>This section is not normative.</em>

Document-Isolation-Policy is a security API whose goal is to give access to
potentially dangerous APIs (like Shared Array Buffers) in a safe manner. In
order to do so, Document-Isolation-Policy relies on the user agent backing the
agent cluster separation with effective process separation. If the user agent
is not able to do so (e.g. it cannot support Out-of-Process Iframes), the user
agent should set a cross-origin isolation mode of "logical" for documents with
Document-Isolation-Policy. This will prevent the document from getting access
to the dangerous APIs gated behind cross-origin isolation.

This choice of cross-origin isolation mode should be a static choice made for
all origins on a user's machine, to avoid leaking the state of other documents on
the user's machine.

For a longer discussion of the threat model this API adresses, please refer to
the [[explainer]].

# Privacy considerations # {#dip-privacy}

<em>This section is not normative.</em>

No additional privacy concerns beyond the risks mentionned in the security
considerations section.