matrix-spec-proposals/proposals/2774-widget-id.md

MSC2774: Giving widgets their ID so they can communicate

Under the current specification, widgets are able to communicate with their client host, however doing so is a bit difficult if they don't already know their widget ID. Some widgets will be able to get their ID from another source like an integration manager, however this is not the case for all widgets.

MSC2762 has a fair amount of background information on widgets, as does the current specification linked above.

Proposal

Currently widgets can expect a ?widgetId query parameter sent to them in clients like Element, however this has some issues and as such is not proposed to exist any further. One of the issues is that the widget must retain the query string, which isn't entirely possible for some frontends (they would instead prefer to use the fragment). It's also a privacy risk in that by being sent through the query string, the server can be made aware of the widget ID. The widget ID doesn't normally contain any useful information (it's an opaque string), however it's not required for the server to function under typical usage.

The proposal is to introduce a $matrix_widget_id template variable for the URL, similar to the existing $matrix_room_id variable. Widgets can then have their widget ID wherever they want in the widget URL, making it easier on them to find and use.

This carries the same risks as a room ID being passed to the widget: the client can easily lie about it, however there's no real risk involved in doing so because it's used for communication only. So long as the client is able to identify which widget is talking to it, it doesn't really matter. It's more of a problem if the client uses a widget ID from another widget as that could confuse the client, however this is believed to be a bug. Clients should also be performing origin checks to ensure the widget is talking from a sane origin and not somewhere else, like another tab or browser.

Potential issues

This is not backwards compatible with the history of widgets so far, so clients and widgets will need to be modified to support it. Clients which currently use the ?widgetId parameter are encouraged to continue supporting the parameter until sufficient adoption is reached.

Alternatives

As mentioned, a query parameter could be used, though this has the issues previously covered. Another solution might be to allow a single widget API action which has no widget ID solely for the purpose of finding the widget ID, however clients are unlikely to be able to differentiate between two widgets if this were the case.

Another solution would be to let the widget discover its widget ID by harvesting it out of the first widget API request it sees. This can't always be relied upon (some flows require the widget to speak first), and as the widget API becomes more capable it could become a security risk. A malicious browser extension could spam the widget with fake requests to try and convince it to talk to it instead of the client, thus redirecting some information to the wrong place.

Unstable prefix

Implementations should use $org.matrix.msc2774_widget_id as a variable until this lands in a released version of the specification.