Split the subresource-loading explainer into the core part and the ex… (

#645)

* Split the subresource-loading explainer into the core part and the extension part (#623 #641)

This is the almost mechanical *refactoring*, splitting the
subresource-loading explainer into the core part and the extension
part. The related issues are #624 and #641.

In a follow-up PR, we might want to refine the core part so that we
can write extension parts more easily, such as having well-defined
terminologies and hook points.

explainers/subresource-loading-opaque-origin-iframes.md

@@ -0,0 +1,100 @@
+# Subresource loading with Web Bundles: Support opaque origin iframes
+
+Last updated: Apr 2021
+
+This is an extension to [Subresource loading with Web Bundles]. This extension
+allows a bundle to include `urn:uuid:` URL resources, which will be used to
+create an opaque origin iframe.
+
+## Goals
+
+Support the use case of
+[WebBundles for Ad Serving](https://github.com/WICG/webpackage/issues/624).
+
+## Extension to [Subresource loading with Web Bundles]
+
+In this section, _the explainer_ means the [Subresource loading with Web
+Bundles] explainer.
+
+### Allow `urn:uuid:` resources
+
+In addition to the same origin subresource explained in the
+[`<link>`-based API](https://github.com/WICG/webpackage/blob/main/explainers/subresource-loading.md#link-based-api)
+section in the explainer, this extension allows a bundle to include a
+[`urn:uuid:`](https://tools.ietf.org/html/rfc4122) URL subresource.
+
+### Opaque origin iframes
+
+If a `<iframe>`'s `src` attribute is a `urn:uuid:` URL subresource in the
+bundle, the iframe must be instantiated as an
+[opaque origin](https://html.spec.whatwg.org/multipage/origin.html#concept-origin-opaque)
+iframe.
+
+## Example
+
+### The bundle
+
+Suppose that the bundle, `subresources.wbn`, includes the following resources:
+
+```
+- urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+- … (omitted)
+```
+
+### The main document
+
+```html
+<link
+  rel="webbundle"
+  href="https://example.com/dir/subresources.wbn"
+  resources="urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
+/>
+
+<iframe src="urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"></iframe>
+```
+
+`urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6` is loaded from the bundle, and a
+subframe is instantiated as an
+[opaque origin](https://html.spec.whatwg.org/multipage/origin.html#concept-origin-opaque)
+iframe.
+
+Note:
+
+- `urn:uuid:` resource must be explicitly specified in `resources` attribute in
+  `<link>` elements, similar to other subresources. `scopes` attribute can be
+  also used for `urn:uuid:` resources. For example, `scopes=urn:` allows all
+  `urn:` resources.
+
+### Content Security Policy (CSP)
+
+To allow `urn:uuid` resources in CSP, the `urn:` scheme must be explicitly
+specified. "`*`" source expression does not match `urn:uuid` resources according
+to the CSP's
+[matching rule](https://w3c.github.io/webappsec-csp/#match-url-to-source-expression).
+
+For example, given this CSP header,
+
+```
+Content-Security-Policy: script-src https://example.com/script/ urn:; frame-src *
+```
+
+In the following, the first and third `<script>` will be loaded, and the second
+`<script>` and the `<iframe>` will be blocked:
+
+```
+<link rel="webbundle"
+  href="https://example.com/subresources.wbn"
+  resources="https://example.com/script/a.js
+             https://example.com/b.js
+             urn:uuid:429fcc4e-0696-4bad-b099-ee9175f023ae
+             urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
+/>
+
+<script src=”https://example.com/script/a.js”></script>
+<script src=”https://example.com/b.js”></script>
+<script src=”urn:uuid:429fcc4e-0696-4bad-b099-ee9175f023ae”></script>
+<iframe src="urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"></iframe>
+```
+
+[subresource loading with web bundles]:
+  https://github.com/WICG/webpackage/blob/main/explainers/subresource-loading.md

explainers/subresource-loading.md

@@ -1,6 +1,6 @@
 # Explainer: Subresource loading with Web Bundles
 
-Last updated: Oct 2020
+Last updated: Apr 2021
 
 We propose a new approach to load a large number of resources efficiently using
 a format that allows multiple resources to be bundled, e.g.
@@ -98,12 +98,10 @@ When the browser parses such a `link` element, it:
 
 1. Fetches the specified Web Bundle, `https://example.com/dir/subresources.wbn`.
 
-2. Records the `resources` and _delays_ fetching a subresource specified there if either
-
-   - a subresource's origin is the [same origin](https://html.spec.whatwg.org/#same-origin)
-     as the bundle's origin and its [path](https://url.spec.whatwg.org/#concept-url-path)
-     contains the bundle's path as a prefix, or
-   - a subresource's URL is a [`urn:uuid:`](https://tools.ietf.org/html/rfc4122) URL.
+2. Records the `resources` and _delays_ fetching a subresource specified there if
+   a subresource's origin is the [same origin](https://html.spec.whatwg.org/#same-origin)
+   as the bundle's origin and its [path](https://url.spec.whatwg.org/#concept-url-path)
+   contains the bundle's path as a prefix.
 
 3. As the bundle arrives, the browser fulfills those pending subresource
    fetches from the bundle's contents.
@@ -132,7 +130,6 @@ Suppose that the bundle, `subresources.wbn`, includes the following resources:
 - https://example.com/dir/a.js (which depends on ./b.js)
 - https://example.com/dir/b.js
 - https://example.com/dir/c.png
-- urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
 - … (omitted)
 ```
 
@@ -144,22 +141,19 @@ Suppose that the bundle, `subresources.wbn`, includes the following resources:
   resources="https://example.com/dir/a.js
              https://example.com/dir/b.js
              https://example.com/dir/c.png
-             urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
 />
 
 <script type=”module” src=”https://example.com/dir/a.js”></script>
 <img src=https://example.com/dir/c.png>
-<iframe src="urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6">
 ```
 
 Then, a browser must fetch the bundle, `subresources.wbn`, and load
 subresources, `a.js`, `b.js`, and `c.png`, from the bundle.
 
-`urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6` is also loaded from
-the bundle, and a subframe is instantiated as an
-[opaque origin](https://html.spec.whatwg.org/multipage/origin.html#concept-origin-opaque) frame.
-If a URL is available from an attached bundle, the browser must retrieve it from
-the bundle, instead of using any [registered custom protocol handler](https://html.spec.whatwg.org/multipage/system-state.html#dom-navigator-registerprotocolhandler)
+If a URL is available from an attached bundle, the browser must
+retrieve it from the bundle, instead of using any [registered custom
+protocol
+handler](https://html.spec.whatwg.org/multipage/system-state.html#dom-navigator-registerprotocolhandler)
 for its scheme.
 
 Note that `resources` attribute is reflected to JavaScript as a [`DOMTokenList`](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList).
@@ -204,31 +198,33 @@ set to "`webbundle`"
 For resources loaded from bundles, URL matching of CSP is done based on the URL
 of the resource, not the URL of the bundle. For example, given this CSP header:
 ```
-Content-Security-Policy: script-src https://example.com/script/ urn:; frame-src *
+Content-Security-Policy: script-src https://example.com/script/
 ```
 
-In the following, the first and third `<script>` will be loaded, and the second
-`<script>` and the `<iframe>` will be blocked:
+In the following, the first `<script>` will be loaded, but the second
+`<script>` will be blocked:
 
 ```
 <link rel="webbundle"
   href="https://example.com/subresources.wbn"
   resources="https://example.com/script/a.js
              https://example.com/b.js
-             urn:uuid:429fcc4e-0696-4bad-b099-ee9175f023ae
-             urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
 />
 
 <script src=”https://example.com/script/a.js”></script>
 <script src=”https://example.com/b.js”></script>
-<script src=”urn:uuid:429fcc4e-0696-4bad-b099-ee9175f023ae”></script>
-<iframe src="urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"></iframe>
 ```
 
-Note that `*` source expression does not match `urn:uuid` resources according
-to the CSP's [matching rule](https://w3c.github.io/webappsec-csp/#match-url-to-source-expression).
-To allow `urn:uuid` resources in CSP, the `urn:` scheme must be explicitly
-specified.
+## Extensions
+
+There are several extensions to this explainer, aiming to support
+various use cases which this explainer doesn't support:
+
+- [Subresource loading with Web Bundles: Support opaque origin iframes](./subresource-loading-opaque-origin-iframe.md)
+
+See [issue #641](https://github.com/WICG/webpackage/issues/641) for
+the motivation of splitting the explainer into the core part, this
+explainer, and the extension parts.
 
 ## Subsequent loading and Caching