From f3b471771d680f1ac0ce939f6b4abed627d4a194 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 20 Aug 2024 14:01:56 +0200 Subject: [PATCH 1/9] MSC3939: Account locking Signed-off-by: Johannes Marbach --- content/client-server-api/_index.md | 54 +++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 1a6f1c6ec..6fea3d73c 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -100,6 +100,9 @@ section](#soft-logout) for more information. `M_MISSING_TOKEN` 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_BAD_JSON` Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys. @@ -516,6 +519,10 @@ token available. If it does not have a refresh token available, or refreshing fails with `soft_logout: true`, the client can acquire a new access token by specifying the device ID it is already using to the login API. +{{% changed-in v="1.12" %}} A client that receives such a response together +with an `M_USER_LOCKED` error code, cannot obtain a new access token until +the account has been [unlocked](#account-locking). + ### User-Interactive Authentication API #### Overview @@ -1425,6 +1432,53 @@ number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% /boxes/warning %}} +#### Account locking + +Server administrators may apply locks to prevent users from usefully +using their accounts, for instance, due to safety or security concerns. +In contrast to account deactivation, locking is a non-destructive action +that can be reversed. This specification describes the behaviour of clients +and servers when an account is locked but delibaretely leaves the creation +and removal of locks as a server implementation detail. + +When an account is locked, servers MUST return a `401 Unauthorized` error +response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout) +set to `true` on all but the following APIs: + +- [`POST /logout`](#post_matrixclientv3logout) +- [`POST /logout/all`](#post_matrixclientv3logoutall) + +Servers MAY additionally include details of why the lock was applied in +the `error` field. + +``` +HTTP/1.1 401 Unauthorized +Content-Type: application/json +``` + +```json +{ + "errcode": "M_USER_LOCKED", + "error": "This account has been locked", + "soft_logout": true +} +``` + +Servers SHOULD NOT invalidate access tokens on locked accounts unless the +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. + +Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session +information including encryption state and inform the user that their account +has been locked. While the lock is applied, clients SHOULD hide the normal UI +from the user, preventing general use of their account. Clients SHOULD, however, +continue to make rate-limited requests to `/sync` 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). + ### Adding Account Administrative Contact Information A homeserver may keep some contact information for administrative use. From 33de595c9d0066bccce3dc6c1623108ac343e0e1 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 20 Aug 2024 14:04:25 +0200 Subject: [PATCH 2/9] Fix typo --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 6fea3d73c..e8580a60b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1438,7 +1438,7 @@ Server administrators may apply locks to prevent users from usefully using their accounts, for instance, due to safety or security concerns. In contrast to account deactivation, locking is a non-destructive action that can be reversed. This specification describes the behaviour of clients -and servers when an account is locked but delibaretely leaves the creation +and servers when an account is locked but deliberately leaves the creation and removal of locks as a server implementation detail. When an account is locked, servers MUST return a `401 Unauthorized` error From 1f4c8f4e051cfa3acd0efab64331c54679656236 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 20 Aug 2024 14:05:48 +0200 Subject: [PATCH 3/9] Add changelog --- changelogs/client_server/newsfragments/1934.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1934.feature diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature new file mode 100644 index 000000000..7100396b5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1934.feature @@ -0,0 +1 @@ +Add account locking as per MSC3939. From 2b79c41a30ab78cac671050fc482947ba80d1cdc Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 27 Aug 2024 19:33:32 +0200 Subject: [PATCH 4/9] Update changelogs/client_server/newsfragments/1934.feature --- changelogs/client_server/newsfragments/1934.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature index 7100396b5..7bb445e7e 100644 --- a/changelogs/client_server/newsfragments/1934.feature +++ b/changelogs/client_server/newsfragments/1934.feature @@ -1 +1 @@ -Add account locking as per MSC3939. +Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/MSC3939). From f51797f1ee9fca3d1879518581df0a8edbd8a662 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 27 Aug 2024 19:37:18 +0200 Subject: [PATCH 5/9] Update changelogs/client_server/newsfragments/1934.feature --- changelogs/client_server/newsfragments/1934.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature index 7bb445e7e..75b556885 100644 --- a/changelogs/client_server/newsfragments/1934.feature +++ b/changelogs/client_server/newsfragments/1934.feature @@ -1 +1 @@ -Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/MSC3939). +Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). From fe387433bc17c45fdfbc146e794c34954a44af36 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 9 Sep 2024 08:09:24 +0200 Subject: [PATCH 6/9] Add added-in shortcode --- content/client-server-api/_index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index e8580a60b..dcbaf7769 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1434,6 +1434,8 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. #### Account locking +{{% added-in v="1.12" %}} + Server administrators may apply locks to prevent users from usefully using their accounts, for instance, due to safety or security concerns. In contrast to account deactivation, locking is a non-destructive action From 27d3db56eb2e0610931653c08fc34ba6876934c8 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:08:27 +0200 Subject: [PATCH 7/9] Update content/client-server-api/_index.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- content/client-server-api/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index dcbaf7769..0453a9c24 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1440,8 +1440,8 @@ Server administrators may apply locks to prevent users from usefully using their accounts, for instance, due to safety or security concerns. In contrast to account deactivation, locking is a non-destructive action that can be reversed. This specification describes the behaviour of clients -and servers when an account is locked but deliberately leaves the creation -and removal of locks as a server implementation detail. +and servers when an account is locked. It deliberately leaves the methods +for locking and unlocking accounts as a server implementation detail. When an account is locked, servers MUST return a `401 Unauthorized` error response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout) From ac3b194bb2c3a3f4a3ba2d982f89137686011c6e Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:08:52 +0200 Subject: [PATCH 8/9] Update content/client-server-api/_index.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0453a9c24..f93656495 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1445,7 +1445,7 @@ for locking and unlocking accounts as a server implementation detail. When an account is locked, servers MUST return a `401 Unauthorized` error response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout) -set to `true` on all but the following APIs: +set to `true` on all but the following Client-Server APIs: - [`POST /logout`](#post_matrixclientv3logout) - [`POST /logout/all`](#post_matrixclientv3logoutall) From 7ea55cf64f156c79e60e2e3ccaf052e4eed03fcf Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 25 Sep 2024 20:12:30 +0200 Subject: [PATCH 9/9] Linkify /sync --- content/client-server-api/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index f93656495..e9efe8ec2 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1475,8 +1475,8 @@ Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session information including encryption state and inform the user that their account has been locked. While the lock is applied, clients SHOULD hide the normal UI from the user, preventing general use of their account. Clients SHOULD, however, -continue to make rate-limited requests to `/sync` and other APIs to detect -when the lock has been lifted. +continue to make rate-limited requests to [`/sync`](#get_matrixclientv3sync) +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).