diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md new file mode 100644 index 00000000000..c80f4b5e435 --- /dev/null +++ b/proposals/3939-account-locking.md @@ -0,0 +1,91 @@ +# MSC3939: Account locking + +Account locking is a common safety and security tool where server administrators +can prevent a user from usefully using their account. For example, too many failed +login attempts, escalation in moderation action, or out of band verification +needing to be completed. + +Currently, Matrix only supports deactivating an account. This is a destructive +action which often leads to the account leaving all joined rooms, among other +details. With account locking, the effect of making the user unable to access +their account is achieved without destroying that same account - the account +can always be unlocked. + +This proposal covers account locking, though leaves the specifics of use as an +implementation detail. APIs for administration of locking are also not provided. + +## Proposal + +When an account is locked, clients receive a `401 Unauthorized` error response +to most APIs with an `M_USER_LOCKED` error code and `soft_logout` set to `true`. +Excluded APIs are described below. We enable `soft_logout` to encourage clients +to make use of the [soft logout](https://spec.matrix.org/v1.9/client-server-api/#soft-logout) +semantics: keep encryption state, but otherwise render the account unusable. 401 +is used to support legacy clients by giving the user a semantically meaningful +experience: they may need to try logging in again, and when they do they may get +a more useful error message about their account status, though their session data +may be deleted by the client if it doesn't recognize the error code. Soft logout +aims to prevent total destruction of this data, however. + +Upon receiving the `M_USER_LOCKED` error, clients SHOULD retain session information +including encryption state and inform the user that their account has been locked. +Details about *why* the user's account is locked are not formally described by +this proposal, though future MSCs which cover informing users about actions taken +against their account should have such details. Clients may wish to make use of +[server contact discovery](https://spec.matrix.org/v1.10/client-server-api/#getwell-knownmatrixsupport) +in the meantime. + +Clients SHOULD hide the normal UI from the user when informing them that their +account is locked, preventing general use of the account. + +Clients SHOULD continue to `/sync` and make other API calls to more quickly detect +when the lock has been lifted. However, clients should rate-limit their requests. If unlocked, the APIs will either return a different +error code or a normal 200 OK/successful response. For example, `/sync` will return +to working as though nothing ever happened. If the error code changes to +`M_UNKNOWN_TOKEN`, the client should delete local session data as it normally +would when seeing the error code (and use soft logout as it normally would). This +is typically expected if the server admin logged the user out or the user logged +themselves out. + +Locked accounts are still permitted to access the following API endpoints: + +* [`POST /logout`](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3logout) +* [`POST /logout/all`](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3logoutall) + +When a user's account is locked, servers SHOULD NOT invalidate an account's access tokens in case the account becomes +unlocked: the user should be able to retain their sessions without having to log +back in. However, if a client requests a logout (using the above endpoints), the +associated access tokens should be invalidated as normal. + +## Potential issues + +This proposal does not communicate *why* a user's account is restricted. The human-readable `error` +field may contain some information, though anything comprehensive may not be surfaced to the user. +A future MSC is expected to build a system for both informing the user of the action taken against +their account and allow the user to appeal that action. + +## Alternatives + +[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823) covers +a similar concept, though is semantically different. See [matrix-org/glossary](https://github.com/matrix-org/glossary) +for details. + +Another similar concept would be "shadow banning", though this only applies to +moderation use cases. + +A 403 HTTP status code was considered instead of 401 with a `soft_logout`. A 403 +would indicate that the given action is denied, but otherwise keep the user logged +in. This could wrongly indicate [suspension](https://github.com/matrix-org/matrix-spec-proposals/pull/3823), +confusing the user. Instead, we provide a semantically similar experience where +the user gets soft logged out on legacy clients, preserving encryption and related +session data (assuming the client also supports soft logout). This can result in +some loss of other session data however, like device-specific settings. Users may +also be differently confused when they try to log back in and get cryptic error +messages (indicating wrong username/password), however as mentioned above in the +Potential Issues section, communicating actions taken against an account is a +concern for a future MSC. + +## Unstable prefix + +Until this proposal is considered stable, implementations must use +`ORG_MATRIX_MSC3939_USER_LOCKED` instead of `M_USER_LOCKED`.