Merge f95dcfb0e7 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/client_server/newsfragments/2278.feature

@@ -0,0 +1 @@
+Add endpoints to lock and suspend server-local users for administrations and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.1

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.2

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.3

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.4

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

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

content/client-server-api/_index.md

@@ -2280,9 +2280,12 @@ The server SHOULD return one of the following responses:
 Server administrators may apply locks to prevent users from usefully
 using their accounts, for instance, due to safety or security concerns.
 In contrast to account deactivation, locking is a non-destructive action
-that can be reversed. This specification describes the behaviour of clients
-and servers when an account is locked. It deliberately leaves the methods
-for locking and unlocking accounts as a server implementation detail.
+that can be reversed.
+
+{{% added-in v="1.18" %}} To lock or unlock an account, the administrators
+SHOULD use the [`PUT /admin/lock/{userId}`](#put_matrixclientv1adminlockuserid)
+endpoint. They MAY also use [`GET /admin/lock/{userId}`](#get_matrixclientv1adminlockuserid)
+to check whether a user's account is locked.
 
 When an account is locked, servers MUST return a `401 Unauthorized` error
 response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout)
@@ -2331,6 +2334,11 @@ from that account. The effect is similar to [locking](#account-locking), though
 without risk of the client losing state from a logout. Suspensions are reversible,
 like locks and unlike deactivations.
 
+{{% added-in v="1.18" %}} To suspend or unsuspend an account, the administrators
+SHOULD use the [`PUT /admin/suspend/{userId}`](#put_matrixclientv1adminsuspenduserid)
+endpoint. They MAY also use [`GET /admin/suspend/{userId}`](#get_matrixclientv1adminsuspenduserid)
+to check whether a user's account is suspended.
+
 The actions a user can perform while suspended is deliberately left as an
 implementation detail. Servers SHOULD permit the user to perform at least the
 following, however:
@@ -2386,9 +2394,6 @@ Content-Type: application/json
 }
 ```
 
-APIs for initiating suspension or unsuspension are not included in this version
-of the specification, and left as an implementation detail.
-
 ### Adding Account Administrative Contact Information
 
 A homeserver may keep some contact information for administrative use.

data/api/client-server/admin.yaml

@@ -16,7 +16,7 @@ info:
   title: Matrix Client-Server Administration API
   version: 1.0.0
 paths:
-  "/admin/whois/{userId}":
+  "/v3/admin/whois/{userId}":
     get:
       summary: Gets information about a particular user.
       description: |-
@@ -107,6 +107,391 @@ paths:
                   }
       tags:
         - Server administration
+  "/v1/admin/suspend/{userId}":
+    get:
+      summary: Gets information about the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the suspended status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                suspended:
+                  type: boolean
+                  description: Whether to suspend the target account.
+                  example: true
+              required:
+                - suspended
+            examples:
+                request:
+                  value: {
+                    "suspended": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to suspend their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+  "/v1/admin/lock/{userId}":
+    get:
+      summary: Gets information about the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the locked status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                locked:
+                  type: boolean
+                  description: Whether to lock the target account.
+                  example: true
+              required:
+                - locked
+            examples:
+                request:
+                  value: {
+                    "locked": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                    example: true
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to lock their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:
@@ -118,7 +503,7 @@ servers:
       hostname:
         default: localhost:8008
       basePath:
-        default: /_matrix/client/v3
+        default: /_matrix/client
 components:
   securitySchemes:
     accessTokenQuery:

data/api/client-server/capabilities.yaml

@@ -78,7 +78,7 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
                           Refer to `m.profile_fields` for extended profile management.
-                          
+
                           For backwards compatibility, servers that directly or indirectly include the
                           `displayname` profile field in the `m.profile_fields` capability MUST also
                           set this capability accordingly.
@@ -115,7 +115,7 @@ paths:
                             description: |
                               If present, a list of profile fields that clients are allowed to create, modify or delete,
                               provided `enabled` is `true`; no other profile fields may be changed.
-                              
+
                               If absent, clients may set all profile fields except those forbidden by the `disallowed`
                               list, where present.
                             items:
@@ -127,7 +127,7 @@ paths:
                             type: array
                             description:  |
                               This property has no meaning if `allowed` is also specified.
-                              
+
                               Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
                               Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
                               included in this list.
@@ -141,6 +141,34 @@ paths:
                             example: true
                         required:
                           - enabled
+                      m.account_moderation:
+                        x-addedInMatrixVersion: "1.18"
+                        type: object
+                        title: AccountModerationCapability
+                        description: |-
+                          Capability to indicate if the user can perform account moderation actions
+                          via [server administration](/client-server-api/#server-administration)
+                          endpoints.
+
+                          This property should be omitted altogether if `suspend` and `lock` would
+                          be `false`.
+                        properties:
+                          suspend:
+                            type: boolean
+                            description: |-
+                              `true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](/client-server-api/#put_matrixclientv1adminsuspenduserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
+                          lock:
+                            type: boolean
+                            description: |-
+                              `true` if the user can lock a user via [`PUT /admin/lock/{userId}`](/client-server-api/#put_matrixclientv1adminlockuserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
               examples:
                 response:
                   value: {

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