From fb719355d3c5fab58fc2d2c7c81a814372c8a3c4 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 26 Aug 2024 09:31:26 +0200 Subject: [PATCH 1/9] MSC4151: Reporting rooms Signed-off-by: Johannes Marbach --- .../modules/report_content.md | 19 ++++-- data/api/client-server/report_content.yaml | 67 ++++++++++++++++++- 2 files changed, 78 insertions(+), 8 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index c482fbbc3..5a2be7bbf 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -5,9 +5,6 @@ Users may encounter content which they find inappropriate and should be able to report it to the server administrators or room moderators for review. This module defines a way for users to report content. -Content is reported based upon a negative score, where -100 is "most -offensive" and 0 is "inoffensive". - #### Client behaviour {{% http-api spec="client-server" api="report_content" %}} @@ -19,6 +16,16 @@ This may be a dedicated room to alert server administrators to the reported content or some other mechanism for notifying the appropriate people. -{{< changed-in v="1.8" >}} The server MUST verify that the user -reporting the event is currently joined to the room the event is -in before accepting a report. +Particularly during waves of a harmful content, users may report whole +rooms instead of individual events. Server administrators and safety teams +should, therefore, be cautious not to shut down rooms that might otherwise +be legitimate. + +{{< changed-in v="1.8" >}} When processing event reports, servers MUST +verify that the reporting user is currently joined to the room the event +is in before accepting a report. + +Contrarily, servers MUST NOT restrict room reports based on whether or not the +reporting user is joined to the room. This is because users can be exposed +to harmful content without being joined to a room, for instance, through +room directories. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index f30e189d9..ebc04ffeb 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -16,6 +16,69 @@ info: title: Matrix Client-Server Report Content API version: 1.0.0 paths: + "/rooms/{roomId}/report": + post: + summary: Report a room as inappropriate. + description: |- + Reports a room as inappropriate to the server, which may then notify + the appropriate people. The caller is not required to be joined to the + room to report it. + operationId: reportRoom + parameters: + - in: path + name: roomId + description: The room being reported. + required: true + example: "!637q39766251:example.com" + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "this makes me sad" + } + properties: + reason: + type: string + description: The reason the room is being reported. + required: true + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: The room has been reported successfully. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: |- + The room was not found on the homeserver. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The room was not found." + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Reporting content "/rooms/{roomId}/report/{eventId}": post: summary: Report an event in a joined room as inappropriate. @@ -29,7 +92,7 @@ paths: will require the homeserver to check whether a user is joined to the room. To combat this, homeserver implementations should add a random delay when generating a response. - operationId: reportContent + operationId: reportEvent parameters: - in: path name: roomId @@ -62,7 +125,7 @@ paths: and 0 is inoffensive. reason: type: string - description: The reason the content is being reported. May be blank. + description: The reason the content is being reported. required: true security: - accessTokenQuery: [] From ab88044235770e11eb9b333ad5d5e138345e4258 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 26 Aug 2024 09:38:23 +0200 Subject: [PATCH 2/9] Add changelog --- changelogs/client_server/newsfragments/1938.clarification | 1 + changelogs/client_server/newsfragments/1938.new | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1938.clarification create mode 100644 changelogs/client_server/newsfragments/1938.new diff --git a/changelogs/client_server/newsfragments/1938.clarification b/changelogs/client_server/newsfragments/1938.clarification new file mode 100644 index 000000000..42784ef69 --- /dev/null +++ b/changelogs/client_server/newsfragments/1938.clarification @@ -0,0 +1 @@ +The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank as per MSC2414. diff --git a/changelogs/client_server/newsfragments/1938.new b/changelogs/client_server/newsfragments/1938.new new file mode 100644 index 000000000..ec436d7b0 --- /dev/null +++ b/changelogs/client_server/newsfragments/1938.new @@ -0,0 +1 @@ +Add `POST /_matrix/client/v3/rooms/{roomId}/report` as per MSC4151. From 9d63f315d7d811cd0ed8904175c8e316d205bc0d Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 27 Aug 2024 19:35:33 +0200 Subject: [PATCH 3/9] Update changelogs/client_server/newsfragments/1938.clarification --- changelogs/client_server/newsfragments/1938.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1938.clarification b/changelogs/client_server/newsfragments/1938.clarification index 42784ef69..4bfd2a3cf 100644 --- a/changelogs/client_server/newsfragments/1938.clarification +++ b/changelogs/client_server/newsfragments/1938.clarification @@ -1 +1 @@ -The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank as per MSC2414. +The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414). From 1cf5104dcb9ef0ed150d47217c0ca2a5abca2c16 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 27 Aug 2024 19:36:44 +0200 Subject: [PATCH 4/9] Update changelogs/client_server/newsfragments/1938.new --- changelogs/client_server/newsfragments/1938.new | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1938.new b/changelogs/client_server/newsfragments/1938.new index ec436d7b0..718ee7550 100644 --- a/changelogs/client_server/newsfragments/1938.new +++ b/changelogs/client_server/newsfragments/1938.new @@ -1 +1 @@ -Add `POST /_matrix/client/v3/rooms/{roomId}/report` as per MSC4151. +Add `POST /_matrix/client/v3/rooms/{roomId}/report` as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151). From 3aad778cabfb85049af310a425e37c70fdffa281 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 9 Sep 2024 08:13:02 +0200 Subject: [PATCH 5/9] Add x-addedInMatrixVersion property --- data/api/client-server/report_content.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index ebc04ffeb..22131ef9c 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -18,6 +18,7 @@ info: paths: "/rooms/{roomId}/report": post: + x-addedInMatrixVersion: "1.12" summary: Report a room as inappropriate. description: |- Reports a room as inappropriate to the server, which may then notify From 414001a0441d92ae33f8d283f6f3ce016d4a01da Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 9 Sep 2024 08:15:52 +0200 Subject: [PATCH 6/9] Add added-in shortcode --- content/client-server-api/modules/report_content.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 5a2be7bbf..6489d8e5a 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -25,7 +25,7 @@ be legitimate. verify that the reporting user is currently joined to the room the event is in before accepting a report. -Contrarily, servers MUST NOT restrict room reports based on whether or not the -reporting user is joined to the room. This is because users can be exposed -to harmful content without being joined to a room, for instance, through -room directories. +{{< added-in v="1.12" >}} Contrarily, servers MUST NOT restrict room reports +based on whether or not the reporting user is joined to the room. This is +because users can be exposed to harmful content without being joined to a +room, for instance, through room directories. From 8c8c37db8329743d42ba687e29b7cdef57666370 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:18:25 +0200 Subject: [PATCH 7/9] Update content/client-server-api/modules/report_content.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- content/client-server-api/modules/report_content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 6489d8e5a..e74e01924 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -16,7 +16,7 @@ This may be a dedicated room to alert server administrators to the reported content or some other mechanism for notifying the appropriate people. -Particularly during waves of a harmful content, users may report whole +Particularly during waves of harmful content, users may report whole rooms instead of individual events. Server administrators and safety teams should, therefore, be cautious not to shut down rooms that might otherwise be legitimate. From 00d4e6d78c6f0b336a8bb0f0a09cf771de1e22c9 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:19:07 +0200 Subject: [PATCH 8/9] Update content/client-server-api/modules/report_content.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- content/client-server-api/modules/report_content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index e74e01924..92288eee5 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -28,4 +28,4 @@ is in before accepting a report. {{< added-in v="1.12" >}} Contrarily, servers MUST NOT restrict room reports based on whether or not the reporting user is joined to the room. This is because users can be exposed to harmful content without being joined to a -room, for instance, through room directories. +room. For instance, through room directories or invites. From 883e9e3f8cc813f7884677d1b0d133251bd6b5f3 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:20:11 +0200 Subject: [PATCH 9/9] Update data/api/client-server/report_content.yaml Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- data/api/client-server/report_content.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 22131ef9c..b83540904 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -22,8 +22,9 @@ paths: summary: Report a room as inappropriate. description: |- Reports a room as inappropriate to the server, which may then notify - the appropriate people. The caller is not required to be joined to the - room to report it. + the appropriate people. How such information is delivered is left up to + implementations. The caller is not required to be joined to the room to + report it. operationId: reportRoom parameters: - in: path