From 36ed8290452793e82a3f15d214875b356b62c295 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 24 Nov 2022 16:55:56 +0000 Subject: [PATCH 01/12] MSCXXXX: Account locking --- proposals/XXXX-account-locking.md | 55 +++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 proposals/XXXX-account-locking.md diff --git a/proposals/XXXX-account-locking.md b/proposals/XXXX-account-locking.md new file mode 100644 index 00000000000..9bfb6fe3485 --- /dev/null +++ b/proposals/XXXX-account-locking.md @@ -0,0 +1,55 @@ +# MSCXXXX: Account locking + +There are legitimate cases where server administrators might want the ability to +temporarily lock users out of their account. For example, server administrators +might require users to go through a regular, out-of-bounds verification check in +order to keep using their account, and temporarily lock a user out of their +account if they do not complete this check in time. + +At the time of writing this proposal, the only option for a server administrator +to prevent a user from accessing their account is to deactivate it. However, +this is a pretty destructive operation. Ideally, a locked account could be +unlocked without any visible impact on the account itself (joined rooms, +associated 3PIDs, etc). + +Note that +[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823) +addresses a similar concept coming from a moderation perspective. However, +locking and suspending an account are semantically different. + +## Proposal + +A new `M_USER_LOCKED` is introduced, which is communicated to clients in `403 Forbidden` HTTP responses. + +When an account is locked: + +* homeservers must respond to any authenticated request from the user with + `M_USER_LOCKED`, _except_ for requests to `/logout` and `/logout/all`. +* homeservers must not automatically invalidate existing access tokens for the + user. +* clients should keep data that has already been locally persisted, unless the + user manually logs out. + +When an account is unlocked, clients and the homeserver can start interacting +again as if nothing happened, similarly to when a client recovers after loss of +connection. + +## Alternatives + +This proposal could be merged with +[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823), which +describes a similar concept coming from a content moderation perspective. +However, locking and suspending an account are semantically different enough +that the author of this proposal thinks that it makes sense for those two cases +to be described differently in the API. + +Another option for merging this proposal with MSC3823 would be adding a +`suspended` boolean property and an optional `href` string property (which would +be required if `suspended` is `true`) to errors bearing the `M_USER_LOCKED` +error code. Opinions are welcome on whether this is a better solution than using +two distincts error codes. + +## Unstable prefix + +Until this proposal is accepted, implementations must use +`ORG_MATRIX_MSCXXXX_USER_LOCKED` instead of `M_USER_LOCKED`. From 79472a2cc368f677853e4475c76bdded975d38ea Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 24 Nov 2022 16:56:55 +0000 Subject: [PATCH 02/12] MSC number --- .../{XXXX-account-locking.md => 3939-account-locking.md} | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) rename proposals/{XXXX-account-locking.md => 3939-account-locking.md} (87%) diff --git a/proposals/XXXX-account-locking.md b/proposals/3939-account-locking.md similarity index 87% rename from proposals/XXXX-account-locking.md rename to proposals/3939-account-locking.md index 9bfb6fe3485..8fcfbbaba5d 100644 --- a/proposals/XXXX-account-locking.md +++ b/proposals/3939-account-locking.md @@ -1,4 +1,4 @@ -# MSCXXXX: Account locking +# MSC3939: Account locking There are legitimate cases where server administrators might want the ability to temporarily lock users out of their account. For example, server administrators @@ -12,11 +12,6 @@ this is a pretty destructive operation. Ideally, a locked account could be unlocked without any visible impact on the account itself (joined rooms, associated 3PIDs, etc). -Note that -[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823) -addresses a similar concept coming from a moderation perspective. However, -locking and suspending an account are semantically different. - ## Proposal A new `M_USER_LOCKED` is introduced, which is communicated to clients in `403 Forbidden` HTTP responses. @@ -52,4 +47,4 @@ two distincts error codes. ## Unstable prefix Until this proposal is accepted, implementations must use -`ORG_MATRIX_MSCXXXX_USER_LOCKED` instead of `M_USER_LOCKED`. +`ORG_MATRIX_MSC3939_USER_LOCKED` instead of `M_USER_LOCKED`. From 9a7a9030d7c207c488c190570db422cee7f69a1e Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 8 Aug 2023 18:19:45 +0200 Subject: [PATCH 03/12] Switch to 401 + soft_lougout --- proposals/3939-account-locking.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index 8fcfbbaba5d..740318d2d1d 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -14,7 +14,8 @@ associated 3PIDs, etc). ## Proposal -A new `M_USER_LOCKED` is introduced, which is communicated to clients in `403 Forbidden` HTTP responses. +A new `M_USER_LOCKED` is introduced, which is communicated to clients in +`401 Unauthorized` HTTP responses with `soft_logout` set to `true`. When an account is locked: @@ -29,6 +30,11 @@ When an account is unlocked, clients and the homeserver can start interacting again as if nothing happened, similarly to when a client recovers after loss of connection. +Using 401 return code allows the user to be aware of the fact that something wrong is +happening, since the app will be logged out. +Using `soft_logout` allows to keep everything encryption related in the client until +the user logs again (after being unlocked). + ## Alternatives This proposal could be merged with @@ -44,6 +50,10 @@ be required if `suspended` is `true`) to errors bearing the `M_USER_LOCKED` error code. Opinions are welcome on whether this is a better solution than using two distincts error codes. +Another option is to use 403 responses instead of 401 and `soft_logout`. We choose this +so that existing apps provide some feedback to the user without explicit support for +this MSC. + ## Unstable prefix Until this proposal is accepted, implementations must use From 73b0a48405a5b8ea42849ebef24ae13de5fb454e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 20 Mar 2024 22:20:16 -0600 Subject: [PATCH 04/12] FCP updates/clarity --- proposals/3939-account-locking.md | 90 +++++++++++++++++-------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index 740318d2d1d..d3548e62ea6 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -1,54 +1,66 @@ # MSC3939: Account locking -There are legitimate cases where server administrators might want the ability to -temporarily lock users out of their account. For example, server administrators -might require users to go through a regular, out-of-bounds verification check in -order to keep using their account, and temporarily lock a user out of their -account if they do not complete this check in time. - -At the time of writing this proposal, the only option for a server administrator -to prevent a user from accessing their account is to deactivate it. However, -this is a pretty destructive operation. Ideally, a locked account could be -unlocked without any visible impact on the account itself (joined rooms, -associated 3PIDs, etc). +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. Self-serve locking APIs are additionally not provided. ## Proposal -A new `M_USER_LOCKED` is introduced, which is communicated to clients in -`401 Unauthorized` HTTP responses with `soft_logout` set to `true`. +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 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. + +Clients MAY prevent actually logging the user out until the error code or response +changes. This is to allow the client to emit a few more requests after receiving +the error, as may be the case with a very active `/sync` loop. Once the error code +changes (but remains a 401 otherwise, regardless of soft logout), the client +should proceed with the logout. Similarly, if the response changes from an error +to a successful response, the client can assume the account has been unlocked and +return to normal operation without needing to get a new access token. + +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/unstable/client-server-api/#getwell-knownmatrixsupport) +in the meantime. -When an account is locked: +> *TODO*: MSC1929 was adopted into Matrix 1.10 - the link needs updating upon release. -* homeservers must respond to any authenticated request from the user with - `M_USER_LOCKED`, _except_ for requests to `/logout` and `/logout/all`. -* homeservers must not automatically invalidate existing access tokens for the - user. -* clients should keep data that has already been locally persisted, unless the - user manually logs out. +Locked accounts are still permitted to access the following API endpoints: -When an account is unlocked, clients and the homeserver can start interacting -again as if nothing happened, similarly to when a client recovers after loss of -connection. +* [`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) -Using 401 return code allows the user to be aware of the fact that something wrong is -happening, since the app will be logged out. -Using `soft_logout` allows to keep everything encryption related in the client until -the user logs again (after being unlocked). +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. ## Alternatives -This proposal could be merged with -[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823), which -describes a similar concept coming from a content moderation perspective. -However, locking and suspending an account are semantically different enough -that the author of this proposal thinks that it makes sense for those two cases -to be described differently in the API. +[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 option for merging this proposal with MSC3823 would be adding a -`suspended` boolean property and an optional `href` string property (which would -be required if `suspended` is `true`) to errors bearing the `M_USER_LOCKED` -error code. Opinions are welcome on whether this is a better solution than using -two distincts error codes. +Another similar concept would be "shadow banning", though this only applies to +moderation use cases. Another option is to use 403 responses instead of 401 and `soft_logout`. We choose this so that existing apps provide some feedback to the user without explicit support for @@ -56,5 +68,5 @@ this MSC. ## Unstable prefix -Until this proposal is accepted, implementations must use +Until this proposal is considered stable, implementations must use `ORG_MATRIX_MSC3939_USER_LOCKED` instead of `M_USER_LOCKED`. From 3c23f611713cd9395cbe9ae942bfabc0e61ba368 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 25 Mar 2024 20:39:32 -0600 Subject: [PATCH 05/12] Mention appeals/information --- proposals/3939-account-locking.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index d3548e62ea6..5bba1598915 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -53,6 +53,13 @@ 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 From 5bccc4e402e088bff7a9fbbda01270e6818bdfa2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 Mar 2024 17:26:23 -0600 Subject: [PATCH 06/12] v1.10 --- proposals/3939-account-locking.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index 5bba1598915..d91a120be53 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -38,11 +38,9 @@ including encryption state and inform the user that their account has been locke 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/unstable/client-server-api/#getwell-knownmatrixsupport) +[server contact discovery](https://spec.matrix.org/v1.10/client-server-api/#getwell-knownmatrixsupport) in the meantime. -> *TODO*: MSC1929 was adopted into Matrix 1.10 - the link needs updating upon release. - Locked accounts are still permitted to access the following API endpoints: * [`POST /logout`](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3logout) From 896e98c2b4287615cfa2415f30cac9a6f86d79b0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 Mar 2024 17:37:38 -0600 Subject: [PATCH 07/12] Clarify why not 403 --- proposals/3939-account-locking.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index d91a120be53..a25cc7882ff 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -23,7 +23,9 @@ to make use of the [soft logout](https://spec.matrix.org/v1.9/client-server-api/ semantics: keep encryption state, but otherwise render the account unusable. 401 is used to support legacy clients by giving the user 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. +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. Clients MAY prevent actually logging the user out until the error code or response changes. This is to allow the client to emit a few more requests after receiving @@ -67,9 +69,17 @@ for details. Another similar concept would be "shadow banning", though this only applies to moderation use cases. -Another option is to use 403 responses instead of 401 and `soft_logout`. We choose this -so that existing apps provide some feedback to the user without explicit support for -this MSC. +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 From 02c3a9e40a95f58b0a4b0b0a1327595fcf978770 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 Mar 2024 17:37:59 -0600 Subject: [PATCH 08/12] Update proposals/3939-account-locking.md Co-authored-by: David Baker --- proposals/3939-account-locking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index a25cc7882ff..d1236443274 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -21,7 +21,7 @@ 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 semantically meaningful +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 From 257207b82fe9c26b447f29e4bec75bccc1bafef5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 Mar 2024 17:52:45 -0600 Subject: [PATCH 09/12] Clarify UI expectations --- proposals/3939-account-locking.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index d1236443274..b3078a9df12 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -27,14 +27,6 @@ a more useful error message about their account status, though their session dat 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. -Clients MAY prevent actually logging the user out until the error code or response -changes. This is to allow the client to emit a few more requests after receiving -the error, as may be the case with a very active `/sync` loop. Once the error code -changes (but remains a 401 otherwise, regardless of soft logout), the client -should proceed with the logout. Similarly, if the response changes from an error -to a successful response, the client can assume the account has been unlocked and -return to normal operation without needing to get a new access token. - 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 @@ -43,6 +35,18 @@ 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) From 920d31543f54fb1f63d29c134e24e4ae822fb2c0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 27 Mar 2024 01:34:45 -0600 Subject: [PATCH 10/12] Update proposals/3939-account-locking.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3939-account-locking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index b3078a9df12..3b6d15943e7 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -12,7 +12,7 @@ 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. Self-serve locking APIs are additionally not provided. +implementation detail. APIs for administration of locking are also not provided. ## Proposal From a10802daecacbe1cc53c80d01a39df8ae31f9e8f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 3 Apr 2024 15:22:40 -0600 Subject: [PATCH 11/12] Update proposals/3939-account-locking.md Co-authored-by: Hubert Chathi --- proposals/3939-account-locking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index 3b6d15943e7..85c7af27ea1 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -52,7 +52,7 @@ 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) -Servers SHOULD NOT invalidate an account's access tokens in case the account becomes +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. From f76d53adbd690bf7b625666269d469d3c0ad01f8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 30 Apr 2024 15:59:14 -0600 Subject: [PATCH 12/12] Update proposals/3939-account-locking.md Co-authored-by: Hubert Chathi --- proposals/3939-account-locking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3939-account-locking.md b/proposals/3939-account-locking.md index 85c7af27ea1..c80f4b5e435 100644 --- a/proposals/3939-account-locking.md +++ b/proposals/3939-account-locking.md @@ -39,7 +39,7 @@ 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 +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