Skip to content

Commit 17e3cc1

Browse files
turt2liveSimonBrandnerclokeprichvdhzecakeh
committed
MSC2285: Private read receipts (#2285)
* What if we let people hide their read receipts? * Add unstable prefix * Update proposals/2285-hidden-read-receipts.md Co-authored-by: Šimon Brandner <simon.bra.ag@gmail.com> * Use a separate `receiptType` for hidden read receipts (#3750) * Update the way MSC2285 works Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Update proposals/2285-hidden-read-receipts.md Co-authored-by: Travis Ralston <travpc@gmail.com> * Clarify notification behaviour and other things Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Mention adding `m.fully_read` to `/receipt` * Rename MSC to `Private read receipts` Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Apply suggestions from review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions from review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Remove trailing comma Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions from review Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Apply suggestions from review Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * `r0` -> `v3` Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Describe how to determine server support while stable Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Be more precise about the failure mode Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Improve wording Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Improve wording Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Improve wording Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Be more explicit Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Be more explicit around server support Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Simplify text Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Be more explicit about detecting server support Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Add note about consistency Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Clarify how exactly to detect support * Try to fix clarity around precedence * Be clearer about alternatives Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Add sentence about `/receipt` federation Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Be more explicit about adding `m.read.private` to `/receipt` Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com> * Fix wrong RR type Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> Co-authored-by: Šimon Brandner <simon.bra.ag@gmail.com> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
1 parent 5788b7d commit 17e3cc1

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎proposals/2285-hidden-read-receipts.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# MSC2285: Private read receipts
2+
3+
Currently users must send read receipts in order to affect their notification
4+
counts, which alerts other people that the user has read their message. For
5+
primarily privacy reasons, it may be desirable to users to not advertise to
6+
others that they've read a message.
7+
8+
## Proposal
9+
10+
This MSC proposes adding a new `receiptType` (see [the receipts
11+
spec](https://spec.matrix.org/v1.3/client-server-api/#receipts)) of
12+
`m.read.private`. This `receiptType` is used when the user wants to affect their
13+
notification count but doesn't want other users to see their read receipt.
14+
15+
To move the user's private read receipt to `$123` the client can make a POST
16+
request to the [`/receipt`
17+
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid).
18+
For example:
19+
20+
```HTTP
21+
POST /_matrix/client/v3/rooms/!a:example.org/receipt/m.read.private/$123
22+
{}
23+
```
24+
25+
The MSC also proposes adding `m.fully_read` and `m.read.private` as a possible
26+
`receiptType` for `/receipt` to make this endpoint consistent with
27+
`/read_markers`. (we have two endpoints that do essentially the same thing, so
28+
it would make sense for them to be consistent)
29+
30+
Alternatively, the client can move the user's `m.fully_read` marker and/or
31+
`m.read` receipt at the same time as `m.read.private` by making a POST request
32+
to the [`/read_markers`
33+
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers).
34+
For example:
35+
36+
```HTTP
37+
POST /_matrix/client/r0/rooms/!a:example.org/read_markers
38+
{
39+
"m.fully_read": "$123",
40+
"m.read": "$123",
41+
"m.read.private": "$123"
42+
}
43+
```
44+
45+
Both `m.read` and `m.read.private` clear notifications in the same way. If the
46+
user sent two receipts into a room, the later one should be the one that decides
47+
the notification count.
48+
49+
The receipt that is more "ahead" of the other takes precedence when considering
50+
notifications and a client's rendering of read receipts. This means that given
51+
an ordered set of events A, B, C, and D the public read receipt could be at
52+
point C, private at point A. If the user moves the private receipt from A to B
53+
then the user's notification count is still considered from point C as the public
54+
receipt is further ahead, still. Other users would also see the user's public read
55+
receipt as not having moved. The user can then move the private read receipt
56+
to point D, hopping over the public receipt, to change their notification count.
57+
58+
For clarity, if the public receipt is "fast forwarded" to be at the same position
59+
as the private receipt then the public receipt is broadcast to other users, even
60+
if previously considered private.
61+
62+
Note that like regular read receipts today, neither receipt can cause a backwards
63+
movement: both receipts can only move forwards, but do not have to be ahead of
64+
each other. It's valid to, for example, update a public read receipt which lags
65+
20 messages behind the private one.
66+
67+
The `m.fully_read` property is now optional for the [`/read_markers`
68+
endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers)
69+
as sometimes we only want to send `m.read.private`.
70+
71+
The MSC proposes that from now on, not all things sent over `/receipt` are
72+
federated. Servers MUST NOT send receipts of `receiptType` `m.read.private` to
73+
any other user than the sender. Servers also MUST NOT send receipts of
74+
`receiptType` `m.read.private` to any server over federation.
75+
76+
## Security considerations
77+
78+
Servers could act as if `m.read.private` is the same as `m.read` so the user
79+
must already trust the homeserver to a degree however, and the methods of
80+
notifying the user to the problem are difficult to implement. Users can always
81+
run their own homeservers to ensure it behaves correctly.
82+
83+
## Potential issues
84+
85+
Clients which support read receipts would end up rendering the user's receipt as
86+
jumping down when they send a message. This is no different from how IRC and
87+
similarly bridged users are perceived today.
88+
89+
## Alternatives
90+
91+
It has been suggested to use account data to store the setting that controls
92+
whether read receipts should be private on a per-account/per-room basis. While
93+
this might have some benefits, it is much less flexible.
94+
95+
Previous iterations of this MSC additionally suggested that having an `m.hidden`
96+
flag on existing read receipts could work, however this feels like assigning too
97+
much responsibility to an existing structure.
98+
99+
## Unstable prefix
100+
101+
While this MSC is not considered stable, implementations should use
102+
`org.matrix.msc2285` as a namespace.
103+
104+
|Stable (post-FCP)|Unstable |
105+
|-----------------|---------------------------------|
106+
|`m.read.private` |`org.matrix.msc2285.read.private`|
107+
108+
Clients should check for server support before sending private read receipts:
109+
if the server does not support them, then a private read receipt will not clear
110+
any notifications for the user.
111+
112+
The presence of `org.matrix.msc2285` or `org.matrix.msc2285.stable` in
113+
`unstable_features` is a reliable indication that a server supports private read
114+
receipts; however the converse is not true: their absence does not necessarily
115+
mean that the server does *not* support private read receipts. In particular,
116+
the server may have been updated to a future spec version which includes
117+
private read receipts, and hence removed the `unstable_features` entry.
118+
119+
Therefore, if a client has this feature enabled, but the server does not advertise
120+
support for this MSC in `unstable_features`, the client should either keep sending
121+
private read receipts with the risk that notifications will not be clearing, or it
122+
should warn the user and start sending public read receipts instead.
123+
124+
To mitigate this problem, once this MSC gets merged and once it becomes a part of a
125+
spec version, clients should update their implementations as fast as possible to
126+
accommodate the fact that the way of detecting server support will change: clients
127+
will now be looking for that spec version in `/versions`.
128+
129+
### While the MSC is unstable
130+
131+
During this period, to detect server support clients should check for the
132+
presence of the `org.matrix.msc2285` flag in `unstable_features` on `/versions`.
133+
Clients are also required to use the unstable prefixes (see [unstable
134+
prefix](#unstable-prefix)) during this time.
135+
136+
### Once the MSC is merged but not in a spec version
137+
138+
Once this MSC is merged, but is not yet part of the spec, clients should rely on
139+
the presence of the `org.matrix.msc2285.stable` flag in `unstable_features` to
140+
determine server support. If the flag is present, clients are required to use
141+
stable prefixes (see [unstable prefix](#unstable-prefix)).
142+
143+
### Once the MSC is in a spec version
144+
145+
Once this MSC becomes a part of a spec version, clients should rely on the
146+
presence of the spec version, that supports the MSC, in `versions` on
147+
`/versions`, to determine support. Servers are encouraged to keep the
148+
`org.matrix.msc2285.stable` flag around for a reasonable amount of time
149+
to help smooth over the transition for clients. "Reasonable" is intentionally
150+
left as an implementation detail, however the MSC process currently recommends
151+
*at most* 2 months from the date of spec release.

0 commit comments

Comments
 (0)