Clarify how manifest image resources are fetched

[marcoscaceres]

Closes #910

This change (choose at least one, delete ones that don't apply):

• Makes a normative change (adds a proper fetch algorithm for manifest image resources, with client and mode requirements)

What changed

1. Added client parameter to "processing a manifest" — an optional environment settings object. When HTML invokes processing via <link rel="manifest">, this is the document's relevant settings object. When processing without a document (e.g., sync install), it is null.

2. Stored client on the processed manifest — so it's available later when image resources need to be fetched.

3. Added "fetch a manifest image resource" algorithm — creates a Request with:

   • URL from the image resource's src
   • destination set to "image"
   • client set to the manifest's stored client (for CSP and service worker interception)
   • Delegates to the Image Resource spec's "fetching an image resource" algorithm, which sets mode to "cors" (see w3c/image-resource#50)

4. Clarified the HTML invocation context — the "Processing without a document" section now explains when client is the document's relevant settings object vs. null.

Implementation commitment

• WebKit — currently non-conformant. Manifest icon fetches are routed directly to the network process, bypassing the document context. CSP img-src directives and service workers do not apply.
• Chromium — fetches manifest icons through the document frame via DownloadImageInFrame(). Service workers can intercept (confirmed by @dmurph). Does not explicitly set a fetch mode.
• Gecko — fetches manifest icons via window.fetch() through the content window. CSP and service workers apply. Firefox explicitly sets mode: "cors".

Related

• w3c/image-resource#50 — sets fetch mode to cors in the Image Resource spec's algorithm

Person merging, please make sure that commits are squashed with one of the following as a commit message prefix:

• chore:
• editorial:
• BREAKING CHANGE:
• And use none if it's a normative change

---

Preview | Diff

[dmurph]

My main thoughts here are:

• On Chrome, we download through the document, which can hit things like the service worker, and also shows up in things like the devools network panel
• I hesitate to open up the options here for another user agent to download the icons in a different way, as this reduces consistency here between platforms.
• Normal image fetches from a document get a bunch of things like headers, which might be used by the server to, say, customize the image based on the user's profile, whether they are in an experiment group, etc. Maybe can't fetch unless auth headers are there?

It's hard to know how important keeping this consistent, if there is a requirement out there someone would have here. I think my biggest concern would just be consistency.

HOWEVER - I think also we have an effort to decouple the manifest parsing from the document. There are a lot of benefits there too, allowing services to cache data about a manifest & the icons for distribution. But - yeah - not sure what the right answer is here.

edit: Having this always go through the document also means that you can hit the serviceworker in an offline setting.

[benfrancis]

I tend to agree that icon/image fetching should be possible outside of the document the manifest was linked from. There could be all kinds of architecture designs for how to install an application where the functions of downloading, caching and updating icons are delegated to browser chrome or the underlying operating system. In Firefox OS for example I believe at least at one point icons were initially fetched by browser/system chrome to provide a preview but then stored (in IndexedDB) and managed by the separate homescreen application after installation.

In general anything that helps decouple app installation from the document is a good thing from my point of view.

An edge case I can imagine that could create a problem is if fetching an image resource requires some form of authentication like a cookie being set, but there all kinds of reasons why I think that should be discouraged.

FWIW in WebThings Shell we currently fetch icons from system chrome rather than the document, but there's still work to do there around caching and updating images.

[marcoscaceres]

I got confirmation too that in WebKit it's done through using there document as well (i.e., CSP applies). So yeah, we should just say, go through the algorithm "fetching an image resource".

The problem with decoupling it from the document is that it would break the CSP policies, service worker served icons, etc.

[marcoscaceres]

@benfrancis, although rare, there could be a case where the icons might be pulled from a service worker - which seems like a valid thing to do. In such a case, it would need to through the document context to get to the service worker.

[christianliebel]

The Fetching an image resource algorithm in Image Resource would have to be adjusted.

[marcoscaceres]

I think we should push all the fetching to the Image Resource spec. @dmurph, cool with that?

[dmurph]

@marcoscaceres ping on this, seems strickly better at least, can we merge?

[marcoscaceres]

Checked implementations ahead of merging:

Chrome (content/browser/manifest/manifest_icon_downloader.cc): uses WebContents::DownloadImageInFrame() with an initiator_frame_routing_id, which ties the fetch to a specific renderer frame. CSP and service workers apply. Consistent with this algorithm.

Firefox (dom/manifest/ManifestIcons.sys.mjs): uses aWindow.fetch(request) with mode: "cors", going through the content window. CSP and service workers apply. Consistent with this algorithm (though Firefox sets mode: "cors" explicitly, whereas the algorithm leaves mode unset).

WebKit: currently routes manifest image fetches directly to the network process via NetworkDataTask without setting a client/settings object, bypassing CSP and service worker interception. Filed https://bugs.webkit.org/show_bug.cgi?id=311872 to track the conformance gap.

[marcoscaceres]

@dmurph re: the mode question — the "fetching an image resource" algorithm currently doesn't set a fetch mode, which defaults to no-cors. Looking at implementations:

• Firefox explicitly sets mode: "cors" when fetching manifest icons.
• Chrome fetches through the document frame via DownloadImageInFrame (internal mode handling).

From a security and privacy perspective, cors is the right default: without it, a manifest author can silently cause every visitor's browser to make cross-origin requests to arbitrary servers (leaking IP, timing, Referer), without those servers' consent. This is functionally a tracking pixel mechanism via the manifest.

I've filed w3c/image-resource#50 to set mode to cors in the "fetching an image resource" algorithm.

[Copilot]

Pull request overview

This PR updates the Web Application Manifest spec to more explicitly define how manifest image resources (e.g., icons) are fetched, aiming to align fetching behavior with the Image Resource spec’s “fetching an image resource” algorithm.

Changes:

• Clarifies the descriptive text for “manifest image resources”.
• Adds a normative MUST requirement to fetch manifest image resources by running the “fetching an image resource” algorithm.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[benfrancis]

@marcoscaceres wrote:

Checked implementations ahead of merging
...

Presumably this is during initial installation, but what about when updating?

Without the change in this PR it is my understanding that an OS could periodically directly fetch the icon of an already installed app from its icon URL to update an icon in an app launcher (e.g. in an app drawer/home screen/start menu/launchpad/dock) if it wanted to, outside of any browsing context. After this change it will always be necessary to wait for a browsing context to load a document linking to the manifest in order to download an updated icon. Do operating systems provide APIs for an installed web app (or the native browser app providing its application context) to update the icons of apps after installation?

I understand the points about CSP policies and the (slightly odd) use case of serving icons from a service worker, but it's kind of a shame to have to make this change because without it it's technically possible for a user agent to ask an OS to install a web app by just providing a manifest. After this change my understanding is the user agent will always have to fetch all of the linked image resources the OS might need itself and hand them over to the OS along with the manifest.

[marcoscaceres]

This has come up a few times and it's complicated: What you’re describing introduces an out-of-band fetch path where the OS (or UA on its behalf) can update icons outside a browsing context. The problem with that is it bypasses the origin’s security model (CSP, service workers, fetch behavior, etc.).

From a user perspective, that means app identity surfaces (like icons) can change without the site being loaded, and without the protections the developer put in place. In particular, it creates a path for persistent spoofing of installed apps if those resources are ever temporarily compromised, and generally makes behavior harder to reason about.

The intent of this change is to keep things consistent:

resources that affect user-visible app identity are fetched under the same policy constraints as the rest of the app.

That does mean the UA needs to fetch and hand assets to the OS, rather than the OS fetching them directly. In practice, I think that's how most platforms behave today... or, at least I hope... will need to check.

So while it reduces some flexibility, it avoids introducing a second, less constrained fetch path for security-sensitive resources.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[marcoscaceres]

@copilot can you fix the issue causing the CI failure?