diff --git a/changelogs/client_server/newsfragments/2014.feature b/changelogs/client_server/newsfragments/2014.feature new file mode 100644 index 000000000..0671f14d3 --- /dev/null +++ b/changelogs/client_server/newsfragments/2014.feature @@ -0,0 +1 @@ +Add new `M_USER_SUSPENDED` error code behaviour, as per [MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index bfcbd031d..63cc5c59b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -29,7 +29,7 @@ JSON object. Clients should supply a `Content-Type` header of The exceptions are: -- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and +- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), both of which take the uploaded media as the request body. - [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and @@ -103,6 +103,10 @@ No access token was specified for the request. `M_USER_LOCKED` The account has been [locked](#account-locking) and cannot be used at this time. +`M_USER_SUSPENDED` +The account has been [suspended](#account-suspension) and can only be used for +limited actions at this time. + `M_BAD_JSON` Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys. @@ -1471,7 +1475,7 @@ Content-Type: application/json ``` Servers SHOULD NOT invalidate access tokens on locked accounts unless the -client requests a logout (using the above endpoints). This ensures that +client requests a logout (using the above endpoints). This ensures that users can retain their sessions without having to log back in if the account becomes unlocked. @@ -1485,6 +1489,73 @@ and other APIs to detect when the lock has been lifted. To enable users to appeal to a lock clients MAY use [server contact discovery](#getwell-knownmatrixsupport). +#### Account suspension + +{{% added-in v="1.13" %}} + +Server administrators MAY suspend a user's account to prevent further activity +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. + +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: + +* Log in and create additional sessions (which are also suspended). +* See and receive messages, particularly through [`/sync`](#get_matrixclientv3sync) + and [`/messages`](#get_matrixclientv3roomsroomidmessages). +* [Verify other devices](#device-verification) and write associated + [cross-signing data](#cross-signing). +* [Populate their key backup](#server-side-key-backups). +* [Leave rooms and reject invites](#post_matrixclientv3roomsroomidleave). +* [Redact](#redactions) their own events. +* [Log out](#post_matrixclientv3logout) or [delete](#delete_matrixclientv3devicesdeviceid) + any device of theirs, including the current session. +* [Deactivate](#post_matrixclientv3accountdeactivate) their account, potentially + with a time delay to discourage making a new account right away. +* Change or add [admin contacts](#adding-account-administrative-contact-information), + but not remove. Servers are recommended to only permit this if they keep a + changelog on contact information to prevent misuse. + +General purpose endpoints like [`/send/{eventType}`](#put_matrixclientv3roomsroomidsendeventtypetxnid) +MAY return the error described below depending on the path parameters. For example, +a user may be allowed to send `m.room.redaction` events but not `m.room.message` +events through `/send`. + +Where a room is used to maintain communication between server administration +teams and the suspended user, servers are recommended to allow the user to send +events to that room specifically. Server administrators which do not want the +user to continue receiving messages may be interested in [account locking](#account-locking) +instead. + +Otherwise, the recommended set of explicitly forbidden actions is: + +* [Joining](#joining-rooms) or [knocking](#knocking-on-rooms) on rooms. +* Accepting or sending [invites](#room-membership). +* [Sending messages](#put_matrixclientv3roomsroomidsendeventtypetxnid) to rooms. +* Changing [profile data](#profiles) (display name and avatar, primarily). +* [Redacting](#redactions) other users' events, when permission is possible in a room. + +When a client attempts to perform an action while suspended, the server MUST +respond with a `403 Forbidden` error response with `M_USER_SUSPENDED` as the +error code, as shown below: + +``` +HTTP/1.1 403 Forbidden +Content-Type: application/json +``` + +```json +{ + "errcode": "M_USER_SUSPENDED", + "error": "You cannot perform this action while suspended." +} +``` + +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.