Add spec for MSC2449: Require users to have visibility on an event when submitting reports

changelogs/client_server/newsfragments/1517.feature

@@ -0,0 +1 @@
+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).

content/client-server-api/modules/report_content.md

@@ -18,3 +18,7 @@ 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.
+
+{{< 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.

data/api/client-server/report_content.yaml

@@ -29,10 +29,17 @@ securityDefinitions:
 paths:
   "/rooms/{roomId}/report/{eventId}":
     post:
-      summary: Reports an event as inappropriate.
+      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 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
       parameters:
         - in: path
@@ -67,12 +74,29 @@ 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.
           schema:
             type: object
           examples:
             application/json: {}
+        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."
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
       tags:
         - Reporting content