# 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. 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`.