From 86071fafadacddfa31b131d915f3428df54d352e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 1 Mar 2021 23:03:53 -0700 Subject: [PATCH] Proposal for typed typing notifications --- proposals/3038-typed-typing-notifications.md | 137 +++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 proposals/3038-typed-typing-notifications.md diff --git a/proposals/3038-typed-typing-notifications.md b/proposals/3038-typed-typing-notifications.md new file mode 100644 index 00000000..84c26ec8 --- /dev/null +++ b/proposals/3038-typed-typing-notifications.md @@ -0,0 +1,137 @@ +# MSC3038: Typed Typing Notifications + +Typing notifications in Matrix currently support a single boolean value of typing or not typing. While +this works for most use cases (text chat specifically), it is not always applicable when sending more +complicated data types like voice messages. + +This MSC extends the existing typing notification structure to support metadata about the event the +user is sending. All of the metadata is optional. + +For reference, a typing notification currently looks something like this: + +```json5 +{ + "content": { + "user_ids": [ + "@alice:matrix.org", + "@bob:example.com" + ] + }, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "type": "m.typing" +} +``` + +## Proposal + +A new, optional, `event` field is added to the `PUT` body of +[`/rooms/:roomId/typing/:userId`](https://matrix.org/docs/spec/client_server/r0.6.1#put-matrix-client-r0-rooms-roomid-typing-userid) +which represents the event the user is working on sending. A new `PUT` body may look like: + +```json5 +{ + "typing": true, + "timeout": 33038, + "event": { + "type": "m.room.message", + "content": { + "msgtype": "m.text" + } + } +} +``` + +The `event` is a stripped-down version of a real event, indicating the `type` and relevant parts of +the `content` to be included. This does technically allow a client to also send partial events such +as the event body, however this MSC strongly advises that clients do not send or render that information +due to the privacy implications. See the "Security Considerations" section for more information. + +For a `type` of `m.room.message`, The default `content.msgtype` is `m.text`. Similarly, when no +`event` information is supplied, the user can be assumed to be sending a `m.text` `m.room.message` +event. The server should reject any invalid fields (wrong data types, unexpected locations, etc), +though clients are ultimately responsible for parsing the data safely. + +The ephemeral event a client would receive could look something like this: + +```json5 +{ + "content": { + "user_ids": [ + "@alice:matrix.org", + "@bob:example.com" + ], + "events": { + "@alice:matrix.org": { + "type": "m.room.message", + "content": { + "msgtype": "m.voice" + } + } + } + }, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "type": "m.typing" +} +``` + +In this example, `@alice:matrix.org` is recording a theoretical voice message while `@bob:example.com` +is typing a regular text event (the default). If the receiving client doesn't recognize the event +Alice is trying to send, for example, then the client would assume that they are sending a regular +text event or use generic language like "Alice is sending something...". + +The `events` object is not required. Clients should interpret invalid data (wrong data types, missing +fields, etc) as though users are typing text messages. Users who are *not* listed in `user_ids` +should not show up in the `events` object, and clients should ignore any updates for users who are +not in the `user_ids` array. + +Like with typing notifications currently, a user can send `typing: false` at any time to stop typing. +Changing the `event` information being sent replaces any previous state, including removal of `event` +from the `PUT` body. + +For example: + +1. User hits `PUT /typing` with `{"typing": true, "event": {"type": "m.room.message"}}` +2. Other users see them as typing a text message. +3. The same user hits `PUT /typing` with `{"typing": true, "event": {"type": "org.example.msg"}}` this time. +4. Other users see them as typing an `org.example.msg` event. +5. The same user once again hits `PUT /typing` with `{"typing": true}` +6. Other users now see them as typing a text message again +7. Finally, the user sends `{"typing": false}` to clear their typing status for other users. + +## Potential issues + +This MSC is potentially far too generic for what it aims to achieve, which is a "User is recording a +voice message..." line in clients. This approach feels suitable for other applications in the future, +such as potentially streaming uploads or other lengthy message sending stats (as this approach could +send progress information too). + +## Alternatives + +Not really considered at the moment, but there is an option of a whole other `m.recording` EDU and partner +API to cover the use case of "show user as recording a voice message". This feels like overkill for such +a feature, however. + +## Security considerations + +As already mentioned, because the `content` the client sends to `/typing` is sent verbatim over federation +it could be a way to expose far more information than the user intended to send, such as their draft of +the message they are typing. Clients are strongly discouraged from using this practice, and servers should +enforce strong rate limits to help discourage the behaviour. Servers could even optionally reject `body` +being included in `content`, for example. + +If a client does decide to render `body` (or `formatted_body`) information from the typing notification, +it should consider the security risks associated with using unsafe user input, like HTML injection. + +Clients could also abuse this feature for custom status, presence, or other similar functionality where it +might otherwise be disabled/non-functional on their homeserver. Again, servers should use rate limits to +avoid this sort of behaviour and room administrators/moderators should consider banning/kicking the users +from the room for doing this. Servers could also use pattern-detecting behaviour if appropriate for their +deployment to determine if a user is abusing typing notifications (for example, a user is unlikely to be +typing a message for 4 solid hours). + +## Unstable prefix + +While this MSC is not considered stable, implementations should use `org.matrix.msc3038.events` in place +of `events` - both in the `PUT` body and in the resulting `m.typing` ephemeral event. Note that servers +which do not support this functionality will end up ignoring any mention of `events`, thus leaving the +user as typing a text message in existing client implementations.