diff --git a/proposals/4277-reporting-harmonization.md b/proposals/4277-reporting-harmonization.md new file mode 100644 index 00000000000..466e0e1da37 --- /dev/null +++ b/proposals/4277-reporting-harmonization.md @@ -0,0 +1,82 @@ +# MSC4277: Harmonizing the reporting endpoints + +Matrix currently has three reporting endpoints: + +- [`/_matrix/client/v3/rooms/{roomId}/report/{eventId}`] ([added] in Matrix + 0.4.0, no MSC known) +- [`/_matrix/client/v3/rooms/{roomId}/report`] ([added][1] in Matrix 1.13 as per + [MSC4151]) +- `/_matrix/client/v3/users/{userId}/report` (to be [added][2] to Matrix as per + [MSC4260]) + +The spec contains a number of subtle differences for these endpoints: + +1. The user reporting endpoint [allows] servers to respond with 200 even if the + user doesn't exist to deny enumerating users. This option is not allowed in + the event and room reporting endpoints. +2. The user and event reporting endpoints allow servers to add a random delay + when generating responses. This is a more sophisticated measure against + enumeration attacks. While the spec doesn't explicit forbid this technique + on the room reporting endpoint it doesn't explicitly mention or recommend it + either. +3. The event reporting endpoint contains a `score` property in the request body + that was made optional by [MSC2414] in 2020. The other two endpoints, when + introduced much later, didn't include this property. Evidently, this is + because `score` hasn't proved useful on event reports. + +These differences seem unnecessary and at least some of them were likely +introduced by accident only. The present proposal, therefore, seeks to align the +three endpoints. + +Note that in addition to the list above, the endpoints also differ in their +handling of the `reason` property in the request body. [MSC2414] made `reason` +optional on the event reporting endpoint. The other two endpoints, however, went +the opposite direction and made `reason` required (while allowing it to be +blank) to limit spam. Resolving this inconsistency is not covered by this +proposal. + +## Proposal + +On all three endpoints: + +1. Servers MAY respond with 200 and no content regardless of whether the + reported subject exists or not to combat enumeration attacks. +2. Servers MAY add a random delay or use constant time functions when + processing responses to combat enumeration attacks. +3. The `score` property is removed. + +All of these changes appear applicable regardless of the reported subject and it +is not clear why the spec should differentiate the endpoints here. + +## Potential issues + +Some Clients may send `score` on event reports today. These clients are not +broken by this proposal because servers that implement it will simply ignore any +`score` property. + +## Alternatives + +None. + +## Security considerations + +Enumeration attacks are likely more severe for users than for rooms or events. +There are still not irrelevant, however. + +## Unstable prefix + +None. + +## Dependencies + +None. + + [`/_matrix/client/v3/rooms/{roomId}/report/{eventId}`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3roomsroomidreporteventid + [added]: https://github.com/matrix-org/matrix-spec-proposals/pull/1264 + [`/_matrix/client/v3/rooms/{roomId}/report`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3roomsroomidreport + [1]: https://github.com/matrix-org/matrix-spec/pull/1938 + [MSC4151]: https://github.com/matrix-org/matrix-spec-proposals/pull/4151 + [2]: https://github.com/matrix-org/matrix-spec/pull/2093 + [MSC4260]: https://github.com/matrix-org/matrix-spec-proposals/pull/4260 + [allows]: https://github.com/matrix-org/matrix-spec-proposals/pull/4260/files#diff-cbb17920e2617e7a20ab0838879675f7aa70e828f0263a3cfa5f4c53913ce5f7R34-R35 + [MSC2414]: https://github.com/matrix-org/matrix-spec-proposals/pull/2414