From 12066dd84cb5344dd181d5845124e11346d9e313 Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Fri, 21 Jan 2022 16:56:14 +0200 Subject: [PATCH 01/21] MSC3672: Sharing ephemeral streams of location data --- .../3672-ephemeral-location-streaming.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 proposals/3672-ephemeral-location-streaming.md diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md new file mode 100644 index 0000000000..d3a8e01a53 --- /dev/null +++ b/proposals/3672-ephemeral-location-streaming.md @@ -0,0 +1,107 @@ +# MSC3672 - Sharing ephemeral streams of location data + +## Problem + +[MSC3489](https://github.com/matrix-org/matrix-doc/blob/matthew/location-streaming/proposals/3489-location-streaming.md) +focuses on streaming persistent location data for applications that require +historical knowledge. + +We also need the ability to share this data in a non-persistent way for cases in +which privacy is a concern, like user locations. + +## Proposal + +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 [MSC2476](https://github.com/ananace/matrix-doc/blob/user-defined-edus/proposals/2477-user-defined-ephemeral-events.md). + +In order to do so we will start by introducing a new boolean property on +`m.beacon_info` called `live` which will mark the start of an user's +intent to share ephemeral location information. + +```json5 +{ + "type": "m.beacon_info.@stefan:matrix.org", + "state_key": "@stefan:matrix.org", + "content": { + "m.beacon_info": { + "description": "Stefan's live location", + "timeout": 600000, // how long from the last event until we consider the beacon inactive in milliseconds + "live": true // this is a live location beacon + }, + "m.ts": 1436829458432, // creation timestamp of the beacon on the client + "m.asset": { + "type": "m.self.live" // live user location tracking + } + } +} +``` + +We define this new property in order to allow clients to distinguish between +share types without potentially overwriting static ones. + +Multiple live beacons on the same timeline have the option of either aggregating +all available location EDUs or just the ones referencing a particular +`beacon_info`. + +Subsequently clients will start sending beacon data EDUs to the new +`rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals +`m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/blob/matthew/location-streaming/proposals/3489-location-streaming.md). + + +```json5 +{ + "m.relates_to": { // from MSC2674: https://github.com/matrix-org/matrix-doc/pull/2674 + "rel_type": "m.reference", // from MSC3267: https://github.com/matrix-org/matrix-doc/pull/3267 + "event_id": "$beacon_info" + }, + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Arbitrary beacon information" + }, + "m.ts": 1636829458432, +} +``` + +These will reach clients through `/sync`s `ephemeral` dictionary with the same +payload but with the addition of a `sender` which the clients can aggregate user +locations on. + +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`. + +## Encryption + +E2E encryption for EDUs isn't currently defined but as we're dealing with +privacy sensitive data we propose to wrap them inside the standard encryption +envelope: + +```json5 +{ + "algorithm": "m.megolm.v1.aes-sha2", + "sender_key": "", + "device_id": "", + "session_id": "", + "ciphertext": "" +} +``` + +in which the `ciphertext` will contain the `m.beacon` payload defined above and +which will be sent to `rooms/{roomId}/ephemeral/m.room.encrypted/{txnId}` + +The Megolm keys required to decrypt this EDU should be shared over Olm just like +regular encrypted timeline events. + +## Alternatives + +Alternatively, we could negotiate a WebRTC data channel using [MSC3401](https://github.com/matrix-org/matrix-doc/blob/matthew/group-voip/proposals/3401-group-voip.md) and stream low-latency geospatial data over the +participating devices in the room. However it would be useful to support plain +HTTP like the rest of Matrix and requiring a WebRTC stack is prohibitively +complicated for simple clients (e.g. basic IOT devices reporting spatial telemetry). + +## Unstable prefix + + * `m.beacon_info.*` should be referred to as `org.matrix.msc3489.beacon_info.*` until this MSC lands. + * `m.beacon` should be referred to as `org.matrix.msc3489.beacon` until this MSC lands. + * `m.location` should be referred to as `org.matrix.msc3488.location.*` until MSC3488 lands. + * `m.ts` should be referred to as `org.matrix.msc3488.ts.*` until MSC3488 lands. + * `m.asset` should be referred to as `org.matrix.msc3488.asset.*` until MSC3488 lands. \ No newline at end of file From 55fb0edf1f886cd1714131a9b016a4e5bbe33b20 Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Wed, 26 Jan 2022 09:30:37 +0200 Subject: [PATCH 02/21] Referencing MSCs through PR link instead of rendered. --- proposals/3672-ephemeral-location-streaming.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index d3a8e01a53..43190b23ae 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -2,7 +2,7 @@ ## Problem -[MSC3489](https://github.com/matrix-org/matrix-doc/blob/matthew/location-streaming/proposals/3489-location-streaming.md) +[MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489) focuses on streaming persistent location data for applications that require historical knowledge. @@ -12,7 +12,7 @@ which privacy is a concern, like user locations. ## Proposal 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 [MSC2476](https://github.com/ananace/matrix-doc/blob/user-defined-edus/proposals/2477-user-defined-ephemeral-events.md). +the use of custom Ephemeral Data Units (EDUs) by building on top of [MSC2477](https://github.com/matrix-org/matrix-doc/pull/2477). In order to do so we will start by introducing a new boolean property on `m.beacon_info` called `live` which will mark the start of an user's @@ -45,7 +45,7 @@ all available location EDUs or just the ones referencing a particular Subsequently clients will start sending beacon data EDUs to the new `rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals -`m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/blob/matthew/location-streaming/proposals/3489-location-streaming.md). +`m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489). ```json5 @@ -93,10 +93,11 @@ regular encrypted timeline events. ## Alternatives -Alternatively, we could negotiate a WebRTC data channel using [MSC3401](https://github.com/matrix-org/matrix-doc/blob/matthew/group-voip/proposals/3401-group-voip.md) and stream low-latency geospatial data over the -participating devices in the room. However it would be useful to support plain -HTTP like the rest of Matrix and requiring a WebRTC stack is prohibitively -complicated for simple clients (e.g. basic IOT devices reporting spatial telemetry). +Alternatively, we could negotiate a WebRTC data channel using [MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401) +and stream low-latency geospatial data over the participating devices in the +room. However it would be useful to support plain HTTP like the rest of Matrix +and requiring a WebRTC stack is prohibitively complicated for simple clients +(e.g. basic IOT devices reporting spatial telemetry). ## Unstable prefix From 861dc4c546f938adaabd2700f98ee83dc1b5a09c Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Wed, 26 Jan 2022 09:36:19 +0200 Subject: [PATCH 03/21] Link to encrypted EDUs MSC. --- .../3672-ephemeral-location-streaming.md | 21 ++----------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 43190b23ae..d6ba459396 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -71,25 +71,8 @@ original `m.beacon_info`'s `live` property should be set to `false`. ## Encryption -E2E encryption for EDUs isn't currently defined but as we're dealing with -privacy sensitive data we propose to wrap them inside the standard encryption -envelope: - -```json5 -{ - "algorithm": "m.megolm.v1.aes-sha2", - "sender_key": "", - "device_id": "", - "session_id": "", - "ciphertext": "" -} -``` - -in which the `ciphertext` will contain the `m.beacon` payload defined above and -which will be sent to `rooms/{roomId}/ephemeral/m.room.encrypted/{txnId}` - -The Megolm keys required to decrypt this EDU should be shared over Olm just like -regular encrypted timeline events. +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) ## Alternatives From c7c032e9bc1402cf340977ccd7f0e6065a1be79f Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Wed, 26 Jan 2022 09:48:21 +0200 Subject: [PATCH 04/21] Add to-device alternative. --- proposals/3672-ephemeral-location-streaming.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index d6ba459396..5855cdd3fc 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -82,6 +82,10 @@ room. However it would be useful to support plain HTTP like the rest of Matrix and requiring a WebRTC stack is prohibitively complicated for simple clients (e.g. basic IOT devices reporting spatial telemetry). +Another alternative is to use to-device events but that comes with disadvantages +of its own as they're 1:1, single message per transaction and not intended for +conversational data. + ## Unstable prefix * `m.beacon_info.*` should be referred to as `org.matrix.msc3489.beacon_info.*` until this MSC lands. From 2a26b20b9d99a8bdc3412fcf1e94b6248ea26afe Mon Sep 17 00:00:00 2001 From: Stefan Ceriu Date: Wed, 26 Jan 2022 12:29:38 +0200 Subject: [PATCH 05/21] Add more details on EDUs and use cases. --- .../3672-ephemeral-location-streaming.md | 23 +++++++++++++++---- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 5855cdd3fc..4b9cfd9013 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -6,17 +6,30 @@ focuses on streaming persistent location data for applications that require historical knowledge. -We also need the ability to share this data in a non-persistent way for cases in -which privacy is a concern, like user locations. +While that's perfect for situations in which long term storage of the data is a +non-issue and implied (e.g. flight paths, strava style exercises, fleet +tracking), there are also cases in doing so is undersirable for either privacy +or performance reasons. + +Sharing user live location updates is one of the cases in which privacy is +paramount and where we need the ability to share data in a safe and +non-persistent fashion. ## Proposal 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). -In order to do so we will start by introducing a new boolean property on -`m.beacon_info` called `live` which will mark the start of an user's -intent to share ephemeral location information. +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 a new boolean property on `m.beacon_info` called +`live` which will mark the start of an user's intent to share ephemeral location +information. ```json5 { From f439d3e848ae852198ab5598ffff059e64ed888f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 14:27:00 +0100 Subject: [PATCH 06/21] typo --- proposals/3672-ephemeral-location-streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 4b9cfd9013..6db3d34e4f 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -8,7 +8,7 @@ historical knowledge. While that's perfect for situations in which long term storage of the data is a non-issue and implied (e.g. flight paths, strava style exercises, fleet -tracking), there are also cases in doing so is undersirable for either privacy +tracking), there are also cases in doing so is undesirable for either privacy or performance reasons. Sharing user live location updates is one of the cases in which privacy is From fb309964326628d0464cb2cfa3d6f5e98ca7de4d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 14:55:20 +0100 Subject: [PATCH 07/21] Describe each field in a table, clean up example --- .../3672-ephemeral-location-streaming.md | 43 +++++++++++++++---- 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 6db3d34e4f..5bffc06ba5 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -27,23 +27,50 @@ 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 a new boolean property on `m.beacon_info` called -`live` which will mark the start of an user's intent to share ephemeral location -information. +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. + +**`m.beacon_info` state event definition** + +| type | key | value | description | Required | +| ---- | ----| ----- | ----------- | -------- | +| string | `type` | `m.beacon_info` | This state event defines a single location sharing session. | yes | +| string | `state_key` | 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. | yes | +| dict | `content->m.beacon_info` | An `m.beacon_info` dictionary (see below) | This defines the current state of the live location sharing session. | yes | +| int | `m.ts` | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. | yes +| dict | `m.asset` | A dictionary (see below) | Describes the object being tracked. From [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). | yes + +**`m.beacon_info` dictionary definition** + +| type | key | value | description | required | +| ---- | --- | ----- | ----------- | -------- | +| int | `timeout` | A positive number of milliseconds | The maximum length of the location sharing session, relative to a `m.ts`. | yes +| string | `description` | Optional descriptive text | A human-readable description of the live location sharing session. | no | +| bool | `live` | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes + +TODO: `m.beacon_info` being used in two contexts is confusing. + +**`m.asset` dictionary definition** + +| type | key | value | description | required | +| ---- | --- | ----- | ----------- | -------- | +| string | `type` | `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.@stefan:matrix.org", + "type": "m.beacon_info", "state_key": "@stefan:matrix.org", "content": { "m.beacon_info": { + "timeout": 600000, "description": "Stefan's live location", - "timeout": 600000, // how long from the last event until we consider the beacon inactive in milliseconds - "live": true // this is a live location beacon + "live": true }, - "m.ts": 1436829458432, // creation timestamp of the beacon on the client + "m.ts": 1436829458432, "m.asset": { - "type": "m.self.live" // live user location tracking + "type": "m.self" } } } From f063795a13a498e4a66145f7780857016c1c97dd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 14:55:48 +0100 Subject: [PATCH 08/21] Clarify m.beacon_info, m.beacon are now defined by this MSC --- proposals/3672-ephemeral-location-streaming.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 5bffc06ba5..8bf6656f1b 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -128,8 +128,13 @@ conversational data. ## Unstable prefix - * `m.beacon_info.*` should be referred to as `org.matrix.msc3489.beacon_info.*` until this MSC lands. - * `m.beacon` should be referred to as `org.matrix.msc3489.beacon` until this MSC lands. - * `m.location` should be referred to as `org.matrix.msc3488.location.*` until MSC3488 lands. - * `m.ts` should be referred to as `org.matrix.msc3488.ts.*` until MSC3488 lands. - * `m.asset` should be referred to as `org.matrix.msc3488.asset.*` until MSC3488 lands. \ No newline at end of file +Until this MSC is merged, the following unstable prefixes should be used: + + * Any instance of `m.beacon_info` should be referred to as `org.matrix.msc3672.beacon_info` + * `m.beacon` should be referred to as `org.matrix.msc3672.beacon` + + Until [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) is merged, the following unstable prefix should be used: + + * `m.location` should be referred to as `org.matrix.msc3488.location` + * `m.ts` should be referred to as `org.matrix.msc3488.ts` + * `m.asset` should be referred to as `org.matrix.msc3488.asset` \ No newline at end of file From 440a5d16aaf70a054d8e4e8178d788067b8870db Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 16:24:48 +0100 Subject: [PATCH 09/21] Mention that the current design does not support multi-share --- proposals/3672-ephemeral-location-streaming.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 8bf6656f1b..90e3e97573 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -39,6 +39,8 @@ We will start by introducing `m.beacon_info` as a new state event type; the even | int | `m.ts` | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. | yes | dict | `m.asset` | 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. + **`m.beacon_info` dictionary definition** | type | key | value | description | required | From a72bda3db0429d54f4dd86941d351a0bb8ebfb84 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 16:46:41 +0100 Subject: [PATCH 10/21] Note MSCs that we depend on --- proposals/3672-ephemeral-location-streaming.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 90e3e97573..82b40bb3e4 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -128,6 +128,13 @@ Another alternative is to use to-device events but that comes with disadvantages of its own as they're 1:1, single message per transaction and not intended for conversational data. +## Dependencies + +This proposal relies on the following MSCs: + +* [MSC2477: User-defined ephemeral events in rooms](https://github.com/matrix-org/matrix-doc/pull/2477) +* [MSC3488: Extending events with location data](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) + ## Unstable prefix Until this MSC is merged, the following unstable prefixes should be used: From de543b1a63fa2b662ddcb82732eb25014034e856 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 16:50:00 +0100 Subject: [PATCH 11/21] Rename Encryption section to Security considerations, and add another --- proposals/3672-ephemeral-location-streaming.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 82b40bb3e4..43d5759da1 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -111,10 +111,13 @@ locations on. 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`. -## Encryption +## Security considerations + +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. + +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. -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) ## Alternatives From 6144b23b53887c2296eb13449818a62a109829f0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 16:54:33 +0100 Subject: [PATCH 12/21] Add top-level fields to m.beacon EDU example --- .../3672-ephemeral-location-streaming.md | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 43d5759da1..b1116b032e 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -89,18 +89,24 @@ Subsequently clients will start sending beacon data EDUs to the new `rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals `m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489). +An full example of a `m.beacon` EDU: ```json5 { - "m.relates_to": { // from MSC2674: https://github.com/matrix-org/matrix-doc/pull/2674 - "rel_type": "m.reference", // from MSC3267: https://github.com/matrix-org/matrix-doc/pull/3267 - "event_id": "$beacon_info" - }, - "m.location": { - "uri": "geo:51.5008,0.1247;u=35", - "description": "Arbitrary beacon information" + "content": { + "m.relates_to": { // from MSC2674: https://github.com/matrix-org/matrix-doc/pull/2674 + "rel_type": "m.reference", // from MSC3267: https://github.com/matrix-org/matrix-doc/pull/3267 + "event_id": "$beacon_info" + }, + "m.location": { + "uri": "geo:51.5008,0.1247;u=35", + "description": "Arbitrary beacon information" + }, + "m.ts": 1636829458432, }, - "m.ts": 1636829458432, + "type": "m.beacon", + "sender": "@stefan:matrix.org", + "origin_server_ts": 1636829518182 } ``` From 35c20f6f1f9a489bd4c2972f77dcdf398a3952a6 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 17:16:50 +0100 Subject: [PATCH 13/21] Delete a paragraph that didn't make sense --- proposals/3672-ephemeral-location-streaming.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index b1116b032e..6c6fdcd575 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -78,9 +78,6 @@ A full example of the `m.beacon_info` state event: } ``` -We define this new property in order to allow clients to distinguish between -share types without potentially overwriting static ones. - Multiple live beacons on the same timeline have the option of either aggregating all available location EDUs or just the ones referencing a particular `beacon_info`. From a62d237d33c6425c8f610b08d0c9b6771ecccc60 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 17:18:49 +0100 Subject: [PATCH 14/21] Clarify some client UI suggestions from multiple shares --- proposals/3672-ephemeral-location-streaming.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 6c6fdcd575..2a367fe0a8 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -78,8 +78,8 @@ A full example of the `m.beacon_info` state event: } ``` -Multiple live beacons on the same timeline have the option of either aggregating -all available location EDUs or just the ones referencing a particular +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 `beacon_info`. Subsequently clients will start sending beacon data EDUs to the new From 76df8b50fd091fc0d58181a9bac99d6a40389e0a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 17:19:41 +0100 Subject: [PATCH 15/21] Clarify m.beacon example --- proposals/3672-ephemeral-location-streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 2a367fe0a8..16b133c7ae 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -86,7 +86,7 @@ Subsequently clients will start sending beacon data EDUs to the new `rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals `m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489). -An full example of a `m.beacon` EDU: +An full example of a `m.beacon` EDU as received by a client: ```json5 { From 4a922c44f18fb2ea024ff72ab9f0f7bffd437585 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 6 Apr 2022 17:20:46 +0100 Subject: [PATCH 16/21] Remove paragraph that was already made clear by MSC2477 --- proposals/3672-ephemeral-location-streaming.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 16b133c7ae..07dd703f96 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -107,10 +107,6 @@ An full example of a `m.beacon` EDU as received by a client: } ``` -These will reach clients through `/sync`s `ephemeral` dictionary with the same -payload but with the addition of a `sender` which the clients can aggregate user -locations on. - 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`. From f0356944e9b23df2ba29cdfb98ba9083b1fa46ee Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 7 Apr 2022 14:38:36 +0100 Subject: [PATCH 17/21] Remove superfluous inner m.beacon_info dict --- .../3672-ephemeral-location-streaming.md | 32 +++++++------------ 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 07dd703f96..627e6d5556 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -35,22 +35,14 @@ We will start by introducing `m.beacon_info` as a new state event type; the even | ---- | ----| ----- | ----------- | -------- | | string | `type` | `m.beacon_info` | This state event defines a single location sharing session. | yes | | string | `state_key` | 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. | yes | -| dict | `content->m.beacon_info` | An `m.beacon_info` dictionary (see below) | This defines the current state of the live location sharing session. | yes | +| int | `timeout` | A positive number of milliseconds | The maximum length of the location sharing session, relative to `m.ts`. | yes +| string | `description` | Optional descriptive text | A human-readable description of the live location sharing session. | no | +| bool | `live` | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes | int | `m.ts` | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. | yes | dict | `m.asset` | 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. -**`m.beacon_info` dictionary definition** - -| type | key | value | description | required | -| ---- | --- | ----- | ----------- | -------- | -| int | `timeout` | A positive number of milliseconds | The maximum length of the location sharing session, relative to a `m.ts`. | yes -| string | `description` | Optional descriptive text | A human-readable description of the live location sharing session. | no | -| bool | `live` | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes - -TODO: `m.beacon_info` being used in two contexts is confusing. - **`m.asset` dictionary definition** | type | key | value | description | required | @@ -65,11 +57,9 @@ A full example of the `m.beacon_info` state event: "type": "m.beacon_info", "state_key": "@stefan:matrix.org", "content": { - "m.beacon_info": { - "timeout": 600000, - "description": "Stefan's live location", - "live": true - }, + "timeout": 600000, + "description": "Stefan's live location", + "live": true, "m.ts": 1436829458432, "m.asset": { "type": "m.self" @@ -78,10 +68,6 @@ A full example of the `m.beacon_info` state event: } ``` -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 -`beacon_info`. - Subsequently clients will start sending beacon data EDUs to the new `rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals `m.beacon` with the same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489). @@ -107,6 +93,10 @@ An full example of a `m.beacon` EDU as received by a client: } ``` +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`. @@ -141,7 +131,7 @@ This proposal relies on the following MSCs: Until this MSC is merged, the following unstable prefixes should be used: - * Any instance of `m.beacon_info` should be referred to as `org.matrix.msc3672.beacon_info` + * `m.beacon_info` should be referred to as `org.matrix.msc3672.beacon_info` * `m.beacon` should be referred to as `org.matrix.msc3672.beacon` Until [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) is merged, the following unstable prefix should be used: From e07abb3ed5f50689321e8b5129a778a00245a4bd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 7 Apr 2022 14:40:28 +0100 Subject: [PATCH 18/21] swap type and key columns in the field definition tables --- .../3672-ephemeral-location-streaming.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 627e6d5556..f3fcf3925a 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -31,23 +31,23 @@ We will start by introducing `m.beacon_info` as a new state event type; the even **`m.beacon_info` state event definition** -| type | key | value | description | Required | +| key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | -| string | `type` | `m.beacon_info` | This state event defines a single location sharing session. | yes | -| string | `state_key` | 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. | yes | -| int | `timeout` | A positive number of milliseconds | The maximum length of the location sharing session, relative to `m.ts`. | yes -| string | `description` | Optional descriptive text | A human-readable description of the live location sharing session. | no | -| bool | `live` | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes -| int | `m.ts` | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. | yes -| dict | `m.asset` | A dictionary (see below) | Describes the object being tracked. From [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). | yes +| `type` | string | `m.beacon_info` | This state event defines a single location sharing session. | yes | +| `state_key` | string | 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. | yes | +| `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. | 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. **`m.asset` dictionary definition** -| type | key | value | description | required | +| key | type | value | description | required | | ---- | --- | ----- | ----------- | -------- | -| string | `type` | `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 | +| `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: From 45389a5cb714d599709cd8989a9dab6222c9afc6 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 7 Apr 2022 18:19:04 +0100 Subject: [PATCH 19/21] Clean up field definitions, add table for m.beacon --- .../3672-ephemeral-location-streaming.md | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index f3fcf3925a..92f4885c2f 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -29,12 +29,12 @@ updates. As an extra precaution they can also be encrypted as defined in [MSC367 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. -**`m.beacon_info` state event definition** +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 | | ---- | ----| ----- | ----------- | -------- | -| `type` | string | `m.beacon_info` | This state event defines a single location sharing session. | yes | -| `state_key` | string | 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. | yes | | `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 @@ -43,6 +43,8 @@ We will start by introducing `m.beacon_info` as a new state event type; the even 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 | @@ -64,21 +66,32 @@ A full example of the `m.beacon_info` state event: "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 same location payload as defined in [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489). +`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": { // from MSC2674: https://github.com/matrix-org/matrix-doc/pull/2674 - "rel_type": "m.reference", // from MSC3267: https://github.com/matrix-org/matrix-doc/pull/3267 + "m.relates_to": { + "rel_type": "m.reference", "event_id": "$beacon_info" }, "m.location": { From 43d224accc81a8335305d22790f7eb1d61f282f8 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 3 May 2022 17:27:28 +0100 Subject: [PATCH 20/21] Clarify that m.ts is in milliseconds --- proposals/3672-ephemeral-location-streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index 92f4885c2f..fd701f8bc6 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -38,7 +38,7 @@ The `state_key` of this state event must be send to the sender's MXID. As per [e | `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. | 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. From 750635d72955b5e1f3fda52c45242dc1eaba0af0 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 May 2022 14:29:28 +0100 Subject: [PATCH 21/21] Remodel to lean heavily on MSC3489, instead of repeating --- .../3672-ephemeral-location-streaming.md | 185 ++++++------------ 1 file changed, 64 insertions(+), 121 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index fd701f8bc6..626a25ec74 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -2,153 +2,96 @@ ## Problem -[MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489) +[MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489) focuses on streaming persistent location data for applications that require -historical knowledge. +historical knowledge. -While that's perfect for situations in which long term storage of the data is a -non-issue and implied (e.g. flight paths, strava style exercises, fleet -tracking), there are also cases in doing so is undesirable for either privacy +While that's perfect for situations in which long term storage of the data is a +non-issue and implied (e.g. flight paths, strava style exercises, fleet +tracking), there are also cases in doing so is undesirable for either privacy or performance reasons. -Sharing user live location updates is one of the cases in which privacy is -paramount and where we need the ability to share data in a safe and +Sharing user live location updates is one of the cases in which privacy is +paramount and where we need the ability to share data in a safe and non-persistent fashion. ## Proposal -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). - -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`. +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. -## Security considerations +Ephemeral data units (EDUs) are Matrix's default mechanism for broadcasting +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. + +To allow the use of EDUs for live location sharing, this MSC depends on +[MSC2477](https://github.com/matrix-org/matrix-spec-proposals/pull/2477/) +for user-defined EDUs, and +[MSC3673](https://github.com/matrix-org/matrix-spec-proposals/pull/3673) +for encrypted EDUs. + +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). + +All other behaviour is the same as in MSC3489. The only difference is that +`m.beacon` events are EDUs. -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. +### Delivery guarantees -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. +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) -and stream low-latency geospatial data over the participating devices in the -room. However it would be useful to support plain HTTP like the rest of Matrix -and requiring a WebRTC stack is prohibitively complicated for simple clients +Alternatively, we could negotiate a WebRTC data channel using +[MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401) +and stream low-latency geospatial data over the participating devices in the +room. However it would be useful to support plain HTTP like the rest of Matrix +and requiring a WebRTC stack is prohibitively complicated for simple clients (e.g. basic IOT devices reporting spatial telemetry). Another alternative is to use to-device events but that comes with disadvantages -of its own as they're 1:1, single message per transaction and not intended for +of its own as they're 1:1, single message per transaction and not intended for conversational data. ## Dependencies This proposal relies on the following MSCs: -* [MSC2477: User-defined ephemeral events in rooms](https://github.com/matrix-org/matrix-doc/pull/2477) -* [MSC3488: Extending events with location data](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) +* [MSC2477: User-defined ephemeral events in rooms](https://github.com/matrix-org/matrix-spec-proposals/pull/2477) +* [MSC3673: Encrypted ephemeral data units](https://github.com/matrix-org/matrix-spec-proposals/pull/3673) +* [MSC3489: Sharing streams of location data with history](https://github.com/matrix-org/matrix-spec-proposals/pull/3489) -## Unstable prefix +For live location shares to work in appservices, these MSCs will also be +required: -Until this MSC is merged, the following unstable prefixes should be used: +* [MSC2409: Proposal to send EDUs to appservices](https://github.com/matrix-org/matrix-spec-proposals/pull/2409) +* [MSC3202: Encrypted appservices](https://github.com/matrix-org/matrix-spec-proposals/pull/3202) - * `m.beacon_info` should be referred to as `org.matrix.msc3672.beacon_info` - * `m.beacon` should be referred to as `org.matrix.msc3672.beacon` +## Unstable prefix - Until [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) is merged, the following unstable prefix should be used: +This MSC uses the same unstable prefixes as +[MSC3489](https://github.com/matrix-org/matrix-spec-proposals/pull/3489). - * `m.location` should be referred to as `org.matrix.msc3488.location` - * `m.ts` should be referred to as `org.matrix.msc3488.ts` - * `m.asset` should be referred to as `org.matrix.msc3488.asset` \ No newline at end of file +Note that MSC3489 actually uses prefixes that match this MSC's numbering. +This is an historical artifact of the various revision histories of these +proposals.