Merge cb0e7a0bec into 4c2bb5aae1

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2410.clarification

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

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

@@ -1551,7 +1551,7 @@ objects described as follows:
 
 {{% added-in v="1.19" %}}
 
-When Alice invites Bob to an encrypted room, she might want Bob to have access
+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.
 
@@ -1610,12 +1610,22 @@ room.
 
 ##### Construction and sharing of the key bundle
 
-Alice's client MAY choose not to share any room history (even messages sent when the
-history visibity 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`).
+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.
 
-Otherwise, before inviting Bob to a room, Alice's client constructs and sends a key bundle as follows:
+History visibility mechanics prevent changing the visibility of events
+retrospectively. It is thus possible for a room timeline to have "gappy" visibility.
+For example, events sent in the past during `shared` visibility are visible to new
+members, even though events sent more recently (during `joined` visibility) 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`), client implementations
+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 SHOULD share all available shareable keys.
+
+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,7 +33,9 @@ properties:
       - m.no_olm
       - m.history_not_shared
     description: |-
-      A machine-readable code for why the key was not sent. Codes beginning
+      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
       with `m.` are reserved for codes defined in the Matrix
       specification. Custom codes must use the Java package naming
       convention.