Merge fe6c97f498 into 2a3841347e

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request
+and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`,
+as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/identity_service/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken`
+and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT`
+error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/server_server/newsfragments/2284.clarification

@@ -0,0 +1 @@
+Specified input validation for PDUs passed to federation membership endpoints.

data/api/client-server/definitions/request_token_response.yaml

@@ -24,16 +24,23 @@ properties:
   submit_url:
     type: string
     format: uri
+    x-changedInMatrixVersion:
+      "1.18": |-
+        The URL has the same request and response parameters and error codes as
+        the Identity Service API's endpoint.
     description: |-
       An optional field containing a URL where the client must submit the
-      validation token to, with identical parameters to the Identity Service
-      API's `POST /validate/email/submitToken` endpoint (without the requirement
-      for an access token). The homeserver must send this token to the user (if
-      applicable), who should then be prompted to provide it to the client.
+      validation token, with identical request and response parameters and error
+      codes to the Identity Service API's
+      [`POST /validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)
+      and [`POST /validate/msisdn/submitToken`](/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)
+      endpoints (without the requirement for an access token). The homeserver
+      must send this token to the user (if applicable), who should then be
+      prompted to provide it to the client.
 
       If this field is not present, the client can assume that verification
       will happen without the client's involvement provided the homeserver
-      advertises this specification version in the `/versions` response
-      (ie: r0.5.0).
+      advertises a sufficiently recent version in the [`GET /versions`](/client-server-api/#get_matrixclientversions)
+      response (ie: r0.5.0).
     example: "https://example.org/path/to/submitToken"
 required: ['sid']

data/api/identity/v2_email_associations.yaml

@@ -153,6 +153,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example

data/api/identity/v2_phone_associations.yaml

@@ -155,6 +155,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example

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

@@ -172,6 +172,17 @@ paths:
                   }
         "400":
           description: |-
+            The `M_INVALID_PARAM` error code is used to indicate one 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`.
+            * The `membership` field inside the event content is not `invite`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not a user ID on the receiving server.
+
+            Servers MUST apply the validation above to the invite event before
+            signing it regardless of room version.
+
             The `M_MISSING_PARAM` error code is used to indicate one or more of
             the following:
 
@@ -186,9 +197,9 @@ paths:
             Servers MAY apply the validation above to room versions 1 through 11,
             and SHOULD apply the validation above to all other room versions.
 
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
+            is associated with a Client-Server API request, the Client-Server API
+            request SHOULD fail with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:

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

@@ -154,6 +154,17 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            The `M_INVALID_PARAM` error code is used to indicate one 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`.
+            * The `membership` field inside the event content is not `invite`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not a user ID on the receiving server.
+
+            Servers MUST apply the validation above to the invite event before
+            signing it regardless of room version.
+
             The `M_MISSING_PARAM` error code is used to indicate one or more of
             the following:
 
@@ -168,9 +179,9 @@ paths:
             Servers MAY apply the validation above to room versions 1 through 11,
             and SHOULD apply the validation above to all other room versions.
 
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
+            is associated with a Client-Server API request, the Client-Server API
+            request SHOULD fail with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:

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

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the join event will be for.
+          description: The user ID the join event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -388,6 +388,43 @@ paths:
                       }
                     }
                   ]
+        "400":
+          description: |-
+            The request is invalid in some way.
+
+            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`.
+            * The `membership` field inside the event content is not `join`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the join event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a join event."
+                  }
+        "403":
+          description: |-
+            The room that the joining server is attempting to join does not permit the user
+            to join.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room"
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

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

@@ -247,6 +247,16 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            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`.
+            * The `membership` field inside the event content is not `join`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the join event.
+
             New in `v1.2`, the following error conditions might happen:
 
             If the room is [restricted](/client-server-api/#restricted-rooms)

data/api/server-server/knocks.yaml

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the knock event will be for.
+          description: The user ID the knock event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -330,6 +330,27 @@ paths:
                       "$ref": "./examples/invite_or_knock_state.json"
                     }
                   }
+        "400":
+          description: |-
+            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`.
+            * The `membership` field inside the event content is not `knock`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the knock event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a knock event."
+                  }
         "403":
           description: |-
             The knocking server or user is not permitted to knock on the room, such as when the

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

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the leave event will be for.
+          description: The user ID the leave event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -249,6 +249,27 @@ paths:
                     200,
                     {}
                   ]
+        "400":
+          description: |-
+            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`.
+            * The `membership` field inside the event content is not `leave`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the leave event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

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

@@ -134,6 +134,27 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: |-
+            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`.
+            * The `membership` field inside the event content is not `leave`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the leave event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables: