matrix-spec-proposals/proposals/3817-widget-api-create-rooms.md

MSC3817: Allowing widgets to create rooms

MSC1236 and (among others) MSC2763 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 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:

{
  "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:

{
  "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 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 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 actions if an API version of org.matrix.msc3817 is advertised.