Merge ccd90eb5d5 into e9f0f31d27
Dominik Henneke
1 week ago
committed by
GitHub
commit
cb3f781f04
@ -0,0 +1,149 @@
|
|||||||
|
# MSC3817: Allowing widgets to create rooms
|
||||||
|
|
||||||
|
[MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236) and (among others)
|
||||||
|
[MSC2763](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) specify a Widget API that
|
||||||
|
is able to send events to the client and receive events from the client. One feature that is not yet
|
||||||
|
available is the creation of new rooms via this API. An example use case for this feature is a
|
||||||
|
calendar application that can create new Matrix rooms for every calendar event. Another is a widget
|
||||||
|
that allows the user to create breakout rooms to discuss certain topics directly from the widget.
|
||||||
|
Giving the widget this option would also give them the possibility to provide an initial state for
|
||||||
|
the room that is hard (or impossible) to add after the room has been created.
|
||||||
|
|
||||||
|
This proposal aims to bring the functionality of creating rooms into the widget specification. It
|
||||||
|
should provide the same features that the
|
||||||
|
[“Room Creation” endpoint](https://spec.matrix.org/v1.2/client-server-api/#creation) of the
|
||||||
|
Client-Server API provides.
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
Having the possibility to create new rooms would improve the capabilities of the widgets and would
|
||||||
|
fill a gap of widget room capabilities. As of now, a widget can read and write state or room events
|
||||||
|
to arbitrary rooms, but it can't be used to create these rooms.
|
||||||
|
|
||||||
|
In order to secure the user from malicious widgets, we will add a new capability that the user must
|
||||||
|
manually approve:
|
||||||
|
|
||||||
|
- `m.create_room`: Let the widget create new rooms.
|
||||||
|
|
||||||
|
This capability will enable the user to provide arbitrary events as the initial state of the room and
|
||||||
|
can also invite an arbitrary amount of users to the room. These events are not bound by the approved
|
||||||
|
capabilities of the widget, because we assume that the creator of the room should be able to have the
|
||||||
|
full control of the room during this initialization process. Thus, the `m.send.event:<event type>`
|
||||||
|
capabilities will not apply here.
|
||||||
|
|
||||||
|
To trigger the action, widgets will use a new `fromWidget` request with the action `create_room` which
|
||||||
|
takes the following shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"api": "fromWidget",
|
||||||
|
"widgetId": "20200827_WidgetExample",
|
||||||
|
"requestid": "generated-id-1234",
|
||||||
|
"action": "create_room",
|
||||||
|
"data": {
|
||||||
|
"creation_content": {
|
||||||
|
"m.federate": false
|
||||||
|
},
|
||||||
|
"initial_state": [],
|
||||||
|
"invite": [],
|
||||||
|
"invite_3pid": [],
|
||||||
|
"is_direct": false,
|
||||||
|
"name": "The Grand Duke Pub",
|
||||||
|
"power_level_content_override": {},
|
||||||
|
"preset": "public_chat",
|
||||||
|
"room_alias_name": "thepub",
|
||||||
|
"room_version": "1",
|
||||||
|
"topic": "All about happy hour",
|
||||||
|
"visibility": "public"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Under `data`, all keys are a mirrored representation of the original `/createRoom` API. This also
|
||||||
|
means that all keys are optional.
|
||||||
|
|
||||||
|
If the widget did not get approved for the capability required to send the event, the client MUST
|
||||||
|
send an error response (as required currently by the capabilities system for widgets).
|
||||||
|
|
||||||
|
The client SHOULD NOT modify the data of the request. The widget is responsible for producing valid
|
||||||
|
events - the client MUST pass through any errors, such as permission errors, to the widget using the
|
||||||
|
standard error response in the Widget API.
|
||||||
|
|
||||||
|
If the event is successfully sent by the client, the client sends the following response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"api": "fromWidget",
|
||||||
|
"widgetId": "20200827_WidgetExample",
|
||||||
|
"requestid": "generated-id-1234",
|
||||||
|
"action": "create_room",
|
||||||
|
"data": {
|
||||||
|
"creation_content": {
|
||||||
|
"m.federate": false
|
||||||
|
},
|
||||||
|
"initial_state": [],
|
||||||
|
"invite": [],
|
||||||
|
"invite_3pid": [],
|
||||||
|
"is_direct": false,
|
||||||
|
"name": "The Grand Duke Pub",
|
||||||
|
"power_level_content_override": {},
|
||||||
|
"preset": "public_chat",
|
||||||
|
"room_alias_name": "thepub",
|
||||||
|
"room_version": "1",
|
||||||
|
"topic": "All about happy hour",
|
||||||
|
"visibility": "public"
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"room_id": "!room:example.org"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `room_id` field of the `response` is required and represents the ID of the new room that has been
|
||||||
|
created.
|
||||||
|
|
||||||
|
## Alternatives
|
||||||
|
|
||||||
|
Widgets could be powered by a bot or some sort of backend which allows them to create new rooms,
|
||||||
|
however this can be a large amount of infrastructure for a widget to maintain. The widget is already
|
||||||
|
capable of interacting with the events that are stored in a room, so the sole purpose of the bot
|
||||||
|
would be to create new rooms.
|
||||||
|
|
||||||
|
The Widget API could limit the API surface by not permitting the widget to e.g. provide an initial
|
||||||
|
state or by providing user ids that should be invited by the server. However, this would limit the
|
||||||
|
usefulness of the API.
|
||||||
|
|
||||||
|
If [MSC3008](https://github.com/matrix-org/matrix-spec-proposals/pull/3008) goes forward, the widget
|
||||||
|
could interact with the respective API call of the Client-Server API. However, the status of the MSC
|
||||||
|
is unknown so it would be a good alternative to add this feature to the widget API.
|
||||||
|
|
||||||
|
Instead of mirroring the API surface of the Client-Server API, the widget api could use a more
|
||||||
|
specific interface as it is also available in the
|
||||||
|
[`matrix-react-sdk`](https://github.com/matrix-org/matrix-react-sdk/blob/c67b41fbde06e302e0ca296d99fbcea9f95b4a78/src/createRoom.ts#L52-L67)
|
||||||
|
and provide that in the `WidgetDriver` interface. This would enable the API to for example automatically
|
||||||
|
setup the encryption or add the `m.space.child` to a parent space room. However, the Widget API is
|
||||||
|
more independent if it doesn't rely on external logic, especially considering a potential emergence
|
||||||
|
of MSC3008. This also means that this complexity is moved to the widget itself that must implement
|
||||||
|
the logic if needed.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
It is important that clients prompt for permission to create rooms. It could mess with the room list
|
||||||
|
of a user, or it could also invite unwanted users to a room. This could either be a malicious bot,
|
||||||
|
or other users who are spammed with unwanted invitations. Instead of solely relying on the
|
||||||
|
`m.create_room` capability, the widget API could consider the `m.send.event:<event type>` capabilities
|
||||||
|
for all events that are provided as initial state in the API call. This could also include the
|
||||||
|
`m.send.event:m.room.member` capability to secure the `invite` list. But in order to correctly check
|
||||||
|
the capabilities, the widget would need to have the capabilities accepted for the `room_id` of the
|
||||||
|
room that is about to be created, or the widget must request timeline access to all (i.e. `"*"`)
|
||||||
|
rooms, which would be unpractical. An alternative could be to add more narrowly scoped capabilities
|
||||||
|
such as `m.create_room:invite,m.room.encryption,…`.
|
||||||
|
|
||||||
|
## Unstable prefix
|
||||||
|
|
||||||
|
While this MSC is not present in the spec, clients and widgets should:
|
||||||
|
|
||||||
|
- Use `org.matrix.msc3817.` in place of `m.` in all new identifiers of this MSC.
|
||||||
|
- Use `org.matrix.msc3817.create_room` in place of `create_room` for the action type in the
|
||||||
|
`fromWidget` requests.
|
||||||
|
- Only call/support the `action`s if an API version of `org.matrix.msc3817` is advertised.
|
||||||
Loading…
Reference in New Issue