changelogs/server_server/newsfragments/2284.clarification

@@ -1 +1 @@
-Specify validation for PDUs passed to and returned from federation membership endpoints.
+Specified input validation for PDUs passed to and returned from federation membership endpoints.

data/api/server-server/invites-v1.yaml

@@ -38,8 +38,8 @@ paths:
         transaction](/server-server-api/#transactions).
 
         Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
-        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        events from a malicious server. The `M_MISSING_PARAM` error code is used to indicate one
-        return `M_INVALID_PARAM` if:
+        or more of the following:
 
         * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.
@@ -47,9 +47,8 @@ paths:
         * The event sender is not a user ID on the origin server.
         * The `state_key` is not a user ID on the receiving server.
 
-        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        The `M_MISSING_PARAM` error code is also used to indicate one or more of the following
-        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        problems in the `invite_room_state` field:
-        SHOULD return `M_INVALID_PARAM` if:
 
         * The `m.room.create` event is missing from `invite_room_state`.
         * One or more entries in `invite_room_state` are not formatted according
@@ -58,6 +57,9 @@ paths:
         * One or more events does not reside in the same room as the invite.
           Note: Some room versions may require calculating the room ID for an
           event rather than relying on the presence of `room_id`.
+
+        Servers MAY apply the `invite_room_state` validation to room versions 1 through 11,
+        and SHOULD apply the validation to all other room versions.
       operationId: sendInviteV1
       security:
         - signedRequest: []
@@ -105,7 +107,8 @@ paths:
                             MUST additionally be formatted according to the room version specification.
 
                             Servers might need to apply validation to the `invite_room_state` depending
-                            on room version. See endpoint description for more information.
+                            on room version. See the `400 M_MISSING_PARAM` error definition for more
+                            information.
 
                             Note that events have a different format depending on the room
                             version - check the [room version specification](/rooms) for
@@ -207,7 +210,7 @@ paths:
               examples:
                 response:
                   value: {
-                    "errcode": "M_INVALID_PARAM",
+                    "errcode": "M_MISSING_PARAM",
                     "error": "Create event not among invite state entries."
                   }
 servers:

data/api/server-server/invites-v2.yaml

@@ -42,8 +42,8 @@ paths:
         transaction](/server-server-api/#transactions).
 
         Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
-        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        events from a malicious server. The `M_MISSING_PARAM` error code is used to indicate one
-        return `M_INVALID_PARAM` if:
+        or more of the following:
 
         * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.
@@ -51,9 +51,8 @@ paths:
         * The event sender is not a user ID on the origin server.
         * The `state_key` is not a user ID on the receiving server.
 
-        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        The `M_MISSING_PARAM` error code is also used to indicate one or more of the following
-        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        problems in the `invite_room_state` field:
-        SHOULD return `M_INVALID_PARAM` if:
 
         * The `m.room.create` event is missing from `invite_room_state`.
         * One or more entries in `invite_room_state` are not formatted according
@@ -62,6 +61,9 @@ paths:
         * One or more events does not reside in the same room as the invite.
           Note: Some room versions may require calculating the room ID for an
           event rather than relying on the presence of `room_id`.
+
+        Servers MAY apply the `invite_room_state` validation to room versions 1 through 11,
+        and SHOULD apply the validation to all other room versions.
       operationId: sendInviteV2
       security:
         - signedRequest: []
@@ -106,7 +108,8 @@ paths:
                     MUST additionally be formatted according to the room version specification.
 
                     Servers might need to apply validation to the `invite_room_state` depending
-                    on room version. See the endpoint description for more information.
+                    on room version. See the `400 M_MISSING_PARAM` error definition for more
+                    information.
 
                     Note that events have a different format depending on the room
                     version - check the [room version specification](/rooms) for
@@ -175,8 +178,8 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
-            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
+            If `M_MISSING_PARAM` is returned and the request is associated with a
-            with a Client-Server API request, the Client-Server API request SHOULD fail
+            Client-Server API request, the Client-Server API request SHOULD fail
             with a 5xx error rather than being passed through.
           content:
             application/json:

data/api/server-server/joins-v1.yaml

@@ -251,7 +251,7 @@ paths:
         fields for a PDU.**
 
         The receiving server MUST apply certain validation before accepting the event.
-        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+        The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
 
         * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.

data/api/server-server/joins-v2.yaml

@@ -40,7 +40,7 @@ paths:
         fields for a PDU.**
 
         The receiving server MUST apply certain validation before accepting the event.
-        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+        The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
 
         * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.
@@ -256,8 +256,8 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
-            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
+            If `M_MISSING_PARAM` is returned and the request is associated with a
-            with a Client-Server API request, the Client-Server API request SHOULD fail
+            Client-Server API request, the Client-Server API request SHOULD fail
             with a 5xx error rather than being passed through.
 
             New in `v1.2`, the following error conditions might happen:

data/api/server-server/knocks.yaml

@@ -217,7 +217,7 @@ paths:
         fields for a PDU.**
 
         The receiving server MUST apply certain validation before accepting the event.
-        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+        The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
 
         * The knock event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.

data/api/server-server/leaving-v1.yaml

@@ -166,7 +166,7 @@ paths:
         fields for a PDU.**
 
         The receiving server MUST apply certain validation before accepting the event.
-        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+        The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
 
         * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.

data/api/server-server/leaving-v2.yaml

@@ -40,7 +40,7 @@ paths:
         fields for a PDU.**
 
         The receiving server MUST apply certain validation before accepting the event.
-        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+        The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
 
         * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
         * The event type is not `m.room.member`.