Intent to Ship: Web App Origin Migration

[Chromestatus]

Contact emails

m...@chromium.org, diby...@chromium.org, dmu...@chromium.org, pwa-...@google.com

Explainer

https://github.com/WICG/manifest-incubations/blob/gh-pages/pwa-migration-explainer.md

Specification

https://github.com/WICG/manifest-incubations/pull/136

Summary

When a user installs a Progressive Web App (PWA), its identity and security context are tightly bound to its web origin (e.g., app.example.com). This presents a significant challenge for developers who need to change their PWA's origin due to rebranding, domain restructuring, or technical re-architecture. Currently, such a change forces users to manually uninstall the old app and reinstall the new one, leading to a disruptive experience and potential user loss. This proposal introduces a mechanism for developers to seamlessly migrate an installed PWA to a new, same-site origin, preserving user trust and permissions. Administrator force-install policy will block migration. Since enterprise policies around web applications are primarily based on URLs and origins, there is a risk that a migration would bypass certain policies an admin might have configured. As such no migration will be offered to the user when an app is force-installed by their enterprise administrator, and instead a banner will be shown explaining this to the user.

Blink component

UI>Browser>WebAppInstalls

Web Feature ID

manifest

Motivation

Imagine you have the "SocialApp" app installed on your computer from www.example.com/social. One day, the company decides to move the app to its own dedicated home at social.example.com. Without a migration mechanism, the app you have installed would either break or redirect you to the new site in a generic browser window, losing its app-like feel. You would have to figure out that you need to uninstall the old app and install the new one from the new address. You might also lose your settings, like whether you've allowed the app to send notifications. This feature aims to make that transition seamless. Instead of a broken experience, the app would notify you of an available update. With your approval, the app would relaunch from its new home at social.example.com, with your notification settings intact.

Initial public proposal

https://github.com/WICG/manifest-incubations/pull/121

Search tags

app migration, manifest update

TAG review

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

TAG review status

Pending

Goals for experimentation

None

Risks

Interoperability and Compatibility

By its nature, this is a feature that a site might use for some amount of time while migrating their Web Applications to a different origin, but where longtime usage by any particular site is unlikely, as the whole purpose of this feature is to get users away from sites that use this feature. As such, the risks around making breaking changes in the future are significantly lower than for other web platform features. This is not a feature any website will rely on long term, instead at different points in time different websites can make use of it.

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

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/568)

Web developers: No signals

Other signals:

Ergonomics

One common way this API is likely to be used is in combination with Scope Extensions and HTTP redirects (by redirecting the old app to the new location, while using Scope Extensions to treat the new location in scope for the old app). As such we designed this API explicitly to work well in that situation. Usage of this API should not have any effect on Chrome performance, it is merely a signal to Chrome to display UI to the user to allow migration of the Web Application.

Activation

We are planning on either adding new documentation or updating the existing manifest updating docs to mention this new feature, to help educate developers about this feature. Besides that usage of this feature shouldn't be particularly challenging for developers, as long as they have the ability to host the .well-known/web-app-origin-associations file on the origin they are migrating away from.

Security

The primary security threat is a hostile takeover, where a malicious actor could try to migrate a legitimate PWA to a phishing site. The same-site restriction is the critical defense here. Since an attacker cannot control a different eTLD+1, they cannot hijack a PWA. For example, example.com could not be migrated to evil-phishing-site.com. In addition the old origin needs to explicitly allow migrations to the new location via its .well-known/web-app-origin-association file.

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?

No information provided

Debuggability

The existing DevTools support for the manifest will show any parsing or validation errors around these new migration related manifest fields.

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

No
This feature is currently only targeting desktop platforms. While Android does have support for PWAs, installation and update mechanisms are very different from what is done on desktop platforms, where implementing this feature would possibly require changes at a much lower level.

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

No
There is no web exposed effect of usage of this API, as such there isn't much that makes sense to test using Web Platform Tests. It would be nice however to at least have web platform tests for the manifest parsing/processing steps, but that requires a feature such as https://github.com/w3c/manifest/issues/1179 so a test can read back the processed manifest.

DevTrial instructions

https://googlechrome.github.io/samples/pwa-migration

Flag name on about://flags

chrome://flags/#web-app-migration-api

Finch feature name

WebAppMigrationApi

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

True

Tracking bug

https://issues.chromium.org/396504527

Launch bug

https://launch.corp.google.com/launch/4453101

Measurement

We will measure both the presence of these new manifest fields in manifests, as well as activation of the migration by users.

Estimated milestones

Shipping on desktop	148
DevTrial on desktop	147

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).

No information provided

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5123349239955456?gate=5094079474040832

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6903a614.050a0220.56be2.0983.GAE%40google.com

This intent message was generated by Chrome Platform Status.