Intent to Ship: Document-Isolation-Policy

[Chromestatus]

Contact emails

cl...@google.com

Explainer

https://github.com/WICG/document-isolation-policy/blob/main/README.md

Specification

https://wicg.github.io/document-isolation-policy

Summary

Document-Isolation-Policy allows a document to enable crossOriginIsolation for itself, without having to deploy COOP or COEP, and regardless of the crossOriginIsolation status of the page. The policy is backed by process isolation. Additionally, the document non-CORS cross-origin subresources will either be loaded without credentials or will need to have a CORP header.

Blink component

Blink>SecurityFeature

TAG review

https://github.com/w3ctag/design-reviews/issues/995

TAG review status

Pending

Origin Trial Name

Document Isolation Policy

Chromium Trial Name

DocumentIsolationPolicy

Origin Trial documentation link

https://github.com/WICG/document-isolation-policy

WebFeature UseCounter name

kDocumentIsolationPolicyRequireCorp

Risks

Interoperability and Compatibility

None

Gecko: No signal (https://github.com/mozilla/standards-positions/issues/1074)

WebKit: Negative (https://github.com/WebKit/standards-positions/issues/399) Safari is concerned about our first version of the API for Android, which would have us not provide access to crossOriginIsolation-gated API on very low end devices. We have revised this plan, and plan to launch on low end Android as well.

Web developers: Positive (https://github.com/WICG/proposals/issues/145) See the initial WICG proposal. We've also been in touch with developers at Google and Microsoft who think the proposed API will allow them to use Shared-Array-Buffers. Gmail, Google Meet and Zoom have experimented the feature during Origin Trial. While they still have work to do to fully roll it out, they now see deploying crossOriginIsolation as possible. Deploying crossOriginIsolation using COOP and COEP was previously impossible for them.

Other signals:

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

We have no plans on launching the feature in Android WebView in the foreseeable future due to lack of process isolation in Android WebView.

Debuggability

None

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

No

We are planning to launch in M137 on desktop only (ChromeOS, Linux, Windows, MacOS). Android requires more development work due to the different process allocation model. We will add support on Android as soon as possible. However, we'd like to launch for desktop as soon as possible to help developers currently in the ungated SAB reverse origin trial get off the deprecation OT. Support on Android WebView is not possible due to the lack of process isolation.

Is this feature fully tested by web-platform-tests?

Yes

https://wpt.fyi/results/html/document-isolation-policy?label=experimental&label=master&aligned

Flag name on about://flags

None

Finch feature name

DocumentIsolationPolicy

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://g-issues.chromium.org/issues/333029146

Availability expectation

As of now, other browser vendors have not given us signals that they plan to implement this.

Adoption expectation

Gmail, Google Meet and Zoom are interested in rolling out the feature to gain access to SharedArrayBuffers. They will need a bit more work, but we expect that they will be rolling it out in the next 12 months.

Estimated milestones

Shipping on desktop	137
Origin trial desktop first	132
Origin trial desktop last	134
Origin trial extension 1 end milestone	136

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

None

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5141940204208128?gate=5070133686173696

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOmohS%2BzyOX6amnva6t_HBsXPXAFoZEri7A78ka7-OwA66B%3Dmw%40mail.gmail.com
Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/p52-T7m3rOM?e=48417069
Intent to Extend Experiment 1: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/67a63f67.2b0a0220.2908d.02b2.GAE%40google.com

This intent message was generated by Chrome Platform Status.

[Alex Russell]

LGTM1. We're excited to see this move forward.

[Dan Clark]

LGTM2

[Domenic Denicola]

This generally looks really good, with an amazing detailed explainer and similarly-detailed spec. I am excited to approve it.

However I have a couple of questions about mismatches between the explainer and spec I'd like to hear back on first:

• https://github.com/WICG/document-isolation-policy/blob/main/README.md#reporting seems pretty different from the only reporting support I find in the spec, at https://wicg.github.io/document-isolation-policy/#queue-a-document-isolation-policy-corp-violation-report
• https://github.com/WICG/document-isolation-policy/blob/main/README.md#interactions-with-workers talks about worker inheritance, but I don't see any of that in the spec. (Maybe it's taken care of automatically by the policy container infrastructure or something similar?)

[Camille Lamy]

Thanks!

On Tue, Apr 22, 2025 at 11:19 AM Domenic Denicola <dom...@chromium.org> wrote:

This generally looks really good, with an amazing detailed explainer and similarly-detailed spec. I am excited to approve it.

However I have a couple of questions about mismatches between the explainer and spec I'd like to hear back on first:

• https://github.com/WICG/document-isolation-policy/blob/main/README.md#reporting seems pretty different from the only reporting support I find in the spec, at https://wicg.github.io/document-isolation-policy/#queue-a-document-isolation-policy-corp-violation-report

Yes following feedback from developers, we've only implemented the reporting for subresources being blocked (similar to COEP) and as described in the spec. If developers tell us that they also need the reporting on same-origin frames in the browsing context group we'll implement that as well, but the developers who tried the OT didn't think it was useful for them, so we've held off implementing that. I will update the explainer and move this part of the reporting as a potential follow up.

 

• https://github.com/WICG/document-isolation-policy/blob/main/README.md#interactions-with-workers talks about worker inheritance, but I don't see any of that in the spec. (Maybe it's taken care of automatically by the policy container infrastructure or something similar?)

Right, for this I think both the explainer and the spec should be updated as this was modified during the OT. Following the OT, what we ended up with was:

- ServiceWorkers can't have a DocumentIsolationPolicy by themselves. However, if they handle a resource request from a document with DIP, they will apply the subresource checks as expected. If SeviceWorkers themselves want access to COI gated APIs, then they should just deploy COEP.

- DedicatedWorkers inherit their DocumentIsolationPolicy from their embedders. This is different from COEP, which will block the worker script from loading if its COEP doesn't match the COEP of its creator. We were told by developers that having the script blocked from loading made rollout harder, so we opted for a different solution for DocumentIsolationPolicy. Provided that there are no compatibility issues, we'll also try to modify the COEP behavior in the future so that it matches DIP.

- SharedWorkers are supposed to set their DIP by themselves, like for COEP. I say supposed here because a SharedWorker created by a crossOriginIsolated document can be not crossOriginIsolated, but our implementation does not support the reverse. We'd have to change the moment at which we allocate processes for the SharedWorker to make it work, which is likely complicated. Alternatively, maybe SharedWorkers should also just inherit COEP and DIP from their creators when they are same-origin, just as is the case for DedicatedWorkers. This would make it possible for SharedWorkers to have access to COI gated APIs when they were created in a document with COI. That said, it's possible to change this after release, since we would not have compatibility risks (i.e. currently SharedWorkers can never get COI, with this change they might).

I will update the explainer and the spec to reflect the current state of the interactions with workers.

[Camille Lamy]

I have updated the explainer to reflect what we're shipping in terms of reporting.

I have also updated the spec to have the DocumentIsolationPolicy inherit DIP from its owner through the PolicyContainer: https://wicg.github.io/document-isolation-policy/#dip-policy-containers. This should ensure that the subresource checks are appropriately done. When it comes to agent clustering, we have the following behavior in the spec already:

• Dedicated Workers are put in the agent cluster of their creator: step 3 of https://html.spec.whatwg.org/multipage/webappapis.html#obtaining-a-worker/worklet-agent. Which means that if the creator has COI due to DIP, the DedicatedWorker would have it as well. This match what we will ship with DocumentIsolationPolicy.
• SharedWorkers get an origin-keyed agent cluster which does not have COI: step 2 of https://html.spec.whatwg.org/multipage/webappapis.html#obtaining-a-worker/worklet-agent. This agent is obtained on step 4 of the run a worker algorithm https://html.spec.whatwg.org/multipage/workers.html#run-a-worker, which happens before the main fetch. Then on step 12.3.4 of the same algorithm, once we have gotten the script response we check its COEP, and if it has one we set the agent cluster to crossOriginIsolated. There's a big note that it should be done earlier when the agent cluster is created and that the spec should be rewritten. Which is true, because Chrome cannot actually implement this as the process we pick to host the SharedWorker is chosen before we get the response and is always set to a non crossOriginIsolated process. Which means that the SharedWorker never gets crossOriginIsolation, regardless of whether it returns a COEP or a DocumentIsolationPolicy (but we do apply the checks on subresources). With the spec as it is, DIP never gets you a COI shared worker (since step 12.3.4 checks for COEP specifically and will not return true), and this is what we have implemented.

My reading is that what we have in the monkey patch spec + the existing HTML spec now accurately describes what we implemented for DocumentIsolationPolicy. However, the general situation for SharedWorkers and crossOriginIsolation is not satisfactory, regardless of whether COI comes from COEP and DIP. So going forward, we should rework how COI and SharedWorkers interact. In my opinion, we should either inherit COEP/DIP/COI status from the SharedWorker creator, or it needs to be passed to the SharedWorker at creation time as a parameter (as opposed to relying on the script response). I am not sure which makes more sense. That said, since it involves COEP as well, I would like to proceed with DocumentIsolationPolicy launch as it is right now, and do a follow up for SharedWorkers that will align both COEP and DIP. Does that sound ok?

[Yoav Weiss (@Shopify)]

LGTM3