Merge 2fca4789ca into a6da9443da

changelogs/client_server/newsfragments/2278.feature

@@ -1 +0,0 @@
-Add administrator endpoints to lock and suspend server-local users 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

@@ -1 +0,0 @@
-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

@@ -1 +0,0 @@
-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

@@ -1 +0,0 @@
-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

@@ -1 +0,0 @@
-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

@@ -2394,12 +2394,9 @@ where feasible. The Matrix-specific actions are:
 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.
+that can be reversed. This specification describes the behaviour of clients
-
+and servers when an account is locked. It deliberately leaves the methods
-{{% added-in v="1.18" %}} To lock or unlock an account, administrators
+for locking and unlocking accounts as a server implementation detail.
-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)
@@ -2448,11 +2445,6 @@ 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, 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:
@@ -2508,6 +2500,9 @@ 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:
-  "/v3/admin/whois/{userId}":
+  "/admin/whois/{userId}":
     get:
       summary: Gets information about a particular user.
       description: |-
@@ -107,391 +107,6 @@ 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:
@@ -503,7 +118,7 @@ servers:
       hostname:
         default: localhost:8008
       basePath:
-        default: /_matrix/client
+        default: /_matrix/client/v3
 components:
   securitySchemes:
     accessTokenQuery:

data/api/client-server/capabilities.yaml

@@ -84,7 +84,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.
@@ -121,7 +121,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:
@@ -133,7 +133,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.
@@ -147,34 +147,6 @@ 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: {