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

data/api/client-server/report_content.yaml

@@ -18,10 +18,17 @@ info:
 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
@@ -59,6 +66,9 @@ paths:
         required: true
       security:
         - accessToken: []
+      x-changedInMatrixVersion:
+        1.8: |
+          This endpoint now requires the user to be joined to the room.
       responses:
         "200":
           description: The event has been reported successfully.
@@ -69,6 +79,23 @@ paths:
               examples:
                 response:
                   value: {}
+        "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.
+          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."
+                  }
       tags:
         - Reporting content
 servers: