From 8f986210b494998806164c90478de905672884f3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 23 Nov 2020 17:46:32 -0700 Subject: [PATCH 1/3] Allowing widgets to read events in a room --- proposals/2876-widgets-reading-events.md | 137 +++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 proposals/2876-widgets-reading-events.md diff --git a/proposals/2876-widgets-reading-events.md b/proposals/2876-widgets-reading-events.md new file mode 100644 index 00000000000..eaf4bef8731 --- /dev/null +++ b/proposals/2876-widgets-reading-events.md @@ -0,0 +1,137 @@ +# MSC2876: Allowing widgets to read events in a room + +[MSC2762](https://github.com/matrix-org/matrix-doc/pull/2762) allows a widget to request permission +to send events as well as receive events sent while the widget's session is open, however the MSC +does not propose allowing widgets to read events from before the widget is opened. This MSC aims +to propose an approach for that flow, and is isolated from MSC2762 to avoid making MSC2762 difficult +to review. + +While this MSC is isolated from MSC2762, this MSC does use a lot of concepts proposed by MSC2762. It +is suggested to give MSC2762 a read before reading this MSC. + +## Proposal + +It's important to avoid leaking information into the wild through a widget, which is why MSC2762 +doesn't handle the case of widgets being able to look into a room's history. Instead, MSC2762 uses +access controls which prevent the widget from getting too much information up front. This MSC adds +some specific access controls that allow widgets to look backwards into the room's history, though +with the risk that it's violating MSC2762's ideal security model of event handling. + +Using a capability structure like MSC2762, widgets can request `m.read.event:` and +`m.read.state_event:` to activate the functionality in this MSC. MSC2762's ability to +filter on state keys and message types applies to these capabilities as well in the same way. Like +MSC2762, clients should also not allow widgets to mix known event types into the wrong place (ie: +not allowed to request `m.read.event:m.room.topic` or `m.read.state_event:m.room.message`). + +This MSC also does not apply to other kinds of events (EDUs, account data, etc), much like MSC2762. + +Assuming the widget has the relevant permissions, it can request events using the following `fromWidget` +API action: + +```json +{ + "api": "fromWidget", + "widgetId": "20200827_WidgetExample", + "requestid": "generated-id-1234", + "action": "read_events", + "data": { + "state_key": "", + "type": "m.room.topic", + "limit": 25 + } +} +``` + +When a `state_key` is present, the client will respond with state events matching that state key. If +`state_key` is instead a boolean `true`, the client will respond with state events of the given type +with any state key. For clarity, `"state_key": "@alice:example.org"` would return the state event with +the specified state key (there can only be one or zero), while `"state_key": true` would return any +state events of the type, regardless of state key. + +The `type` is simply the event type to go searching for. + +The `limit` is the number of events the widget is looking for. The client can arbitrarily decide to +return less than this limit, though should never return more than the limit. For example, a client +may decide that for privacy reasons a widget can only ever see the last 5 room messages - even though +the widget requested 25, it will only ever get 5 maximum back. When `limit` is not present it is +assumed that the widget wants as many events as the client will give it. When negative, the client +can reject the request with an error. + +The recommended maximum `limit`s are: + +* For `m.room.member` state events, no limit. +* For all other events, 25. + +The client is not required to backfill (use the `/messages` endpoint) to get more events for the +client, and is able to return less than the requested amount of events. When returning state events, +the client should always return the current state event (in the client's view) rather than the history +of an event. For example, `{"type":"m.room.topic", "state_key": "", "limit": 5}` should return zero +or one topic events, not 5, even if the topic has changed more than once. + +The client's response would look like so (note that because of how Widget API actions work, the request +itself is repeated in the response - the actual response from the client is held within the `response` +object): + +```json +{ + "api": "fromWidget", + "widgetId": "20200827_WidgetExample", + "requestid": "generated-id-1234", + "action": "read_events", + "data": { + "state_key": "", + "type": "m.room.topic", + "limit": 25 + }, + "response": { + "events": [ + { + "type": "m.room.topic", + "sender": "@alice:example.org", + "event_id": "$example", + "room_id": "!room:example.org", + "state_key": "", + "origin_server_ts": 1574383781154, + "content": { + "topic": "Hello world!" + }, + "unsigned": { + "age": 12345 + } + } + ] + } +} +``` + +The `events` array is simply the array of events requested. When no matching events are found, this +array must be defined but can be empty. + +## Potential issues + +Most of the concerns are largely security concerns and are discussed in more detail later on in this +proposal. + +## Alternatives + +Widgets could be powered by a bot or some sort of backend which allows them to filter the room state +and timeline themeselves, however this can be a large amount of infrastructure for a widget to maintain +and the user experience is not as great. The client already has most of the information a widget would +need, and trying to interact through a bot would generally mean slower response times or technical +challenges on the part of the widget developer. + +## Security considerations + +This MSC allows widgets to arbitrarily read history from a room without the user necessarily knowing. +Clients should apply strict limits to the number of events they are willing to provide to widgets +and ensure that users are prompted to explicitly approve the permissions requested, like in MSC2762. + +Clients may also wish to consider putting iconography next to room messages when a widget reads them, +either through this MSC or MSC2762. + +## Unstable prefix + +While this MSC is not present in the spec, clients and widgets should: + +* Use `org.matrix.msc2876.` in place of `m.` in all new identifiers of this MSC. +* Only call/support the `action`s if an API version of `org.matrix.msc2876` is advertised. From 07761421a73e576e2279be81b17a83149c35b5ed Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 20:05:04 -0600 Subject: [PATCH 2/3] Spelling --- proposals/2876-widgets-reading-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2876-widgets-reading-events.md b/proposals/2876-widgets-reading-events.md index eaf4bef8731..943088742c5 100644 --- a/proposals/2876-widgets-reading-events.md +++ b/proposals/2876-widgets-reading-events.md @@ -115,7 +115,7 @@ proposal. ## Alternatives Widgets could be powered by a bot or some sort of backend which allows them to filter the room state -and timeline themeselves, however this can be a large amount of infrastructure for a widget to maintain +and timeline themselves, however this can be a large amount of infrastructure for a widget to maintain and the user experience is not as great. The client already has most of the information a widget would need, and trying to interact through a bot would generally mean slower response times or technical challenges on the part of the widget developer. From c4eef453811f3403f88fbca2068a58169277b303 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 21:57:14 -0600 Subject: [PATCH 3/3] Minor clarifications --- proposals/2876-widgets-reading-events.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/proposals/2876-widgets-reading-events.md b/proposals/2876-widgets-reading-events.md index 943088742c5..e9bc071636d 100644 --- a/proposals/2876-widgets-reading-events.md +++ b/proposals/2876-widgets-reading-events.md @@ -48,6 +48,9 @@ with any state key. For clarity, `"state_key": "@alice:example.org"` would retur the specified state key (there can only be one or zero), while `"state_key": true` would return any state events of the type, regardless of state key. +To appease MSC2762's ability to read particular msgtypes, the widget can specify a `msgtype` in place +of the `state_key` for `m.room.message` requests. + The `type` is simply the event type to go searching for. The `limit` is the number of events the widget is looking for. The client can arbitrarily decide to @@ -133,5 +136,7 @@ either through this MSC or MSC2762. While this MSC is not present in the spec, clients and widgets should: -* Use `org.matrix.msc2876.` in place of `m.` in all new identifiers of this MSC. * Only call/support the `action`s if an API version of `org.matrix.msc2876` is advertised. +* Use `org.matrix.msc2762.read.[state_]event:*` instead of `m.read.[state_]event:*`. Note that this + is a different MSC number for better compatibility with MSC2762. +* Use `org.matrix.msc2876.*` in place of `m.*` for all other identifiers.