From 73d1e2776dabd8e919f46bebf329a00c93ffc325 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 20 Dec 2024 17:40:05 -0700 Subject: [PATCH] MSC4246: Sending to-device messages as/to a server --- proposals/4246-to-device-as-to-server.md | 121 +++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 proposals/4246-to-device-as-to-server.md diff --git a/proposals/4246-to-device-as-to-server.md b/proposals/4246-to-device-as-to-server.md new file mode 100644 index 00000000000..7c6821c9cfe --- /dev/null +++ b/proposals/4246-to-device-as-to-server.md @@ -0,0 +1,121 @@ +# MSC4246: Sending to-device messages as/to a server + +When implementing RFC 9420 MLS, a need arises for a client to be able to send "messages" to a specific +server. Other features, like message franking during reporting, could also use the ability to send +ephemeral-ish data to a server without the need for a whole room to be spun up. These communication +channels may also need to be bidirectional to allow servers to reply or send information back to the +client. + +This proposal suggests an approach on how to accomplish that. + + +## Proposal + +An empty string localpart is reserved for a user ID representing the server itself, alongside an +empty string for a device ID. The [current user ID grammar](https://spec.matrix.org/v1.13/appendices/#user-identifiers) +is modified to allow `user_id_localpart` to be zero characters long, as is any grammar for device IDs. +This should be possible because rooms still use the +[historical user ID grammar](https://spec.matrix.org/v1.13/appendices/#historical-user-ids), which +means clients *shouldn't* explode when they see such identifiers. Servers should already be declining +to allow new registrations from the historical user ID grammar, however. + +This translates to the following when a client wishes to send a to-device message to a server, using +the [`/sendToDevice`](https://spec.matrix.org/v1.13/appendices/#historical-user-ids) endpoint: + +``` +PUT /_matrix/client/v3/sendToDevice/org.example.whatever/whatever123 +{ + "messages": { + "@:example.org": { + "": { "example_content": "value" } + } + } +} +``` + +The `*` notation for sending to all device IDs is automatically converted to `""` by the local server, +instead of looking up a device list for the "user". This prevents servers from having multiple devices +(a restriction which may be removed in a future MSC). + +Over federation, if applicable, the associated [`m.direct_to_device`](https://spec.matrix.org/v1.13/server-server-api/#send-to-device-messaging) +EDU looks as follows: + +```jsonc +{ + "edu_type": "m.direct_to_device", + "content": { + "message_id": "", + "sender": "@alice:remote.example.org", + "type": "org.example.whatever", + "messages": { + "@:example.org": { + "": { "example_content": "value" } + } + } + } +} +``` + +When a server is sending a to-device message to another user, it would produce the following +`m.direct_to_device` EDU (if applicable) and resulting [to-device event in `/sync`](https://spec.matrix.org/v1.13/client-server-api/#extensions-to-sync) +(and applicable future synchronization APIs): + +```jsonc +{ + "edu_type": "m.direct_to_device", + "content": { + "message_id": "", + "sender": "@:example.org", + "type": "org.example.whatever", + "messages": { + "@alice:remote.example.org": { + "AAAABBBB": { "example_content": "value" } + } + } + } +} +``` + +```jsonc +{ + "sender": "@:example.org", + "type": "org.example.whatever", + "content": { "example_content": "value" } +} +``` + + +## Alternatives + +A new API for sending to/from a server could be introduced, with a complementing set of EDUs. This +ends up feeling quite a bit like to-device messages already, and looks eerily similar, and is therefore +discounted in favour of just using to-device as-is. + + +## Potential issues + +Servers may already have users which are registered as `@:example.org`, or may have them registered +after this MSC is published. Servers should consider taking over such user IDs for purposes defined +by this MSC. At the time of writing, it does not appear that any human or bot users occupy the empty +string namespace in the public federation. + + +## Security considerations + +Servers should *not* build an inbox for to-device events directed at the server. They should be +delivered to the relevant subsystem directly, and processed as soon as possible. If the event type +or EDU is unknown to the server, it should be left to the pleasantries of `/dev/null`. + + +## Dependencies + +This MSC is not dependent on any other MSCs. [MSC4244](https://github.com/matrix-org/matrix-spec-proposals/pull/4244) +relies on the functionality introduced by this proposal. Others may additionally exist. + + +## Unstable prefix + +This proposal does not require an unstable prefix as it doesn't materially change any APIs. Instead, +dependent MSCs should use unstable prefixes when communicating with the "server" user, and note that +it may be an actual account rather than the server itself for the time being (per Potential Issues +section).