Skip to content

Commit a15271b

Browse files
turt2liveturt2live
authored
MSC4260: Reporting users (Client-Server API) (#4260)
* MSC: Reporting users (Client-Server API) * Add guest access requirements * Add examples; fix reason * Clarify that reports don't transit federation, but can still be received
1 parent 3f3b34a commit a15271b

File tree

1 file changed

+139
-0
lines changed

1 file changed

+139
-0
lines changed

‎proposals/4260-report-user.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# MSC4260: Reporting users (Client-Server API)
2+
3+
[MSC4151 (merged)](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4151-report-room.md)
4+
added an endpoint to report entire rooms to the server admin, expanding upon the existing report event
5+
API. To fully complement this set of APIs, this proposal introduces a Client-Server API endpoint to
6+
report entire users, independent of rooms.
7+
8+
Like MSC4151, the scope of this MSC is intentionally narrow to facilitate quick traversal through the
9+
MSC process. Other, future, MSCs may be required to build out even more APIs for reporting content.
10+
11+
Also like MSC4151, it is expected that a future series of MSCs will revamp reporting in Matrix.
12+
13+
## Proposal
14+
15+
Taking inspiration from [`POST /rooms/:roomId/report/:eventId`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3roomsroomidreporteventid),
16+
a new endpoint is introduced:
17+
18+
```
19+
POST /_matrix/client/v3/users/:userId/report
20+
{
21+
"reason": "<user-supplied, may be empty>"
22+
}
23+
```
24+
25+
`reason` is a human-readable string describing the reason for the report. The string may be blank,
26+
but *must* be provided (to align with `/report/:eventId`).
27+
28+
**Note**: `score` is not carried over from `/report/:eventId` because it has not proven useful. A
29+
future MSC may introduce it. The same was done in MSC4151 for `/rooms/:roomId/report`.
30+
31+
There are no restictions on who can report a user: knowing the user ID is sufficient. This is to
32+
ensure that results from the user directory, invites, links, etc can all be reported. If the user
33+
does not exist on the server, the endpoint returns `404 M_NOT_FOUND`. Otherwise, `200` with `{}` as
34+
a response body. If a user doesn't exist and the server wishes to hide that detail, it MAY return a
35+
successful (`200`) response instead.
36+
37+
Like `/report/:eventId`, handling of the report is left as a deliberate implementation detail.
38+
39+
### Examples
40+
41+
**Note**: Some clients may need to `encodeURIComponent` (or similar) the user ID to use it in a path
42+
parameter.
43+
44+
```
45+
POST /_matrix/client/v3/users/@alice:example.org/report
46+
{"reason":"bad person"}
47+
48+
> 200 OK
49+
> {}
50+
```
51+
52+
```
53+
POST /_matrix/client/v3/users/@alice:example.org/report
54+
{"reason":""}
55+
56+
> 200 OK
57+
> {}
58+
```
59+
60+
```
61+
POST /_matrix/client/v3/users/@alice:example.org/report
62+
{"reason":""}
63+
64+
> 404 OK
65+
> {"errcode":"M_NOT_FOUND","error":"User does not exist"}
66+
```
67+
68+
## Safety considerations
69+
70+
* Server admins may be exposed to harmful content through `reason`. This is an existing issue with
71+
the reporting module, and difficult to fix. Applications which expose report reasons of any kind
72+
are encouraged to place disclosures in the user experience path. For example, a page explaining
73+
that the tool may contain harmful content before allowing the user temporary access, or the use of
74+
spoiler tags on report reasons/content.
75+
76+
* Clients MAY add reported users to the [ignore list](https://spec.matrix.org/v1.13/client-server-api/#ignoring-users)
77+
to both discourage duplicate reports and to remove the harmful content from the user's view, where
78+
possible. This may require filtering user directory responses and local timeline filtering.
79+
80+
* Users may report other users instead of events in any specific room, particularly during a harmful
81+
content spam wave. Administrators and safety teams should aim to clean up a user's events if they
82+
take action against the account, where appropriate.
83+
84+
* 'Report flooding' is more easily possible with this new endpoint, where many users report a user
85+
with the hope of getting them kicked off the server. Automated decision making is not recommended
86+
for this endpoint to prevent consequences like this from happening. Teams may wish to consider using
87+
reversible options like [suspension](https://spec.matrix.org/v1.13/client-server-api/#account-suspension)
88+
and [locking](https://spec.matrix.org/v1.13/client-server-api/#account-locking).
89+
90+
## Potential issues
91+
92+
* Within the Trust & Safety environment, it is well known that `reason` alone is insufficient for an
93+
informed report. Self-triage categories and mandatory `reason` for some of those categories help
94+
improve a safety team's ability to handle a report. These features are not included in this proposal
95+
as they require further thought and consideration - a future MSC may expand (or even deprecate) the
96+
report endpoints to support this added information.
97+
98+
* While reports against non-local users are permitted, this MSC does not introduce a way for those
99+
reports to transit federation to the target's server. This is considered an issue for another MSC,
100+
like [MSC3843](https://github.com/matrix-org/matrix-spec-proposals/pull/3843) or
101+
[MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202).
102+
103+
* Whether a user exists on the server is revealed through the new endpoint. Servers have the option
104+
to mask this detail by ignoring the report.
105+
106+
## Alternatives
107+
108+
* If the client is aiming to report a user within a room, reporting the membership event within that
109+
room may be suitable. If the user is aiming to report a broad pattern of behaviour, or a profile
110+
concern spanning multiple rooms/communities, a more generic API is preferred. A dedicated API is
111+
also required when users are shown outside the context of a room, such as during invites (when event
112+
IDs may not be known) or when looking for users/friends to chat to.
113+
114+
* [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202) discusses the idea of
115+
reporting profiles generally, and aims to work within the context of a room. Introducing a new
116+
dedicated endpoint is compatible with MSC4202's objectives.
117+
118+
## Security considerations
119+
120+
* Rate limiting is strongly recommended for this new endpoint.
121+
122+
* Authentication is required for this new endpoint.
123+
124+
* Guest access is not permitted for this new endpoint to reduce spam. A future MSC may change this
125+
out of necessity. MSC4151 and the original report events API are likely similarly affected.
126+
127+
* Servers which opt to hide the existence of a user on the new endpoint should consider implementing
128+
a constant time function to avoid unintentionally disclosing that a user exists by processing the
129+
request slower.
130+
131+
## Unstable prefix
132+
133+
While this proposal is not considered stable, implementations should use `/_matrix/client/unstable/org.matrix.msc4260/users/:userId/report`
134+
instead. Clients should note the [`M_UNRECOGNIZED` behaviour](https://spec.matrix.org/v1.13/client-server-api/#common-error-codes)
135+
for servers which do not support the (un)stable endpoint.
136+
137+
## Dependencies
138+
139+
This MSC has no direct dependencies.

0 commit comments

Comments
 (0)