Ready for Developer Testing: Web App Origin Migration

15 views

Skip to first unread message

Chromestatus

unread,

2:02 PM (5 hours ago) 2:02 PM

to blin...@chromium.org, pwa...@chromium.org, m...@chromium.org

Contact emails

m...@chromium.org

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

Missing feature

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

Requires code in //chrome?

True

Tracking bug

https://issues.chromium.org/396504527

Launch bug

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