From 56ba3fd5aa13a2e84f12868c3ffd5690f9d1e74d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Jan 2025 11:49:03 -0700 Subject: [PATCH 1/4] MSC: Reporting users (Client-Server API) --- proposals/4260-report-user.md | 104 ++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 proposals/4260-report-user.md diff --git a/proposals/4260-report-user.md b/proposals/4260-report-user.md new file mode 100644 index 00000000000..4d8b56a1d69 --- /dev/null +++ b/proposals/4260-report-user.md @@ -0,0 +1,104 @@ +# MSC4260: Reporting users (Client-Server API) + +[MSC4151 (merged)](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4151-report-room.md) +added an endpoint to report entire rooms to the server admin, expanding upon the existing report event +API. To fully complement this set of APIs, this proposal introduces a Client-Server API endpoint to +report entire users, independent of rooms. + +Like MSC4151, the scope of this MSC is intentionally narrow to facilitate quick traversal through the +MSC process. Other, future, MSCs may be required to build out even more APIs for reporting content. + +Also like MSC4151, it is expected that a future series of MSCs will revamp reporting in Matrix. + +## Proposal + +Taking inspiration from [`POST /rooms/:roomId/report/:eventId`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3roomsroomidreporteventid), +a new endpoint is introduced: + +``` +POST /_matrix/client/v3/users/:userId/report +{ + "reason": "" +} +``` + +`reason` is a human-readable string describing the reason for the report. The string may be blank, +but *must* be provided (to align with `/report/:eventId`). + +**Note**: `score` is not carried over from `/report/:eventId` because it has not proven useful. A +future MSC may introduce it. The same was done in MSC4151 for `/rooms/:roomId/report`. + +There are no restictions on who can report a user: knowing the user ID is sufficient. This is to +ensure that results from the user directory, invites, links, etc can all be reported. If the user +does not exist on the server, the endpoint returns `404 M_NOT_FOUND`. Otherwise, `200` with `{}` as +a response body. If a user doesn't exist and the server wishes to hide that detail, it MAY return a +successful (`200`) response instead. + +Like `/report/:eventId`, handling of the report is left as a deliberate implementation detail. + +## Safety considerations + +* Server admins may be exposed to harmful content through `reason`. This is an existing issue with + the reporting module, and difficult to fix. Applications which expose report reasons of any kind + are encouraged to place disclosures in the user experience path. For example, a page explaining + that the tool may contain harmful content before allowing the user temporary access, or the use of + spoiler tags on report reasons/content. + +* Clients MAY add reported users to the [ignore list](https://spec.matrix.org/v1.13/client-server-api/#ignoring-users) + to both discourage duplicate reports and to remove the harmful content from the user's view, where + possible. This may require filtering user directory responses and local timeline filtering. + +* Users may report other users instead of events in any specific room, particularly during a harmful + content spam wave. Administrators and safety teams should aim to clean up a user's events if they + take action against the account, where appropriate. + +* 'Report flooding' is more easily possible with this new endpoint, where many users report a user + with the hope of getting them kicked off the server. Automated decision making is not recommended + for this endpoint to prevent consequences like this from happening. Teams may wish to consider using + reversible options like [suspension](https://spec.matrix.org/v1.13/client-server-api/#account-suspension) + and [locking](https://spec.matrix.org/v1.13/client-server-api/#account-locking). + +## Potential issues + +* Within the Trust & Safety environment, it is well known that `reason` alone is insufficient for an + informed report. Self-triage categories and mandatory `reason` for some of those categories help + improve a safety team's ability to handle a report. These features are not included in this proposal + as they require further thought and consideration - a future MSC may expand (or even deprecate) the + report endpoints to support this added information. + +* Reports are not federated. This is considered an issue for another MSC, like [MSC3843](https://github.com/matrix-org/matrix-spec-proposals/pull/3843) or [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202). + +* Whether a user exists on the server is revealed through the new endpoint. Servers have the option + to mask this detail by ignoring the report. + +## Alternatives + +* If the client is aiming to report a user within a room, reporting the membership event within that + room may be suitable. If the user is aiming to report a broad pattern of behaviour, or a profile + concern spanning multiple rooms/communities, a more generic API is preferred. A dedicated API is + also required when users are shown outside the context of a room, such as during invites (when event + IDs may not be known) or when looking for users/friends to chat to. + +* [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202) discusses the idea of + reporting profiles generally, and aims to work within the context of a room. Introducing a new + dedicated endpoint is compatible with MSC4202's objectives. + +## Security considerations + +* Rate limiting is strongly recommended for this new endpoint. + +* Authentication is required for this new endpoint. + +* Servers which opt to hide the existence of a user on the new endpoint should consider implementing + a constant time function to avoid unintentionally disclosing that a user exists by processing the + request slower. + +## Unstable prefix + +While this proposal is not considered stable, implementations should use `/_matrix/client/unstable/org.matrix.msc4260/users/:userId/report` +instead. Clients should note the [`M_UNRECOGNIZED` behaviour](https://spec.matrix.org/v1.13/client-server-api/#common-error-codes) +for servers which do not support the (un)stable endpoint. + +## Dependencies + +This MSC has no direct dependencies. From 3c7aa8a0b8c38cfd215a76b13f44cc6197af642f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Jan 2025 17:08:24 -0700 Subject: [PATCH 2/4] Add guest access requirements --- proposals/4260-report-user.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/4260-report-user.md b/proposals/4260-report-user.md index 4d8b56a1d69..f93446f7954 100644 --- a/proposals/4260-report-user.md +++ b/proposals/4260-report-user.md @@ -89,6 +89,9 @@ Like `/report/:eventId`, handling of the report is left as a deliberate implemen * Authentication is required for this new endpoint. +* Guest access is not permitted for this new endpoint to reduce spam. A future MSC may change this + out of necessity. MSC4151 and the original report events API are likely similarly affected. + * Servers which opt to hide the existence of a user on the new endpoint should consider implementing a constant time function to avoid unintentionally disclosing that a user exists by processing the request slower. From 8a2b4d96d19e3d9856e9c4e21ec3da76ce5dfed0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Feb 2025 13:18:44 -0700 Subject: [PATCH 3/4] Add examples; fix reason --- proposals/4260-report-user.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/proposals/4260-report-user.md b/proposals/4260-report-user.md index f93446f7954..9f7803d15b0 100644 --- a/proposals/4260-report-user.md +++ b/proposals/4260-report-user.md @@ -18,7 +18,7 @@ a new endpoint is introduced: ``` POST /_matrix/client/v3/users/:userId/report { - "reason": "" + "reason": "" } ``` @@ -36,6 +36,35 @@ successful (`200`) response instead. Like `/report/:eventId`, handling of the report is left as a deliberate implementation detail. +### Examples + +**Note**: Some clients may need to `encodeURIComponent` (or similar) the user ID to use it in a path +parameter. + +``` +POST /_matrix/client/v3/users/@alice:example.org/report +{"reason":"bad person"} + +> 200 OK +> {} +``` + +``` +POST /_matrix/client/v3/users/@alice:example.org/report +{"reason":""} + +> 200 OK +> {} +``` + +``` +POST /_matrix/client/v3/users/@alice:example.org/report +{"reason":""} + +> 404 OK +> {"errcode":"M_NOT_FOUND","error":"User does not exist"} +``` + ## Safety considerations * Server admins may be exposed to harmful content through `reason`. This is an existing issue with From 2e268d63b39310567fb6c034c72fb0b12d1cae04 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Feb 2025 13:20:18 -0700 Subject: [PATCH 4/4] Clarify that reports don't transit federation, but can still be received --- proposals/4260-report-user.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/4260-report-user.md b/proposals/4260-report-user.md index 9f7803d15b0..6246a7c6053 100644 --- a/proposals/4260-report-user.md +++ b/proposals/4260-report-user.md @@ -95,7 +95,10 @@ POST /_matrix/client/v3/users/@alice:example.org/report as they require further thought and consideration - a future MSC may expand (or even deprecate) the report endpoints to support this added information. -* Reports are not federated. This is considered an issue for another MSC, like [MSC3843](https://github.com/matrix-org/matrix-spec-proposals/pull/3843) or [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202). +* While reports against non-local users are permitted, this MSC does not introduce a way for those + reports to transit federation to the target's server. This is considered an issue for another MSC, + like [MSC3843](https://github.com/matrix-org/matrix-spec-proposals/pull/3843) or + [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202). * Whether a user exists on the server is revealed through the new endpoint. Servers have the option to mask this detail by ignoring the report.