Reorganize client authentication section to separate the legacy API and the new OAuth 2.0 API (#2141)

Since account locking and suspension are authentication API agnostic,
this is a pre-requisite to adding the new OAuth 2.0-based API.

This also splits the endpoints that where all included in the
registration OpenAPI data, to separate them cleanly in the spec, and
avoid having deactivation show before registration.

Signed-off-by: Kévin Commaille <[email protected]>

Author: zecakeh

changelogs/client_server/newsfragments/2141.feature

@@ -0,0 +1 @@
+Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

content/client-server-api/_index.md

@@ -439,7 +439,7 @@ endpoints it supports.
 Most API endpoints require the user to identify themselves by presenting
 previously obtained credentials in the form of an access token.
 An access token is typically obtained via the [Login](#login) or
-[Registration](#account-registration-and-management) processes. Access tokens
+[Registration](#account-registration) processes. Access tokens
 can expire; a new access token can be generated by using a refresh token.
 
 {{% boxes/note %}}
@@ -494,7 +494,7 @@ used to generate a new access token and refresh token, the new access
 and refresh tokens are now bound to the device associated with the
 initial refresh token.
 
-By default, the [Login](#login) and [Registration](#account-registration-and-management)
+By default, the [Login](#login) and [Registration](#account-registration)
 processes auto-generate a new `device_id`. A client is also free to
 generate its own `device_id` or, provided the user remains the same,
 reuse a device: in either case the client should pass the `device_id` in
@@ -560,9 +560,11 @@ specifying the device ID it is already using to the login API.
 with an `M_USER_LOCKED` error code, cannot obtain a new access token until
 the account has been [unlocked](#account-locking).
 
-### User-Interactive Authentication API
+### Legacy API
 
-#### Overview
+#### User-Interactive Authentication API
+
+##### Overview
 
 Some API endpoints require authentication that interacts with the user.
 The homeserver may provide many different ways of authenticating, such
@@ -586,7 +588,7 @@ the flows in order must result in an HTTP 401 response, as defined
 below. When all stages in a flow are complete, authentication is
 complete and the API call succeeds.
 
-#### User-interactive API in the REST API
+##### User-interactive API in the REST API
 
 In the REST API described in this specification, authentication works by
 the client and server exchanging JSON dictionaries. The server indicates
@@ -764,7 +766,7 @@ auth by offering a stage with only the `m.login.dummy` auth type, but they
 must still give a 401 response to requests with no auth data.
 {{% /boxes/note %}}
 
-#### Example
+**Example**
 
 At a high level, the requests made for an API call completing an auth
 flow with three stages will resemble the following diagram:
@@ -806,7 +808,7 @@ flow with three stages will resemble the following diagram:
     |_______________________|
 ```
 
-#### Authentication types
+##### Authentication types
 
 This specification defines the following auth types:
 -   `m.login.password`
@@ -817,7 +819,7 @@ This specification defines the following auth types:
 -   `m.login.dummy`
 -   `m.login.registration_token`
 
-##### Password-based
+###### Password-based
 
 
 | Type               | Description                                                                    |
@@ -876,7 +878,7 @@ explicitly as follows:
 In the case that the homeserver does not know about the supplied 3PID,
 the homeserver must respond with 403 Forbidden.
 
-##### Google ReCaptcha
+###### Google ReCaptcha
 
 | Type                | Description                                          |
 |---------------------|------------------------------------------------------|
@@ -893,7 +895,7 @@ follows:
 }
 ```
 
-##### Single Sign-On
+###### Single Sign-On
 
 | Type          | Description                                                                          |
 |---------------|--------------------------------------------------------------------------------------|
@@ -903,7 +905,7 @@ A client wanting to complete authentication using SSO should use the
 [Fallback](#fallback) mechanism. See [SSO during User-Interactive
 Authentication](#sso-during-user-interactive-authentication) for more information.
 
-##### Email-based (identity / homeserver)
+###### Email-based (identity / homeserver)
 
 | Type                     | Description                                                                                                      |
 |--------------------------|------------------------------------------------------------------------------------------------------------------|
@@ -932,7 +934,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them.
 
-##### Phone number/MSISDN-based (identity / homeserver)
+###### Phone number/MSISDN-based (identity / homeserver)
 
 | Type             | Description                                                                                                    |
 |------------------|----------------------------------------------------------------------------------------------------------------|
@@ -961,7 +963,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them.
 
-##### Dummy Auth
+###### Dummy Auth
 
 | Type             | Description                                                            |
 |------------------|------------------------------------------------------------------------|
@@ -987,7 +989,7 @@ just the type and session, if provided:
 }
 ```
 
-##### Token-authenticated registration
+###### Token-authenticated registration
 
 {{% added-in v="1.2" %}}
 
@@ -1031,7 +1033,7 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
-##### Terms of service at registration
+###### Terms of service at registration
 
 {{% added-in v="1.11" %}}
 
@@ -1154,7 +1156,7 @@ user during registration, if applicable.
 
 {{% definition path="api/client-server/definitions/m.login.terms_params" %}}
 
-#### Fallback
+##### Fallback
 
 Clients cannot be expected to be able to know how to process every
 single login type. If a client does not know how to handle a given login
@@ -1195,7 +1197,7 @@ with just the session ID:
 }
 ```
 
-##### Example
+**Example**
 
 A client webapp might use the following JavaScript to open a popup
 window which will handle unknown login types:
@@ -1251,7 +1253,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo
 }
 ```
 
-#### Identifier types
+##### Identifier types
 
 Some authentication mechanisms use a user identifier object to identify
 a user. The user identifier object has a `type` field to indicate the
@@ -1264,7 +1266,7 @@ This specification defines the following identifier types:
 -   `m.id.thirdparty`
 -   `m.id.phone`
 
-##### Matrix User ID
+###### Matrix User ID
 
 | Type        | Description                                |
 |-------------|--------------------------------------------|
@@ -1281,7 +1283,7 @@ ID.
 }
 ```
 
-##### Third-party ID
+###### Third-party ID
 
 | Type              | Description                                                               |
 |-------------------|---------------------------------------------------------------------------|
@@ -1301,7 +1303,7 @@ ID media.
 }
 ```
 
-##### Phone number
+###### Phone number
 
 | Type         | Description                               |
 |--------------|-------------------------------------------|
@@ -1327,7 +1329,7 @@ The `country` is the two-letter uppercase ISO-3166-1 alpha-2 country
 code that the number in `phone` should be parsed as if it were dialled
 from.
 
-### Login
+#### Login
 
 A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
 
@@ -1399,7 +1401,7 @@ a token for their user ID if supported by the homeserver using
 
 {{% http-api spec="client-server" api="logout" %}}
 
-#### Appservice Login
+##### Appservice Login
 
 {{% added-in v="1.2" %}}
 
@@ -1436,7 +1438,7 @@ If the access token does correspond to an appservice, but the user id does
 not lie within its namespace then the homeserver will respond with an
 errcode of `M_EXCLUSIVE`.
 
-#### Login Fallback
+##### Login Fallback
 
 If a client does not recognize any or all login flows it can use the
 fallback login API:
@@ -1456,11 +1458,13 @@ forwarded to the login endpoint during the login process. For example:
 
     GET /_matrix/static/client/login/?device_id=GHTYAJCE
 
-### Account registration and management
+#### Account registration
 
 {{% http-api spec="client-server" api="registration" %}}
 
-#### Notes on password management
+#### Account management
+
+##### Password management
 
 {{% boxes/warning %}}
 Clients SHOULD enforce that the password provided is suitably complex.
@@ -1469,6 +1473,16 @@ number and a symbol and be at a minimum 8 characters in length. Servers
 MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 {{% /boxes/warning %}}
 
+{{% http-api spec="client-server" api="password_management" %}}
+
+##### Account deactivation
+
+{{% http-api spec="client-server" api="account_deactivation" %}}
+
+### OAuth 2.0 API
+
+### Account moderation
+
 #### Account locking
 
 {{% added-in v="1.12" %}}

data/api/client-server/account_deactivation.yaml

@@ -0,0 +1,141 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Account Deactivation API
+  version: 1.0.0
+paths:
+  /account/deactivate:
+    post:
+      summary: Deactivate a user's account.
+      description: |-
+        Deactivate the user's account, removing all ability for the user to
+        login again.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+
+        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.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: deactivateAccount
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+                id_server:
+                  type: string
+                  description: |-
+                    The identity server to unbind all of the user's 3PIDs from.
+                    If not provided, the homeserver MUST use the `id_server`
+                    that was originally use to bind each identifier. If the
+                    homeserver does not know which `id_server` that was,
+                    it must return an `id_server_unbind_result` of
+                    `no-support`.
+                  example: example.org
+                erase:
+                  x-addedInMatrixVersion: "1.10"
+                  type: boolean
+                  description: |-
+                    Whether the user would like their content to be erased as
+                    much as possible from the server.
+
+                    Erasure means that any users (or servers) which join the
+                    room after the erasure request are served redacted copies of
+                    the events sent by this account. Users which had visibility
+                    on those events prior to the erasure are still able to see
+                    unredacted copies. No redactions are sent and the erasure
+                    request is not shared over federation, so other servers
+                    might still serve unredacted copies.
+
+                    The server should additionally erase any non-event data
+                    associated with the user, such as [account data](/client-server-api/#client-config)
+                    and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
+
+                    Defaults to `false` if not present.
+        required: true
+      responses:
+        "200":
+          description: The account has been deactivated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id_server_unbind_result:
+                    type: string
+                    enum:
+                      - success
+                      - no-support
+                    description: |-
+                      An indicator as to whether or not the homeserver was able to unbind
+                      the user's 3PIDs from the identity server(s). `success` indicates
+                      that all identifiers have been unbound from the identity server while
+                      `no-support` indicates that one or more identifiers failed to unbind
+                      due to the identity server refusing the request or the homeserver
+                      being unable to determine an identity server to unbind from. This
+                      must be `success` if the homeserver has no identifiers to unbind
+                      for the user.
+                    example: success
+                required:
+                  - id_server_unbind_result
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer