Merge fe6c97f498 into 7066694571

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2272.feature

@@ -0,0 +1 @@
+Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824).

changelogs/server_server/newsfragments/2284.clarification

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

content/client-server-api/_index.md

@@ -480,6 +480,13 @@ Currently the OAuth 2.0 API doesn't cover all the use cases of the legacy API,
 such as automated applications that cannot use a web browser.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+A compatibility feature, called [OAuth 2.0 aware clients](#oauth-20-aware-clients),
+is available to ease the transition to the OAuth 2.0 API for clients that only
+support the legacy API.
+{{% /boxes/note %}}
+
 ### Authentication API discovery
 
 To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login)
@@ -1612,6 +1619,73 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% http-api spec="client-server" api="account_deactivation" %}}
 
+#### OAuth 2.0 aware clients
+
+{{% added-in v="1.18" %}}
+
+This is a compatibility feature to aide clients in the transition to the OAuth
+2.0 API. It allows clients that only support the legacy API to make some
+less-invasive changes to improve the user experience when talking to a
+homeserver that is using the OAuth 2.0 API without actually having to implement
+the full OAuth 2.0 API.
+
+##### Client behaviour
+
+For a client to be considered fully OAuth 2.0 aware it MUST:
+
+* Support the [`m.login.sso` authentication flow](#client-login-via-sso).
+* Where a `oauth_aware_preferred` value of `true` is present on an `m.login.sso`
+  flow, *only* offer that auth flow to the user.
+* Append `action=login` or `action=register` parameters to the [SSO redirect
+  endpoints](#get_matrixclientv3loginssoredirect). The client might determine
+  the value to use based on whether the user clicked a "Login" or "Register"
+  button.
+* Check and honour the [`m.3pid_changes` capability](#m3pid_changes-capability)
+  so that the user is not offered the ability to add or remove 3PIDs if the
+  homeserver says the capability is not available.
+* Determine if the homeserver is using the OAuth 2.0 API by using
+  [server metadata discovery](#get_matrixclientv1auth_metadata) from the OAuth
+  2.0 API.
+* If a homeserver is using the OAuth 2.0 API as discovered in the previous step
+  then the client MUST redirect users to manage their account at the [account
+  management URL](#oauth-20-account-management), if available, instead of
+  providing a native UI using the legacy API endpoints.
+  
+  * If the user wishes to deactivate their account then the client MUST refer
+    them to the account management URL.
+  * If the user wishes to sign out a device other than its own then the client
+    MUST deep link the user to the account management URL by adding the
+    `action=org.matrix.device_delete` and `device_id=<device_id>` parameters so
+    that the web UI knows that the user wishes to sign out a device and which
+    one it is.
+
+Optionally, an OAuth 2.0 aware client MAY:
+
+* Label the SSO button as "Continue" rather than "SSO" when
+  `oauth_aware_preferred` is `true`. This is because after redirect the server
+  may then offer a password and/or further upstream IdPs.
+* Pass other [account management URL parameters](#account-management-url-parameters)
+  for context when linking to the account web UI.
+
+##### Server behaviour
+
+For a homeserver to provide support for OAuth 2.0 aware clients it MUST:
+
+* Support the [OAuth 2.0 API](#oauth-20-api).
+* Provide an implementation of the [`m.login.sso` authentication flow](#client-login-via-sso)
+  from the legacy API.
+* If password authentication was previously enabled on the homeserver then
+  provide an implementation of the [`m.login.password` authentication flow](#legacy-login)
+  from the legacy API.
+* Indicate that the `m.login.sso` flow is preferred by setting
+  `oauth_aware_preferred` to `true`.
+* Support a value for the `action` param on the [SSO redirect endpoints](#get_matrixclientv3loginssoredirect).
+
+Additionally, the homeserver SHOULD:
+
+* Advertise the [account management URL](#oauth-20-account-management) in the
+  [server metadata](#get_matrixclientv1auth_metadata).
+
 ### OAuth 2.0 API
 
 {{% added-in v="1.15" %}}

data/api/client-server/account_deactivation.yaml

@@ -35,6 +35,14 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, and MAY use the `action=org.matrix.account_deactivate`
+        parameter.
+        {{% /boxes/warning %}}
       security:
         - {}
         - accessTokenQuery: []

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

@@ -86,5 +86,13 @@ properties:
             brand usage as intended by the server.
           example: "github"
       required: ['id', 'name']
+  oauth_aware_preferred:
+    type: boolean
+    x-addedInMatrixVersion: "1.18"
+    description: |
+      Whether the `m.login.sso` flow is preferred over other flows. If this is `true`,
+      [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST only
+      offer this flow to the user.
+    example: true
 
 required: ['type']

data/api/client-server/device_management.yaml

@@ -170,6 +170,13 @@ paths:
         When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
         {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters.
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -232,6 +239,13 @@ paths:
         When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
         {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available.
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/api/client-server/registration.yaml

@@ -72,6 +72,15 @@ paths:
         `inhibit_login` parameter is not set to `true`, the server MUST return a
         400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
         {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server offers the [`m.login.sso`
+        authentication flow](/client-server-api/#client-login-via-sso) with
+        `oauth_aware_preferred` set to `true`. Instead they MUST use the
+        [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
+        endpoint, adding the `action=register` parameter.
+        {{% /boxes/warning %}}
       operationId: register
       parameters:
         - in: query

data/api/client-server/sso_login_redirect.yaml

@@ -37,6 +37,22 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.
@@ -75,6 +91,22 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.

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
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
-            Client-Server API request, the Client-Server API request SHOULD fail
+            is associated with a Client-Server API request, the Client-Server API
-            with a 5xx error rather than being passed through.
+            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
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
-            Client-Server API request, the Client-Server API request SHOULD fail
+            is associated with a Client-Server API request, the Client-Server API
-            with a 5xx error rather than being passed through.
+            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: