From d134ec5e2a75bf99ff129baf8556828c3f30de33 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 9 May 2023 15:03:44 +0100 Subject: [PATCH 01/10] Add MSC2249 support --- data/api/client-server/report_content.yaml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 7f8b3425c..3b324a68c 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -29,11 +29,14 @@ securityDefinitions: paths: "/rooms/{roomId}/report/{eventId}": post: - summary: Reports an event as inappropriate. + summary: Reports an event as inappropriate. You must have permission to + retrieve this event e.g. by being a member in the room for this event. description: |- Reports an event as inappropriate to the server, which may then notify the appropriate people. operationId: reportContent + tags: + - Reporting content parameters: - in: path type: string @@ -74,5 +77,13 @@ paths: type: object examples: application/json: {} - tags: - - Reporting content + 404: + description: |- + The event was not found or you do not have permission to read this event. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The event was not found or you do not have permission to read this event." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" From b5b4cdb00f9db40c23113f08d145da378c324420 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 9 May 2023 15:05:32 +0100 Subject: [PATCH 02/10] changelog --- changelogs/client_server/newsfragments/1517.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1517.feature diff --git a/changelogs/client_server/newsfragments/1517.feature b/changelogs/client_server/newsfragments/1517.feature new file mode 100644 index 000000000..138a8406d --- /dev/null +++ b/changelogs/client_server/newsfragments/1517.feature @@ -0,0 +1 @@ +Event reporters must be able to view the event in order to report it. [MSC2249](https://github.com/matrix-org/matrix-spec-proposals/pull/2249). From aaac53ac91e2312628c55e9cfb151592a115a006 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 9 May 2023 16:13:37 +0100 Subject: [PATCH 03/10] Add a line on verification --- content/client-server-api/modules/report_content.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 02ef002a7..e705e107d 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -18,3 +18,6 @@ Servers are free to handle the reported content however they desire. This may be a dedicated room to alert server administrators to the reported content or some other mechanism for notifying the appropriate people. + +The server MUST verify that the user has permission to view the event +before accepting a report. From 8f4d9c9784aea94ce6e652b15ad6b5adeefe6f88 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 23 May 2023 15:48:37 +0000 Subject: [PATCH 04/10] Changes based on review feedback --- .../client-server-api/modules/report_content.md | 5 +++-- data/api/client-server/report_content.yaml | 16 ++++++++++++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index e705e107d..a8fe6900d 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -19,5 +19,6 @@ This may be a dedicated room to alert server administrators to the reported content or some other mechanism for notifying the appropriate people. -The server MUST verify that the user has permission to view the event -before accepting a report. +{{< changed-in v="1.7" >}} The server MUST verify that the user +reporting the event is currently joined to the room the event is +in before accepting a report. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 3b324a68c..6e3fdd6c5 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -29,11 +29,17 @@ securityDefinitions: paths: "/rooms/{roomId}/report/{eventId}": post: - summary: Reports an event as inappropriate. You must have permission to - retrieve this event e.g. by being a member in the room for this event. + summary: Reports an event as inappropriate. You must be joined to the room in order + to report an event. description: |- Reports an event as inappropriate to the server, which may then notify the appropriate people. + + It may 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 may add + a random delay when generating a response. operationId: reportContent tags: - Reporting content @@ -70,6 +76,9 @@ paths: description: The reason the content is being reported. May be blank. security: - accessToken: [] + x-changedInMatrixVersion: + 1.7: | + This endpoint now requires the user to be joined to the room. responses: 200: description: The event has been reported successfully. @@ -80,6 +89,9 @@ paths: 404: description: |- The event was not found or you do not have permission to read this event. + + Homeserver implementations may additionally return this error if the + reported event has been redacted. examples: application/json: { "errcode": "M_NOT_FOUND", From 6189837fafea09f60fcb2683898b999072d46dd0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 4 Aug 2023 10:13:54 +0100 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Travis Ralston --- .../client_server/newsfragments/1517.feature | 2 +- data/api/client-server/report_content.yaml | 24 +++++++++++++------ 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/changelogs/client_server/newsfragments/1517.feature b/changelogs/client_server/newsfragments/1517.feature index 138a8406d..0d49f4eb6 100644 --- a/changelogs/client_server/newsfragments/1517.feature +++ b/changelogs/client_server/newsfragments/1517.feature @@ -1 +1 @@ -Event reporters must be able to view the event in order to report it. [MSC2249](https://github.com/matrix-org/matrix-spec-proposals/pull/2249). +Require callers to be joined to the room to report its events, as per [MSC2249](https://github.com/matrix-org/matrix-spec-proposals/pull/2249). diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 6e3fdd6c5..738b2f39f 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -29,16 +29,22 @@ securityDefinitions: paths: "/rooms/{roomId}/report/{eventId}": post: - summary: Reports an event as inappropriate. You must be joined to the room in order - to report an event. + summary: Report an event in a joined room as inappropriate. description: |- Reports an event as inappropriate to the server, which may then notify - the appropriate people. + the appropriate people. The caller must be joined to the room to report + it. - It may be possible for clients to deduce whether an event exists by + It can 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 may add + the room. To combat this, homeserver implementations are encouraged + to add a random delay when generating the response. + + 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: reportContent tags: @@ -88,14 +94,18 @@ paths: application/json: {} 404: description: |- - The event was not found or you do not have permission to read this event. + The event was not found or you are not joined to the room where the + event resides. + + Homeserver implementations can additionally return this error if the + reported event has been redacted. Homeserver implementations may additionally return this error if the reported event has been redacted. examples: application/json: { "errcode": "M_NOT_FOUND", - "error": "The event was not found or you do not have permission to read this event." + "error": "The event was not found or you are not joined to the room." } schema: $ref: "../client-server/definitions/errors/error.yaml" From 8776d9b1bc693da48394d9d0821acd1e281aad99 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 4 Aug 2023 10:15:55 +0100 Subject: [PATCH 06/10] move tags field to the bottom of report_content.yaml --- data/api/client-server/report_content.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 738b2f39f..41ac3669b 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -47,8 +47,6 @@ paths: the room. To combat this, homeserver implementations should add a random delay when generating a response. operationId: reportContent - tags: - - Reporting content parameters: - in: path type: string @@ -109,3 +107,5 @@ paths: } schema: $ref: "../client-server/definitions/errors/error.yaml" + tags: + - Reporting content From 2fb7ce82d20d4213e82d64353ea39bebc5cfa0f2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 4 Aug 2023 10:18:58 +0100 Subject: [PATCH 07/10] fix duplicated content now how did that happen --- data/api/client-server/report_content.yaml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 41ac3669b..ee7caa63c 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -35,12 +35,6 @@ paths: the appropriate people. The caller must be joined to the room to report it. - It can 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 are encouraged - to add a random delay when generating the response. - 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 @@ -97,9 +91,6 @@ paths: Homeserver implementations can additionally return this error if the reported event has been redacted. - - Homeserver implementations may additionally return this error if the - reported event has been redacted. examples: application/json: { "errcode": "M_NOT_FOUND", From 7cc6d6e3598a3e59264ae737d6f9337935264d9a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 4 Aug 2023 10:25:52 +0100 Subject: [PATCH 08/10] fix up the 404 response schema it wasn't displaying correctly in the rendered spec otherwise --- data/api/client-server/report_content.yaml | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 21b201c91..535264606 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -79,18 +79,23 @@ paths: examples: response: value: {} - 404: + "404": description: |- The event was not found or you are not joined to the room where the event resides. Homeserver implementations can additionally return this error if the reported event has been redacted. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The event was not found or you are not joined to the room." - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The event was not found or you are not joined to the room." + } schema: $ref: "../client-server/definitions/errors/error.yaml" tags: From 78c9a5d9cc6e5ee4bb578eca510f71174647093c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 4 Aug 2023 10:26:54 +0100 Subject: [PATCH 09/10] remove erroneous schema reference --- data/api/client-server/report_content.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 535264606..2e36704f4 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -96,8 +96,6 @@ paths: "errcode": "M_NOT_FOUND", "error": "The event was not found or you are not joined to the room." } - schema: - $ref: "../client-server/definitions/errors/error.yaml" tags: - Reporting content servers: From 8958f8a7848a991c665b0695c5fd1ecb193d3f62 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 9 Aug 2023 00:38:02 +0100 Subject: [PATCH 10/10] 1.7 -> 1.8 Co-authored-by: Travis Ralston --- content/client-server-api/modules/report_content.md | 2 +- data/api/client-server/report_content.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index a8fe6900d..c482fbbc3 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -19,6 +19,6 @@ 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.7" >}} The server MUST verify that the user +{{< 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. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 2e36704f4..9241705ae 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -67,7 +67,7 @@ paths: security: - accessToken: [] x-changedInMatrixVersion: - 1.7: | + 1.8: | This endpoint now requires the user to be joined to the room. responses: "200":