This MSC adds the ability to publish short-lived location beacons through the
the use of custom Ephemeral Data Units (EDUs) by building on top of [MSC2477](https://github.com/matrix-org/matrix-doc/pull/2477).
This MSC adds the ability to publish short-lived location beacons through
the use of Ephemeral Data Units (EDUs). It is almost identical to MSC3489,
apart from this change.
Ephemeral data units (EDUs) are Matrix's default mechanism for broadcasting
short-lived data to a group of users and with the advent of user-defined ones
they perfectly fit live location sharing.
They are intended to be non-persistent, not take part in a room's history and
are currently used for typing notifications, event receipts, and presence
updates. As an extra precaution they can also be encrypted as defined in [MSC3673](https://github.com/matrix-org/matrix-doc/pull/3673).
We will start by introducing `m.beacon_info` as a new state event type; the event shape originally taken from [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489), but with some slight tweaks.
The `state_key` of this state event must be send to the sender's MXID. As per [event auth rules](https://spec.matrix.org/v1.2/rooms/v9/#authorization-rules), this restricts the state event to only be editable by the sender.
**`m.beacon_info` state event `content` field definitions**
| key | type | value | description | Required |
| ---- | ----| ----- | ----------- | -------- |
| `timeout` | int | A positive number of milliseconds | The maximum length of the location sharing session, relative to `m.ts`. | yes
| `description` | string | Optional descriptive text | A human-readable description of the live location sharing session. | no |
| `live` | bool | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes
| `m.ts` | int | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. **Milliseconds** since the unix epoch. | yes
| `m.asset` | dict | A dictionary (see below) | Describes the object being tracked. From [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). | yes
TODO: This design does not currently allow for a user to have multiple live location sharing sessions active simultaneously. Incorporating either [MSC3671](https://github.com/matrix-org/matrix-spec-proposals/pull/3671) or [MSC3757](https://github.com/matrix-org/matrix-spec-proposals/pull/3757) will help here.
TODO: Is `m.ts` really needed on `m.beacon_info`? Or can we just simply use `origin_server_ts`?
**`m.asset` dictionary definition**
| key | type | value | description | required |
| ---- | --- | ----- | ----------- | -------- |
| `type` | string | `m.self` | A string identifying the asset being tracked, as defined by [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). `m.self` means this session tracks the sender's location. | yes |
A full example of the `m.beacon_info` state event:
```json5
{
"type": "m.beacon_info",
"state_key": "@stefan:matrix.org",
"content": {
"timeout": 600000,
"description": "Stefan's live location",
"live": true,
"m.ts": 1436829458432,
"m.asset": {
"type": "m.self"
}
},
"origin_server_ts": 1436829458474,
"event_id": "$abcd:domain",
"room_id": "!1234:domain"
}
```
Subsequently clients will start sending beacon data EDUs to the new
`rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals
`m.beacon` with the following payload.
**`m.beacon` ephemeral event `content` field definitions**
| key | type | value | description | Required |
| ---- | ----| ----- | ----------- | -------- |
| `m.relates_to` | dictionary | Event reference, defined in [MSC2674](https://github.com/matrix-org/matrix-spec-proposals/pull/2674) | A reference to the state event defining a live location share that this location update is related to. | yes
| `m.location` | dictionary | An extensible event containing location data, defined in [MSC3267](https://github.com/matrix-org/matrix-spec-proposals/pull/3267) | The asset's location, and an optional description | yes |
| `m.ts` | int | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The optional timestamp of when the location was recorded. If missing, clients should use `origin_server_ts`. | no
An full example of a `m.beacon` EDU as received by a client:
```json5
{
"content": {
"m.relates_to": {
"rel_type": "m.reference",
"event_id": "$beacon_info"
},
"m.location": {
"uri": "geo:51.5008,0.1247;u=35",
"description": "Arbitrary beacon information"
},
"m.ts": 1636829458432,
},
"type": "m.beacon",
"sender": "@stefan:matrix.org",
"origin_server_ts": 1636829518182
}
```
If multiple live beacons exist, clients have the option of either aggregating
all available location EDUs into one render or just those referencing a particular
`m.beacon_info` state event.
When the user decides they would like to stop sharing their live location the
original `m.beacon_info`'s `live` property should be set to `false`.
short-lived data to a group of users. They are intended to be
non-persistent, not take part in a room's history and are currently used
for typing notifications, event receipts, and presence updates.
## Security considerations
To allow the use of EDUs for live location sharing, this MSC depends on
Clients announce a share, and stop a share exactly as in MSC3489, by
emitting an `m.beacon_info` state event.
Clients share locations by emitting an `m.beacon` event which is identical
to those described in MSC3489, except that it is an EDU (whereas in MSC3489
the events are PDUs).
End-to-end encryption for ephemeral data units isn't currently available, but a
mechanism for achieving that is defined separately in [MSC3673](https://github.com/matrix-org/matrix-doc/pull/3673). This would prevent location data from being readable by homeservers participating in the room.
All other behaviour is the same as in MSC3489. The only difference is that
`m.beacon` events are EDUs.
Likewise, end-to-end encryption for state events could be provided by [MSC3414](https://github.com/matrix-org/matrix-spec-proposals/pull/3414). This would hide the metadata that a user has started or stopped sharing their location from being known to the homeservers participating in the room.
### Delivery guarantees
MSC2477 specifically avoids defining delivery guarantees for user-defined EDUs,
so we avoid making hard recommendations here. We expect that future MSCs will
clarify the available options. When that happens, clients should choose the
available option that suits their use case, which we expect will be broadly in
line with the following paragraph.
Servers should attempt to deliver `m.beacon` EDUs to all clients, and delete
them as soon as possible. Servers should implement a timeout mechanism to ensure
they are always deleted, even if undelivered. For the expected use cases, we
suggest 30 minutes would be a suitable timeout.
## Security considerations
The security considerations are identical to MSC3489, except that EDUs
provide a better privacy situation because they are not persisted long-term.
## Alternatives
Alternatively, we could negotiate a WebRTC data channel using [MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401)
Alternatively, we could negotiate a WebRTC data channel using
Andy Balaam
2 years ago