#1164: Incubation: PWA (same-site) Origin Migration

Visit on Github

Opened Oct 30, 2025

Explainer

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

The explainer

Where and by whom is the work is being done?

Feedback so far

You should also know that...

No response

<!-- Content below this is maintained by @w3c-tag-bot -->

Track conversations at https://tag-github-bot.w3.org/gh/w3ctag/design-reviews/1164

Discussions

Log in to see TAG-private discussions.

Discussed Dec 1, 2025 (See Github)

Christian: the proposal may be out of date. they may want to do cross-origin handshakes.

Lola: We need an updated explainer, if so.

I'll comment and ask.

Yves: My concerns were mitigated by the fact that it was same-sites only. they were making an assertion on behalf of other resources. So if they've changed, i'm concerned. It's better to clarify if it has changed.

Hadley: I agree.

Comment by @lolaodelola Dec 4, 2025 (See Github)

Hi @mkruisselbrink,

We've heard that there may have been changes to this proposal, should we wait for you to update this proposal with new explainer and details?

Comment by @mkruisselbrink Dec 4, 2025 (See Github)

Thanks for asking, I updated the explainer a couple of days ago to take into account some feedback we got from our web platform security team. I am not currently aware of any other changes that we might want to make, so it should be good to look at.

Discussed Dec 8, 2025 (See Github)

Yves: bump to next week.

Hadley: They updated the explainer 4 days ago, so we're not far behind.

Discussed Dec 15, 2025 (See Github)

Yves: Started to take a look at it, but I’m not done yet. Find it strange that you have to be at the new location, and go back to the previous one. Redirect would also seem feasible. Need to figure out the choreography first. Think it’s dangerous if this is cross-origin.

Hadley: I’m very concerned about going cross-origin.

Christian: It’s related to my work. Didn’t have a look yet, but I’m happy to do so.

Jeffrey: This supports going from maps.google.com to google.com/maps, that’s why the two-way handshake is needed.

Hadley: There was a pattern we had in the past where there was an imbalance of power, think large ad networks, where one party says "do this [like post this dodgy javascript in order to get paid". And the site will do it. Two-way handshake doesn’t mitigate that.

Jeffrey: We might want to say, you can do this to become more fine-grained, but not the other way.

Yves: We could avoid transferring permissions.

Jeffrey: This doesn’t happen.

Yves: Same-site seems ok, but I think information in a redirect would be better.

Lola: Why do this instead of some kind of user-facing notification provided by the app? "Please download the new app."

Jeffrey: It would make sense to ask them that, but I think the answer is that high percentage of users don’t transfer.

Have an answer for Yves regarding the redirect. If you redirect from one origin to another, then a UA doesn’t understand the transfer is going to give you a bad UI in the app. Looks like you’ve navigated to an external page on an installed app. So, they have to try to detect the install status before being able to redirect.

Christian: This is an issue, becasue if you install an app it's pinned to the origin you installed it from. So a redirect would give you the address bar, which is what you try to avoid when creating an app. So I think the proposal is valid, but I need to take a closer look.

Yves: It's weird. it would be better to say, "It's an installed app, and I know it's ???. I know that this app has been upgraded and I should go to this other place." It seems a better option than trying to trick what's installed.

Christian: Need to think about this, let's keep talking offline.

Yves: That’s why I meant knowing the cheorography would help to determine if this is a good approach or not.

Matthew: I have a concern from a user’s perspective, when someone buys an app, there should be some form of opt-out rather than it’s just happening.

Hadley: Tend do agree, but if they got control of the backend, don’t they have the data anyway?

Matthew: Think there’s also a geographical vector, some jurisdictions require notification in that case anyway, don't they.

Yves: In the case of an acquisition, it will likely not be same-site anymore.

Lola: Let's keep working on this one async then.

Discussed Jan 5, 2026 (See Github)

Christian: Looked at it. Complex. I don't think that it is fine. It lets you migrate a PWA from one origin to another, but only within the same site. Elaborate. Lots of security reviews. Problems are that this (again) relies on a manifest present. In webapps, you don't need a manifest. This only works with a manifest. That might be fine, but there is also the ID requirement again, which we had before. It might make sense for Marcos to take a look at it for those issues.

...Also this proposal looks at the scope extensions proposal. It shares some files with that proposal. Not sure what we thought about that proposal, so we might need to include scope extensions in any.

...What seems problematic is that it migrates permissions across between origins (same site). Up for debate, but also merges permissions. You can end up with a denial once the permissions are merged.

...Interesting problem space. Something that people want to do, but there are a lot of details.

Marcos: When you said, lots of security reviews, you mean Chromium security reviews?

Christian: Yes.

Marcos: There is a larger TAG question, where there is a stack of things depending on other things that haven’t become part of the web platform, like Scope Extensions. I’m not sure what we should do about those. I’m gonna have a look at this as well. As you’ve mentioned, there are some parts that may be contrary to the installation workflow as discussed in the WG.

Yves: Still don’t really like the fact that is uses .well-known URLs for the handshake. Would prefer a redirect with a proper media type to trigger the progress. This is a much better architectural approach than to rely on a well-known URL. If you could pass a JSON payload that defines if permissions, data, etc. should be transferred, it would be even better.

Martin (chat): 310 Moved Permanently.

Yves: I’m looking at that from a networing side, not from the PWA side.

Martin: Permissions seems problematic. It seems fine to ask for permissions again. It’s causing an unexpected prompt, but that seems easier to attempt merging permissions.

Marcos: If you've moved it and redesigned the application. A and B might not really be equivalent. The new thing maybe shouldn't have the permissions of the old thing. What if you already had B installed? What if it already has some permissions? Sounds un-good. Trying to be clever never works out well. Just reset. What do they do with cookies?

Christian: Data is not migrated, only permissions.

Xiaocheng: How big is the motivation? How strong is the demand for this?

Marcos: Twitter.com to X

Christian: But this is outside the scope, it’s only same-site.

Martin: It’s maps.google.com to google.com/maps. And that happens. The question is, how much do you want to smooth that process over? Maybe we can skip the installation step, but not move over permissions, etc.

Christian: From a dev standpoint, rebrandings happen, and losing the entire installed user base would be bad. Makes sense to solve this, but the question is how.

Xiaocheng: Feel skeptical about motivations, seems like it’s only for the big ones.

Christian: Even if the motivation is larger companies/brands, smaller ones also benefit from this. Small companies rebrand often, too. Or personal websites, think name changes.

Discussed Jan 12, 2026 (See Github)

Christian: I have a draft comment based on last week's discussion. This helps developers migrate within the same site. Based on too many things that aren't part of the web platform yet. ID requirement and re-using scope extensions. We wanted to suggest an HTTP redirect.

Jeffrey: I'm worried that an HTTP redirect will break browsers that don't support this feature.

Christian: That's why not to close the review. But they should say whether this is reasonable.

Yves: It would be a combination of 301 + a content type. So they have the chance to act based on what's in the body. And the body can be content-negotiated. Do you both apps will be live at the same.

Jeffrey: I suspect so, since they'd leave the old one until users have migrated.

Yves: maps.google.com does redirect to google.com/maps. If it can use the manifest to also migrate data, that'll just help.

Jeffrey: I suspect that sites will be reluctant to redirect while some browsers don't support the full migration, to avoid the ugly second URL bar that appears when a PWA navigates outside its scope. But that supports Christian's approach of letting them reply.

Christian: The review starts with "we think this is a problem worth solving," but we should find the best solution.

Comment by @christianliebel Jan 19, 2026 (See Github)

@mkruisselbrink Thank you for your proposal. The TAG acknowledges that migrating a web app from one origin to another is a problem worth solving, and we support same-site migrations.

We believe that the proposal, in its current form, is based on assumptions and specifications that don’t seem to have cross-vendor consensus. For example, web apps can also be installed without a manifest and, thus, without an explicit ID (i.e., it will get a computed one based on the rules set forth in the spec). Acknowledging the "ID footgun," we ask you to discuss this restriction (which would only apply to migrations) with the other vendors in the Web Apps WG. The URL used for the handshake reuses the location from Scope Extensions, which also does not have cross-vendor support.

Regarding permissions, we recommend not migrating any existing permissions. Denying a permission as part of the migration after it was previously granted by a user seems problematic for user experience. We understand that this could be an inconvenience for users, but doing permission migration might lead to more confusion and complexity.

Also, we are unsure if developers should be able to choose between the "force" and "suggest" update modes. Would developers not want to "force" an update in the default case? However, in that case, they would only be allowed to change the URL during the migration, and might not be able to perform the branding update in the same step.

We would like you to consider an HTTP redirect as an alternative. This approach is not bound to manifests, and might be a little more versatile. For example, this could be limited to 301 Moved Permanently (i.e., "force" update mode), require appropriate headers to be set in the request and/or response (similar to CORS), or a redirect with a certain JSON payload that might give instructions on how to migrate permissions and data.

We would like to hear your thoughts.