Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-23 17:48:37 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge f95dcfb0e7 into 2f6867348f

Browse source
This commit is contained in:
Kévin Commaille 2025-12-19 16:07:49 +00:00 committed by GitHub
parent 2f6867348f f95dcfb0e7
commit c27a40748c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 434 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2278.feature Normal file
View file

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

1
changelogs/client_server/newsfragments/2278.new.1 Normal file
View file

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

1
changelogs/client_server/newsfragments/2278.new.2 Normal file
View file

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

1
changelogs/client_server/newsfragments/2278.new.3 Normal file
View file

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

1
changelogs/client_server/newsfragments/2278.new.4 Normal file
View file

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

17
content/client-server-api/_index.md
View file

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

389
data/api/client-server/admin.yaml
View file

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

34
data/api/client-server/capabilities.yaml
View file

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