diff --git a/proposals/4323-agnostic-suspend-and-lock.md b/proposals/4323-agnostic-suspend-and-lock.md new file mode 100644 index 000000000..8759d8270 --- /dev/null +++ b/proposals/4323-agnostic-suspend-and-lock.md @@ -0,0 +1,147 @@ +# MSC4323: User suspension & locking endpoints + +Currently the specification outlines error codes for suspended and locked users, +even going as far as to suggest which endpoints can and cannot be executed by suspended users. +However, it does not currently define an endpoint which server administrators can call to suspend +and unsuspend users on their server. +As a result, moderation tooling such as Draupnir and Meowlnir have to implement +implementation-specific calls, which is not sustainable as more implementations other than Synapse +integrate this feature. + +This proposal will outline new endpoints that will allow server administrators to +suspend, unsuspend, lock, and unlock given users. + +## Proposal + +> [!IMPORTANT] +> What defines a "server administrator" is left up to the implementation itself as most already have +> their own systems for defining administrators (e.g. Synapse has a database flag, Conduit has room +> membership) which rarely has a reason to be exposed outside of their respective management +> interfaces. + +Complementing [section 10.22 (Server Administration)][p1] of the client-to-server specification, +four new endpoints are introduced: + +- `GET /_matrix/client/v1/admin/suspend/{userId}` +- `PUT /_matrix/client/v1/admin/suspend/{userId}` +- `GET /_matrix/client/v1/admin/lock/{userId}` +- `PUT /_matrix/client/v1/admin/lock/{userId}` + +These new endpoints are similar to [`GET /_matrix/client/v3/admin/whois/{userId}`][p2] in that they +are clearly defined as administration endpoints, however are restricted to only permitting +execution on local server users. + +### New endpoint definitions + +The response body of both the `GET` and `PUT` endpoints, as well as the request body of the +`PUT` endpoints, are defined below. Custom properties may be used provided they utilise +[proper namespacing][p3] in their fields. + +**Suspend**: + +A single key, `suspended`, with a boolean indicating if the target account is suspended: + +```json +{"suspended": true} +``` + +**Lock**: + +A single key, `locked`, with a boolean indicating if the target account is locked: + +```json +{"locked": false} +``` + +### New capability definition + +The server should advertise that these new endpoints are available for the authenticated user +to use by including the following new capability: + +```json5 +{ + "capabilities": { + "m.account_moderation": { + "suspend": true, // or false if unavailable/unimplemented + "lock": true // or false if unavailable/unimplemented + } + } +} +``` + +This allows clients to determine whether they are able to suspend/lock users on this homeserver, +allowing them to do things like dynamically show or hide a "suspend user" button, etc. + +The capability should not be advertised at all if both `suspend` and `lock` would be `false`. +Omitting a key is equivalent to it being `false`. + +### Errors and restrictions + +Sending a request to the respective endpoints returns: + +- `400 / M_INVALID_PARAM`: The user ID does not belong to the local server. +- `403 / M_FORBIDDEN`: The requesting user is not a server administrator, is trying to suspend/lock + their own account, or the target user is another administrator. +- `404 / M_NOT_FOUND`: The user ID is not found, or is deactivated. + +In order to prevent user enumeration, implementations have to ensure that authorization is checked +prior to trying to do account lookups. +As this endpoint requires authentication with an administrator account, guest access is not +permitted. Additionally, no rate-limiting is imposed. + +[p1]: https://spec.matrix.org/v1.15/client-server-api/#server-administration +[p2]: https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3adminwhoisuserid +[p3]: https://spec.matrix.org/v1.15/appendices/#common-namespaced-identifier-grammar + +## Potential issues + +This proposal does not outline any metadata fields for management, such as action reasons, +temporary actions, authors, etc, which implementation-specific methods may currently have. +This is for the sake of brevity and simplicity, and may be expanded upon by a future proposal. + +This proposal is also written under the assumption that all server administrators are equal, and +cannot be suspended or locked. If a server permits such actions against a privileged user, without +stripping their privileges, conflicting behaviours may be encountered. + +## Alternatives + +A full "user-info" endpoint has been suggested, which would include more information about a user's +account that could interest server administrators. This proposal focuses solely on providing +tooling with the capability to suspend and lock without needing to maintain several +implementation-specific versions of their code, and adding a full-fleged user-info endpoint is +almost entirely out of scope. + +## Security considerations + +Adding these new endpoints may provide a path to circumvent restrictions previously imposed on +implementation-specific versions of the suspend and lock endpoints (such as them being blocked off +at the reverse proxy) - server developers will likely want to ensure that their users are made +appropriate aware of this (via release notes or some other similar high-visibility channel) so that +they can apply those same restrictions to these new endpoints if necessary. + +These endpoints also increase the compromise value of an administrator account, as an attacker who +breaches one of these accounts will be able to suspend or lock other users on the server. While +the attacker would not be able to lock out other administrators, a single-administrator homeserver +may be vulnerable to a temporary takeover if the sole administrator account is breached and +the deployment cannot be secured & have the change reverted quickly. +It may possibly also allow an attacker to disable other room-level moderation tooling, such as +moderation bots, assuming those tools are not also server administrators. + +## Unstable prefix + +| Stable | Unstable | +| ------ | -------- | +| `/_matrix/client/v1/admin/...` | `/_matrix/client/unstable/uk.timedout.msc4323/admin/...` | +| `m.account_moderation` | `uk.timedout.msc4323` | + +`locked` and `suspended` in the request/response bodies do not require an unstable prefix +as the entire body is new. + +Servers should advertise `"uk.timedout.msc4323":true` in their `/versions` response while this +proposal is unstable in order to advertise support for this new feature. +It is left as an implementation detail whether to require authentication to view this version flag +or not, as the capabilities endpoint requires authentication regardless. + +## Dependencies + +None