Merge f95dcfb0e7 into 2f6867348f

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

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
+that can be reversed.
-and servers when an account is locked. It deliberately leaves the methods
+
-for locking and unlocking accounts as a server implementation detail.
+{{% 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

@@ -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: {