From 272ce4cc08aff604394fb3238271dd6b368aef4e Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 15 Jun 2026 15:29:48 +0100
Subject: [PATCH] Add `shared_history` flag to data structures

---
 .../modules/end_to_end_encryption.md                |  2 +-
 .../definitions/key_backup_session_data.yaml        |  6 ++++++
 data/event-schemas/examples/m.room_key.yaml         |  3 ++-
 data/event-schemas/schema/m.room_key.yaml           | 13 +++++++++++++
 4 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index 66947c78..4cfcb779 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -1967,7 +1967,7 @@ In order to enable end-to-end encryption in a room, clients can send an
 When creating a Megolm session in a room, clients must share the
 corresponding session key using Olm with the intended recipients, so
 that they can decrypt future messages encrypted using this session. An
-`m.room_key` event is used to do this. Clients must also handle
+[`m.room_key`](#mroom_key) event is used to do this. Clients must also handle
 `m.room_key` events sent by other devices in order to decrypt their
 messages.
 
diff --git a/data/api/client-server/definitions/key_backup_session_data.yaml b/data/api/client-server/definitions/key_backup_session_data.yaml
index b5878471..2a38cf0f 100644
--- a/data/api/client-server/definitions/key_backup_session_data.yaml
+++ b/data/api/client-server/definitions/key_backup_session_data.yaml
@@ -49,6 +49,12 @@ properties:
     description: |-
       Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
     example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
+  shared_history:
+    x-addedInMatrixVersion: "1.19"
+    type: boolean
+    description: |-
+      Whether the session is [shareable](/client-server-api/#shareable-encryption-sessions).
+    example: false
 required:
   - algorithm
   - forwarding_curve25519_key_chain
diff --git a/data/event-schemas/examples/m.room_key.yaml b/data/event-schemas/examples/m.room_key.yaml
index dba497b4..1dfe8809 100644
--- a/data/event-schemas/examples/m.room_key.yaml
+++ b/data/event-schemas/examples/m.room_key.yaml
@@ -5,6 +5,7 @@
     "algorithm": "m.megolm.v1.aes-sha2",
     "room_id": "!Cuyf34gef24t:localhost",
     "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
-    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
+    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY...",
+    "shared_history": false
   }
 }
diff --git a/data/event-schemas/schema/m.room_key.yaml b/data/event-schemas/schema/m.room_key.yaml
index c8c76bb4..c8102b3d 100644
--- a/data/event-schemas/schema/m.room_key.yaml
+++ b/data/event-schemas/schema/m.room_key.yaml
@@ -25,6 +25,19 @@ properties:
       session_key:
         type: string
         description: The key to be exchanged.
+      shared_history:
+        x-addedInMatrixVersion: "1.19"
+        type: boolean
+        description: |
+          `true` indicates that the creator of this encryption considers that
+          the session is [shareable](/client-server-api/#shareable-encryption-sessions):
+          in other words, the sender has observed that the [room history
+          visibility](/client-server-api/#room-history-visibility) is set to
+          `shared` or `world_readable`, and that they understand and agree that
+          the session keys may be shared with newly-invited users in future.
+
+          Absence, or any other value, indicates that the creator of the
+          session does not consider the session to be shareable.
     required:
       - algorithm
       - room_id