179 lines
7.7 KiB
Markdown
179 lines
7.7 KiB
Markdown
# MSC2285: Private read receipts
|
|
|
|
Currently users must send read receipts in order to affect their notification
|
|
counts, which alerts other people that the user has read their message. For
|
|
primarily privacy reasons, it may be desirable to users to not advertise to
|
|
others that they've read a message.
|
|
|
|
## Proposal
|
|
|
|
This MSC proposes adding a new `receiptType` (see [the receipts
|
|
spec](https://spec.matrix.org/v1.3/client-server-api/#receipts)) of
|
|
`m.read.private`. This `receiptType` is used when the user wants to affect their
|
|
notification count but doesn't want other users to see their read receipt.
|
|
|
|
To move the user's private read receipt to `$123` the client can make a POST
|
|
request to the [`/receipt`
|
|
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid).
|
|
For example:
|
|
|
|
```HTTP
|
|
POST /_matrix/client/v3/rooms/!a:example.org/receipt/m.read.private/$123
|
|
{}
|
|
```
|
|
|
|
The MSC also proposes adding `m.fully_read` and `m.read.private` as a possible
|
|
`receiptType` for `/receipt` to make this endpoint consistent with
|
|
`/read_markers`. (we have two endpoints that do essentially the same thing, so
|
|
it would make sense for them to be consistent)
|
|
|
|
Alternatively, the client can move the user's `m.fully_read` marker and/or
|
|
`m.read` receipt at the same time as `m.read.private` by making a POST request
|
|
to the [`/read_markers`
|
|
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers).
|
|
For example:
|
|
|
|
```HTTP
|
|
POST /_matrix/client/r0/rooms/!a:example.org/read_markers
|
|
{
|
|
"m.fully_read": "$123",
|
|
"m.read": "$123",
|
|
"m.read.private": "$123"
|
|
}
|
|
```
|
|
|
|
Both `m.read` and `m.read.private` clear notifications in the same way. If the
|
|
user sent two receipts into a room, the later one should be the one that decides
|
|
the notification count.
|
|
|
|
The receipt that is more "ahead" of the other takes precedence when considering
|
|
notifications and a client's rendering of read receipts. This means that given
|
|
an ordered set of events A, B, C, and D the public read receipt could be at
|
|
point C, private at point A. If the user moves the private receipt from A to B
|
|
then the user's notification count is still considered from point C as the public
|
|
receipt is further ahead, still. Other users would also see the user's public read
|
|
receipt as not having moved. The user can then move the private read receipt
|
|
to point D, hopping over the public receipt, to change their notification count.
|
|
|
|
For clarity, if the public receipt is "fast forwarded" to be at the same position
|
|
as the private receipt then the public receipt is broadcast to other users, even
|
|
if previously considered private.
|
|
|
|
Note that like regular read receipts today, neither receipt can cause a backwards
|
|
movement: both receipts can only move forwards, but do not have to be ahead of
|
|
each other. It's valid to, for example, update a public read receipt which lags
|
|
20 messages behind the private one.
|
|
|
|
The `m.fully_read` property is now optional for the [`/read_markers`
|
|
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers)
|
|
as sometimes we only want to send `m.read.private`.
|
|
|
|
The MSC proposes that from now on, not all things sent over `/receipt` are
|
|
federated. Servers MUST NOT send receipts of `receiptType` `m.read.private` to
|
|
any other user than the sender. Servers also MUST NOT send receipts of
|
|
`receiptType` `m.read.private` to any server over federation.
|
|
|
|
As implied by adding a new `receiptType`, `m.read.private` receipts are echoed
|
|
back to clients through [`m.receipt`](https://spec.matrix.org/v1.3/client-server-api/#mreceipt).
|
|
The structure is the same as `m.read`. For example:
|
|
|
|
```json
|
|
{
|
|
"type": "m.receipt",
|
|
"content": {
|
|
"$event": {
|
|
"m.read": {
|
|
"@public_user:example.org": {
|
|
"ts": 1661385089714
|
|
}
|
|
},
|
|
"m.read.private": {
|
|
"@self:example.org": {
|
|
"ts": 1661385103450
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Due to the nature of private read receipts, the `m.read.private` map in `m.receipt`
|
|
should only ever have the user's own ID.
|
|
|
|
## Security considerations
|
|
|
|
Servers could act as if `m.read.private` is the same as `m.read` so the user
|
|
must already trust the homeserver to a degree however, and the methods of
|
|
notifying the user to the problem are difficult to implement. Users can always
|
|
run their own homeservers to ensure it behaves correctly.
|
|
|
|
## Potential issues
|
|
|
|
Clients which support read receipts would end up rendering the user's receipt as
|
|
jumping down when they send a message. This is no different from how IRC and
|
|
similarly bridged users are perceived today.
|
|
|
|
## Alternatives
|
|
|
|
It has been suggested to use account data to store the setting that controls
|
|
whether read receipts should be private on a per-account/per-room basis. While
|
|
this might have some benefits, it is much less flexible.
|
|
|
|
Previous iterations of this MSC additionally suggested that having an `m.hidden`
|
|
flag on existing read receipts could work, however this feels like assigning too
|
|
much responsibility to an existing structure.
|
|
|
|
## Unstable prefix
|
|
|
|
While this MSC is not considered stable, implementations should use
|
|
`org.matrix.msc2285` as a namespace.
|
|
|
|
|Stable (post-FCP)|Unstable |
|
|
|-----------------|---------------------------------|
|
|
|`m.read.private` |`org.matrix.msc2285.read.private`|
|
|
|
|
Clients should check for server support before sending private read receipts:
|
|
if the server does not support them, then a private read receipt will not clear
|
|
any notifications for the user.
|
|
|
|
The presence of `org.matrix.msc2285` or `org.matrix.msc2285.stable` in
|
|
`unstable_features` is a reliable indication that a server supports private read
|
|
receipts; however the converse is not true: their absence does not necessarily
|
|
mean that the server does *not* support private read receipts. In particular,
|
|
the server may have been updated to a future spec version which includes
|
|
private read receipts, and hence removed the `unstable_features` entry.
|
|
|
|
Therefore, if a client has this feature enabled, but the server does not advertise
|
|
support for this MSC in `unstable_features`, the client should either keep sending
|
|
private read receipts with the risk that notifications will not be clearing, or it
|
|
should warn the user and start sending public read receipts instead.
|
|
|
|
To mitigate this problem, once this MSC gets merged and once it becomes a part of a
|
|
spec version, clients should update their implementations as fast as possible to
|
|
accommodate the fact that the way of detecting server support will change: clients
|
|
will now be looking for that spec version in `/versions`.
|
|
|
|
### While the MSC is unstable
|
|
|
|
During this period, to detect server support clients should check for the
|
|
presence of the `org.matrix.msc2285` flag in `unstable_features` on `/versions`.
|
|
Clients are also required to use the unstable prefixes (see [unstable
|
|
prefix](#unstable-prefix)) during this time.
|
|
|
|
### Once the MSC is merged but not in a spec version
|
|
|
|
Once this MSC is merged, but is not yet part of the spec, clients should rely on
|
|
the presence of the `org.matrix.msc2285.stable` flag in `unstable_features` to
|
|
determine server support. If the flag is present, clients are required to use
|
|
stable prefixes (see [unstable prefix](#unstable-prefix)).
|
|
|
|
### Once the MSC is in a spec version
|
|
|
|
Once this MSC becomes a part of a spec version, clients should rely on the
|
|
presence of the spec version, that supports the MSC, in `versions` on
|
|
`/versions`, to determine support. Servers are encouraged to keep the
|
|
`org.matrix.msc2285.stable` flag around for a reasonable amount of time
|
|
to help smooth over the transition for clients. "Reasonable" is intentionally
|
|
left as an implementation detail, however the MSC process currently recommends
|
|
*at most* 2 months from the date of spec release.
|