Document recovery and backup_disabled account data

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

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.<device_id>](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

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