Merge 867c96c22b into 156d1b878a

changelogs/client_server/newsfragments/2354.feature

@@ -0,0 +1 @@
+Specify m.key_backup account data (MSC4287).

content/client-server-api/_index.md

@@ -4280,6 +4280,7 @@ that profile.
 | [Policy Servers](#policy-servers)                          | Optional  | Optional | Optional | Optional | Optional |
 | [OpenID](#openid)                                          | Optional  | Optional | Optional | Optional | Optional |
 | [Recently used emoji](#recently-used-emoji)                | Optional  | Optional | Optional | Optional | Optional |
+| [Key Backup Enabled](#key-backup-enabled)                  | Optional  | Optional | Optional | Optional | Optional |
 | [Reference Relations](#reference-relations)                | Optional  | Optional | Optional | Optional | Optional |
 | [Reporting Content](#reporting-content)                    | Optional  | Optional | Optional | Optional | Optional |
 | [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
@@ -4385,5 +4386,6 @@ systems.
 {{% cs-module name="Event replacements" filename="event_replacements" %}}
 {{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}
 {{% cs-module name="Recently used emoji" filename="recent_emoji" %}}
+{{% cs-module name="Key backup enabled" filename="key_backup_enabled" %}}
 {{% cs-module name="Threading" filename="threading" %}}
 {{% cs-module name="Reference relations" filename="reference_relations" %}}

content/client-server-api/modules/key_backup_enabled.md

@@ -0,0 +1,44 @@
+### Key backup enabled
+
+{{% added-in v="1.19" %}}
+
+This module enables clients to track a user's preference about enabling or
+disabling [server-side backups of room keys](#server-side-key-backups). The data
+is stored in the [`m.key_backup`](#mkey_backup) global
+[account data](#client-config).
+
+#### Events
+
+{{% event event="m.key_backup" %}}
+
+#### Client behaviour on sign-in
+
+When a user signs in to a client which supports encryption and key backup:
+
+* If this event type exists in account data and contains the specified property
+  in the correct format, clients which support key backup MUST take account of
+  its contents in their behaviour. For example, clients may automatically turn
+  on/off key backup based on the property, or prompt the user, using the
+  property value as a default. (Because this property is server-controlled,
+  clients may wish to confirm the user's intention.)
+
+* If this event type does not exist in account data, or if it does not contain
+  the `enabled` property, or if the value of `enabled` is not a boolean value,
+  clients MUST ignore the existing value and MAY decide whether or not to
+  perform key backup, possibly based on user input.
+
+#### Client behaviour on setting change
+
+If the user turns on key backups, clients MUST set this event type in account
+data, to `"enabled": true`.
+
+If the user turns off key backups, clients MUST set this event type in account
+data, to `"enabled": false`.
+
+#### Not actively monitoring this setting
+
+Clients are not required to monitor the `m.key_backup` account data actively.
+Clients MAY monitor the setting but should be aware that changing this setting
+without user interaction based on choices made in a different client (or a
+compromised homeserver) may cause unforeseen security problems or simply be
+unexpected by users.

data/api/client-server/definitions/key_backup.yaml

@@ -0,0 +1,22 @@
+# Copyright 2026 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+title: Key Backup
+type: object
+properties:
+  enabled:
+    type: boolean
+    description: True if the user chose to enable key backup. False if the user chose to disable key backup.
+required:
+  - enabled

data/event-schemas/examples/m.key_backup.yaml

@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.key_backup",
+  "content": {
+    "enabled": false
+  }
+}

data/event-schemas/schema/m.key_backup.yaml

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "title": "Key Backup Event",
+  "description": "Allows clients to track user preferences about key backup.",
+  "allOf": [{
+    "$ref": "core-event-schema/event.yaml"
+  }],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["m.key_backup"]
+    },
+    "content": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "description": "True if the user chose to enable key backup. False if the user chose to disable key backup.",
+          "type": "boolean",
+        }
+      },
+      "required": ["enabled"]
+    }
+  },
+  "required": ["type", "content"]
+}