changelogs/client_server/newsfragments/2410.clarification

@@ -1 +0,0 @@
-Clarify history key sharing requirements. Contributed by @HarHarLinks and Matrix Stammtisch Aachen.

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

@@ -1551,9 +1551,12 @@ objects described as follows:
 
 {{% added-in v="1.19" %}}
 
-When Alice invites Bob to an encrypted room, she likely wants Bob to have access
-to messages that were previously sent in that room, subject to the [history
-visibility](#room-history-visibility) setting of the room.
+When Alice invites Bob to an encrypted room, that room might be set up for
+Bob to have access to messages that were previously sent in that room,
+subject to the [history visibility](#room-history-visibility) setting of the room.
+Because the key material is not available on the server,
+Alice MUST share the decryption keys of messages visible according to
+the history visibility setting so Bob can read the message history.
 
 Alice does this by constructing an [encrypted key
 bundle](#construction-and-sharing-of-the-key-bundle) and sharing it with Bob
@@ -1610,22 +1613,12 @@ room.
 
 ##### Construction and sharing of the key bundle
 
-Marking keys as [shareable](#shareable-encryption-sessions) essentially serves as
-precomputation of which keys Bob needs to decrypt all messages he can see, as
-defined by the room's history visibility.
+Alice's client MAY choose not to share any room history (even messages sent when the
+history visibility setting would allow sharing) if the current history
+visibility setting does not allow sharing (i.e. if `history_visibility` is
+set to `invited` or `joined`).
 
-History visibility mechanics prevent changing the visibility of events in
-hindsight. It is thus possible for a room timeline to have "gappy" visibility,
-i.e. events sent during `shared` visibility in the past are visible, but events
-more recently sent during `joined` visibility and before joining are not visible.
-In such cases where the current history visibility setting does not allow sharing
-(i.e. if `history_visibility` is set to `invited` or `joined`), Alice's client
-MAY choose not to share *any* room history, even messages sent when the
-history visibility setting would allow sharing.
-
-In all other cases, Alice's client MUST share all available shareable keys.
-
-Before inviting Bob to a room, Alice's client constructs and sends a key bundle as follows:
+Otherwise, before inviting Bob to a room, Alice's client constructs and sends a key bundle as follows:
 
 1. Alice's client SHOULD ensure that it has downloaded all keys relevant to the room
    from [server-side key backup](#server-side-key-backups), if she is using it.

data/event-schemas/schema/components/room_key_withheld_content.yaml

@@ -33,9 +33,7 @@ properties:
       - m.no_olm
       - m.history_not_shared
     description: |-
-      A machine-readable code for why the key was not sent, as defined by
-      [Reporting that decryption keys are withheld](#reporting-that-decryption-keys-are-withheld).
-      Codes beginning
+      A machine-readable code for why the key was not sent. Codes beginning
       with `m.` are reserved for codes defined in the Matrix
       specification. Custom codes must use the Java package naming
       convention.