From 01300dbce7912aee747b1f149f04be85fc0e4589 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 13 Mar 2025 10:58:44 +0100 Subject: [PATCH 1/7] MSC4260: Reporting users (Client-Server API) Signed-off-by: Johannes Marbach --- .../modules/report_content.md | 17 +++++ data/api/client-server/report_content.yaml | 73 +++++++++++++++++-- 2 files changed, 84 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 6f34e938..ec9f101b 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -29,3 +29,20 @@ is in before accepting a report. 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 or invites. + +{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports +based on whether or not the reporting user is joined to any rooms that the +reported user is joined to. This is because users can be exposed to harmful +content without being joined to a room. For instance, through user +directories or invites. + +Clients can infer whether a reported event, room or user exists based on the +404 responses of the reporting endpoints. Homeservers that wish to conceal +this information MAY return 200 responses regardless of the existence of the +reported subject. + +Furthermore, it might be possible for clients to deduce whether a reported +event, room or user exists by timing the response. This is because only a +report for an existing subject will require the homeserver to do further +processing. To combat this, homeserver implementations MAY add a random +delay when generating a response. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 654784ca..d502033f 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -88,12 +88,6 @@ paths: Reports an event as inappropriate to the server, which may then notify the appropriate people. The caller must be joined to the room to report it. - - It might be possible for clients to deduce whether an event exists by - timing the response, as only a report for an event that does exist - 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: reportEvent parameters: - in: path @@ -164,6 +158,73 @@ paths: } tags: - Reporting content + "/users/{userId}/report": + post: + x-addedInMatrixVersion: "1.14" + summary: Report a user as inappropriate. + description: |- + Reports a user as inappropriate to the server, which may then notify + the appropriate people. How such information is delivered is left up to + implementations. The caller is not required to be joined to any rooms + that the reported user is joined to. + + Clients may wish to [ignore](#ignoring-users) users after reporting them. + operationId: reportUser + parameters: + - in: path + name: userId + description: The user being reported. + required: true + example: "@someguy: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 user has been reported successfully. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: |- + The user was not found on the homeserver. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The user was not found." + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Reporting content servers: - url: "{protocol}://{hostname}{basePath}" variables: From e664075ba5866d42ade3b608115586624f21b64b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 13 Mar 2025 11:06:33 +0100 Subject: [PATCH 2/7] Add changelog --- changelogs/client_server/newsfragments/2093.new | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2093.new diff --git a/changelogs/client_server/newsfragments/2093.new b/changelogs/client_server/newsfragments/2093.new new file mode 100644 index 00000000..28c03ffc --- /dev/null +++ b/changelogs/client_server/newsfragments/2093.new @@ -0,0 +1 @@ +Add `POST /_matrix/client/v3/users/{userId}/report` as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). \ No newline at end of file From ebc71218d28e50a28ff7c4bf9bedbad419e656aa Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 13 Mar 2025 17:57:13 +0100 Subject: [PATCH 3/7] Update data/api/client-server/report_content.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> --- data/api/client-server/report_content.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index d502033f..7afe5cec 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -178,6 +178,8 @@ paths: example: "@someguy:example.com" schema: type: string + format: mx-user-id + pattern: "^@" requestBody: content: application/json: From 97bf30b7a3eb092619bef4fc1f98c5abf9306500 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 10:04:50 +0100 Subject: [PATCH 4/7] Move option to consistently respond with 200 to user reporting endpoint --- content/client-server-api/modules/report_content.md | 5 ----- data/api/client-server/report_content.yaml | 8 +++++++- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index ec9f101b..8092c5bc 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -36,11 +36,6 @@ reported user is joined to. This is because users can be exposed to harmful content without being joined to a room. For instance, through user directories or invites. -Clients can infer whether a reported event, room or user exists based on the -404 responses of the reporting endpoints. Homeservers that wish to conceal -this information MAY return 200 responses regardless of the existence of the -reported subject. - Furthermore, it might be possible for clients to deduce whether a reported event, room or user exists by timing the response. This is because only a report for an existing subject will require the homeserver to do further diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 7afe5cec..b21b1de5 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -169,6 +169,10 @@ paths: that the reported user is joined to. Clients may wish to [ignore](#ignoring-users) users after reporting them. + + Clients could infer whether a reported user exists based on the 404 response. + Homeservers that wish to conceal this information MAY return 200 responses + regardless of the existence of the reported user. operationId: reportUser parameters: - in: path @@ -198,7 +202,9 @@ paths: - accessTokenBearer: [] responses: "200": - description: The user has been reported successfully. + description: | + The user has been reported successfully or the server chose + to not disclose whether the users exists. content: application/json: schema: From 31fd5b8cd56754f83da8ca3070552e4c53f106f2 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 10:08:44 +0100 Subject: [PATCH 5/7] Move optional random delay to event and user reporting endpoints --- content/client-server-api/modules/report_content.md | 6 ------ data/api/client-server/report_content.yaml | 10 ++++++++++ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 8092c5bc..ab0e011b 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -35,9 +35,3 @@ based on whether or not the reporting user is joined to any rooms that the reported user is joined to. This is because users can be exposed to harmful content without being joined to a room. For instance, through user directories or invites. - -Furthermore, it might be possible for clients to deduce whether a reported -event, room or user exists by timing the response. This is because only a -report for an existing subject will require the homeserver to do further -processing. To combat this, homeserver implementations MAY add a random -delay when generating a response. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index b21b1de5..3413970d 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -88,6 +88,11 @@ paths: Reports an event as inappropriate to the server, which may then notify the appropriate people. The caller must be joined to the room to report it. + + Furthermore, it might be possible for clients to deduce whether a reported + event exists by timing the response. This is because only a report for an + existing event will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. operationId: reportEvent parameters: - in: path @@ -173,6 +178,11 @@ paths: Clients could infer whether a reported user exists based on the 404 response. Homeservers that wish to conceal this information MAY return 200 responses regardless of the existence of the reported user. + + Furthermore, it might be possible for clients to deduce whether a reported + user exists by timing the response. This is because only a report for an + existing user will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. operationId: reportUser parameters: - in: path From 8bfdf2c2e2bd296776dc29840c526b0ff7e181ae Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 10:16:20 +0100 Subject: [PATCH 6/7] Make reason required for user and room reports --- data/api/client-server/report_content.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 3413970d..b97fc84a 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -45,7 +45,8 @@ paths: properties: reason: type: string - description: The reason the room is being reported. + description: The reason the room is being reported. May be blank. + required: true required: true security: - accessTokenQuery: [] @@ -205,7 +206,8 @@ paths: properties: reason: type: string - description: The reason the room is being reported. + description: The reason the room is being reported. May be blank. + required: true required: true security: - accessTokenQuery: [] From 0c2f84bc1ab43b548350259bb11a1559e9bbc96b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 10:20:40 +0100 Subject: [PATCH 7/7] Fix requiredness syntax --- data/api/client-server/report_content.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index b97fc84a..4934ef3f 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -46,7 +46,8 @@ paths: reason: type: string description: The reason the room is being reported. May be blank. - required: true + required: + - reason required: true security: - accessTokenQuery: [] @@ -207,7 +208,8 @@ paths: reason: type: string description: The reason the room is being reported. May be blank. - required: true + required: + - reason required: true security: - accessTokenQuery: []