diff --git a/spec/backup_disabled.md b/spec/backup_disabled.md new file mode 100644 index 0000000..d96936f --- /dev/null +++ b/spec/backup_disabled.md @@ -0,0 +1,35 @@ +# m.org.matrix.custom.backup_disabled: Recording whether key backup is enabled or disabled + +The `m.org.matrix.custom.backup_disabled` account data event records whether the +user has disabled key backup, so that this information is synchronised between +their devices. Its main purpose is to avoid continuously nagging the user on +multiple devices if they have already chosen to disable key backup. + +It is an object with a boolean property, `disabled`. If the user has chosen to +not enable key backup (for example, by disabling key backup, or by dismissing a +toast prompting them to enable recovery), `disabled` is set to `true`. If the +user has chosen to enable key backup, `disabled` is set to `false`. If +`disabled` is set to `true` but key backup is set up, the client should ignore +the value of `disabled`. + +If there is no `m.org.matrix.custom.backup_disabled` event, this indicates that +the user has not make any decision yet about key backup. In this case, if +backup is not yet set up, we prompt the user to enable backup. + +## MSC + +This is an older version of +[MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287), and [we +should eventually migrate to the system described there](https://github.com/element-hq/element-meta/issues/2745). + +The main difference between this proposal and the MSC is that the MSC uses an +`enabled` property with the values having the reverse meaning of the `disabled` +property used in this proposal. + + +## Implementations + +* `element-web` implemented this in February 2025: + * https://github.com/element-hq/element-web/pull/29290 +* `matrix-rust-sdk` implemented this in November 2023: + * https://github.com/matrix-org/matrix-rust-sdk/pull/2842 diff --git a/spec/index.md b/spec/index.md new file mode 100644 index 0000000..9d30c36 --- /dev/null +++ b/spec/index.md @@ -0,0 +1,12 @@ +Element uses the following non-standard event types: + +# Account-data events + +- [io.element.functional_members](functional_members.md): Marking room members + as unimportant functional members +- [io.element.matrix_client_information.](matrix_client_information.md): + Storing additional client information per device +- [m.org.matrix.custom.backup_disabled](backup_disabled.md): Recording whether + key backup is enabled or disabled +- [io.element.recovery](recovery.md): Recording whether recovery is enabled or + disabled diff --git a/spec/recovery.md b/spec/recovery.md new file mode 100644 index 0000000..c3bbc7c --- /dev/null +++ b/spec/recovery.md @@ -0,0 +1,31 @@ +# io.element.recovery: Recording whether recovery is enabled or disabled + +The `io.element.recovery` account data event indicates whether the user has +enabled or disabled recovery (secret storage), so that this information is +synchronised between devices. Its main purpose is to avoid continuously nagging +the user on multiple devices if they have already chosen to disable recovery. + +It is an object with a boolean property, `enabled`. If the user has chosen to +not enable recovery (for example, by disabling recovery, or by dismissing a +toast prompting them to enable recovery), `enabled` is set to `false`. If the +user has chosen to enable recovery, `enabled` is set to `true`. If `enabled` is +set to `false` but recovery is set up, the client should ignore the value of +`enabled`. + +If there is no `io.element.recovery` event, this indicates that the user has not +make any decision yet about recovery. In this case, if recovery is not yet set +up (but key backup is enabled), we prompt the user to enable recovery. + +Note that we will only enable recovery if key backup is enabled. This means +that the value of this account data event is affected by the value of +[`m.org.matrix.custom.backup_disabled`](backup_disabled.md) account data event. +In particular, if `m.org.matrix.custom.backup_disabled` has `"disabled": true`, +then we ignore this account data, since we will not prompt the user to enable +recovery. However, if a user enables key backup +(`m.org.matrix.custom.backup_disabled` set to `{"disabled": false}`), they may +disable or enable recovery. + +## Implementations + +* `element-web` implemented this in June 2025 + * https://github.com/element-hq/element-web/pull/30075