MSC4260: Reporting users (Client-Server API)

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).

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.

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: