122 lines
4.5 KiB
Markdown
122 lines
4.5 KiB
Markdown
# 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": "<generated by sending server>",
|
|
"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": "<generated by sending server>",
|
|
"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).
|