Skip to content

Commit 0da9d21

Browse files
clokepclokep
committed
Add proposal for intentional mentions.
1 parent 006ca6a commit 0da9d21

File tree

1 file changed

+268
-0
lines changed

1 file changed

+268
-0
lines changed

‎proposals/3951-intentional-mentions.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# MSC3951: Intentional Mentions
2+
3+
Mentioning other users on Matrix is difficult -- it is not possible to know if
4+
[mentioning a user by display name or Matrix ID](https://github.com/matrix-org/matrix-spec/issues/353)
5+
will count as a mention, but is also too easy to mistakenly mention a user.
6+
7+
(Note that throughout this proposal "mention" is considered equivalent to a "ping"
8+
or highlight notification.)
9+
10+
Some situations that result in unintentional mentions include:
11+
12+
* Replying to a message will re-issue pings from the initial message due to
13+
[fallback replies](https://spec.matrix.org/v1.5/client-server-api/#fallbacks-for-rich-replies). [^1]
14+
* Each time a message is edited the new version will be re-evaluated for mentions.
15+
* Mentions occurring [in spoiler contents](https://github.com/matrix-org/matrix-spec/issues/16)
16+
or [code blocks](https://github.com/matrix-org/matrix-spec/issues/15) are
17+
evaluated.
18+
* If the [localpart of your Matrix ID is a common word](https://github.com/matrix-org/matrix-spec-proposals/issues/3011)
19+
then the push rule matching usernames (`.m.rule.contains_user_name`) matches
20+
too often (e.g. Travis CI matching if your Matrix ID is `@travis:example.com`).
21+
* If the [localpart or display name of your Matrix ID matches the hostname](https://github.com/matrix-org/matrix-spec-proposals/issues/2735)
22+
(e.g. `@example:example.com` receives notifications whenever `@foo:example.com`
23+
is replied to).
24+
25+
As a sender you do not know if including the user's display name or Matrix ID would
26+
even be interpreting as a mention (see [issue 353](https://github.com/matrix-org/matrix-spec/issues/353)).
27+
28+
This also results in some unexpected behavior and bugs:
29+
30+
* Matrix users use "leetspeak" when sending messages to avoid mentions (e.g.
31+
referring to M4tthew instead of Matthew).
32+
* Matrix users will append emoji or other unique text in their display names to
33+
avoid unintentional pings.
34+
* It is impossible to ping one out of multiple people with the same localpart
35+
(or display name).
36+
* Since the relation between `body` and `formatted_body` is ill-defined and
37+
["pills" are converted to display names](https://github.com/matrix-org/matrix-spec/issues/714),
38+
this can result in missed messages.
39+
* Bridges [must use display names](https://github.com/matrix-org/matrix-spec/issues/353#issuecomment-1055809364)
40+
as a trick to get pings to work.
41+
* If a user changes their display name in a room than whether or not they are
42+
mentioned changes unless you use historical display names to process push rules.
43+
(TODO I think there's an issue about this?)
44+
45+
## Background
46+
47+
Mentions are powered by two of the default push rules that search an event's
48+
`content.body` field for the current user's display name
49+
([`.m.rule.contains_display_name`](https://spec.matrix.org/v1.5/client-server-api/#default-override-rules))
50+
or the localpart of their Matrix ID ([`.m.rule.contains_user_name`](https://spec.matrix.org/v1.5/client-server-api/#default-content-rules)).
51+
52+
There's also a [section about "user and room mentions"](https://spec.matrix.org/v1.5/client-server-api/#user-and-room-mentions)
53+
which defines that messages which mention the current user in the `formatted_body`
54+
of the message should be colored differently:
55+
56+
> If the current user is mentioned in a message (either by a mention as defined
57+
> in this module or by a push rule), the client should show that mention differently
58+
> from other mentions, such as by using a red background color to signify to the
59+
> user that they were mentioned.
60+
61+
## Proposal
62+
63+
Instead of searching a message's `body` for the user's display name or the localpart
64+
of their Matrix ID, it is proposed to use a field specific to mentions,[^2] and
65+
augment the push rules to search for the current user's Matrix ID.
66+
67+
### New event field
68+
69+
A new `mentions` field is added to the event content, it is an array of strings
70+
consistent of Matrix IDs.
71+
72+
To limit the potential for abuse, only the first 10 items in the array should be
73+
considered. It is recommended that homeservers reject locally created events with
74+
more than 10 mentions with an error with a status code of `400` and an errcode of
75+
`M_INVALID_PARAM`.
76+
77+
Clients should add a Matrix ID to this array whenever composing a message which
78+
includes an intentional [user mention](https://spec.matrix.org/v1.5/client-server-api/#user-and-room-mentions)
79+
(often called a "pill"). Clients may also add them at other times when it is
80+
obvious the user intends to explicitly mention a user.
81+
82+
The `mentions` field is part of the plaintext event body and should be encrypted
83+
into the ciphertext for encrypted events.
84+
85+
### New push rules
86+
87+
A new push rule condition and a new default push rule will be added:
88+
89+
```json
90+
{
91+
"rule_id": ".m.rule.user_is_mentioned",
92+
"default": true,
93+
"enabled": true,
94+
"conditions": [
95+
{
96+
"kind": "is_mention"
97+
}
98+
],
99+
"actions": [
100+
"notify",
101+
{
102+
"set_tweak": "sound",
103+
"value": "default"
104+
},
105+
{
106+
"set_tweak": "highlight"
107+
}
108+
]
109+
}
110+
```
111+
112+
The `is_mention` push condition is defined as[^3]:
113+
114+
> This matches messages where the `content.mentions` is an array containing the
115+
> owner’s Matrix ID in the first 10 entries. This condition has no parameters.
116+
> If the `mentions` key is absent or not an array then the rule does not match;
117+
> any array entries which are not strings are ignored, but count against the limit.
118+
119+
An example matching event is provided below:
120+
121+
```json
122+
{
123+
"content": {
124+
"body": "This is an example mention @alice:example.org",
125+
"format": "org.matrix.custom.html",
126+
"formatted_body": "<b>This is an example mention</b> <a href='https://matrix.to/#/@alice:example.org'>Alice</a>",
127+
"msgtype": "m.text",
128+
"mentions": ["@alice:example.org"]
129+
},
130+
"event_id": "$143273582443PhrSn:example.org",
131+
"origin_server_ts": 1432735824653,
132+
"room_id": "!somewhere:over.the.rainbow",
133+
"sender": "@example:example.org",
134+
"type": "m.room.message",
135+
"unsigned": {
136+
"age": 1234
137+
}
138+
}
139+
```
140+
141+
### Backwards compatibility
142+
143+
The the [`.m.rule.contains_display_name`](https://spec.matrix.org/v1.5/client-server-api/#default-override-rules)
144+
and [`.m.rule.contains_user_name`](https://spec.matrix.org/v1.5/client-server-api/#default-content-rules)
145+
push rules are both deprecated. To avoid the unintentional mentions they are both
146+
modified to only apply when the `mentions` field is missing. As this is for
147+
backwards-compatibility it is not implemented using a generic mechanism, but
148+
behavior specific to those push rules with those IDs.
149+
150+
While this is being deployed there will be a mismatch for legacy clients which
151+
implement the deprecated `.m.rule.contains_display_name` and `.m.rule.contains_user_name`
152+
push rules locally while the `.m.rule.user_is_mentioned` push rule is used on
153+
the homeserver; as messages which
154+
[mention the user should also include the user's localpart](https://spec.matrix.org/v1.5/client-server-api/#user-and-room-mentions)
155+
in the message `body` it is likely that the `.m.rule.contains_user_name`
156+
will also match. It is postulated that this will not cause issues in most cases.
157+
158+
## Potential issues
159+
160+
### Abuse potential
161+
162+
This proposal makes it trivial to "hide" mentions since it does not require the
163+
mentioned Matrix IDs to be part of the displayed text. This is not seen as
164+
worse than what is possible today.
165+
166+
From discussions and research while writing this MSC there are some benefits to
167+
using a separate field for mentions:
168+
169+
* The number of mentions is trivially limited.
170+
* Various forms of "mention bombing" are no longer possible.
171+
* It is simpler to collect data on how many users are being mentioned (without
172+
having to process the textual `body` for every user's display name and local
173+
part).
174+
175+
Nonetheless, the conversations did result in some ideas to combat the potential
176+
for abuse, many of which apply regardless of whether this proposal is implemented.
177+
178+
Clients could expose *why* an event has caused a notification and give users inline
179+
tools to combat potential abuse. For example, a client might show a tooltip:
180+
181+
> The sender of the message (`@alice:example.org`) mentioned you in this event.
182+
>
183+
> Block `@alice:example.org` from sending you messages? `[Yes]` `[No]`
184+
185+
It could also be worth exposing user interface for moderators to see messages
186+
which mention many users.
187+
188+
A future MSC might wish to explore features for trusted contacts or soft-ignores
189+
to give users more control over who can generate notifications.
190+
191+
Overall the proposal does not seem to increase the potential for malicious behavior.
192+
193+
## Alternatives
194+
195+
### Prior proposals
196+
197+
There's a few prior proposals which tackle subsets of the above problem:
198+
199+
* [MSC2463](https://github.com/matrix-org/matrix-spec-proposals/pull/2463):
200+
excludes searching inside a Matrix ID for localparts / display names of other
201+
users.
202+
* [MSC3517](https://github.com/matrix-org/matrix-spec-proposals/pull/3517):
203+
searches for Matrix IDs (instead of display name / localpart) and only searches
204+
specific event types & fields.
205+
* [Custom push rules](https://o.librepush.net/aux/matrix_reitools/pill_mention_rules.html)
206+
to search for matrix.to links instead of display name / localpart.
207+
208+
<summary>
209+
210+
This generates a new push rule to replace `.m.rule.contains_display_name` and
211+
`.m.rule.contains_user_name`:
212+
213+
```json
214+
{
215+
"conditions": [
216+
{
217+
"kind": "event_match",
218+
"key": "content.formatted_body",
219+
"pattern": "*https://matrix.to/#/@alice:example.org*"
220+
}
221+
],
222+
"actions" : [
223+
"notify",
224+
{
225+
"set_tweak": "sound",
226+
"value": "default"
227+
},
228+
{
229+
"set_tweak": "highlight"
230+
}
231+
]
232+
}
233+
```
234+
235+
</summary>
236+
237+
### Room version for backwards compatibility
238+
239+
Alternative backwards compatibility suggestions included using a new room version,
240+
similar to [MSC3932](https://github.com/matrix-org/matrix-spec-proposals/pull/3932)
241+
for extensible events. This does not seem like a good fit since room versions are
242+
not usually interested in non-state events. It would additionally require a stable
243+
room version before use, which would unnecessarily delay usage.
244+
245+
## Security considerations
246+
247+
None foreseen.
248+
249+
## Unstable prefix
250+
251+
During development the `.org.matrix.msc3951.is_user_mentioned` push rule will be
252+
used. If a client sees this rule available it should apply the custom logic discussed
253+
in the [backwards compatibility](#backwards-compatibility) section.
254+
255+
## Dependencies
256+
257+
N/A
258+
259+
[^1]: This MSC does not attempt to solve this problem, but [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/pull/2781)
260+
proposes removing reply fallbacks which would solve it. Although as noted in
261+
[MSC3676](https://github.com/matrix-org/matrix-spec-proposals/pull/3676) this
262+
may require landing [MSC3664](https://github.com/matrix-org/matrix-doc/pull/3664)
263+
in order to receive notifications of replies.
264+
265+
[^2]: As proposed in [issue 353](https://github.com/matrix-org/matrix-spec/issues/353).
266+
267+
[^3]: A new push condition is necessary since none of the current push conditions
268+
(e.g. `event_match`) can process arrays.

0 commit comments

Comments
 (0)