Merge pull request #2774 from matrix-org/travis/msc/widget-id

MSC2774: Expose the widget ID to the widget

proposals/2774-widget-id.md

@@ -0,0 +1,54 @@
+# MSC2774: Giving widgets their ID so they can communicate
+
+Under the [current specification](https://github.com/matrix-org/matrix-doc/pull/2764), 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](https://github.com/matrix-org/matrix-doc/pull/2762) 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.