Merge bb623a587e into 4c2bb5aae1

Previously the spec would use a mix of `string`, `URI`
and `MXC URI` for values of a user's `avatar_url` in
different apis (like `m.room.member`, `m.presence`,
CS profile endpoints).

This clarification updates all occurances to be MXC URIs,
prompted by https URIs `m.room.member#avatar_url` events
in the wild.

Signed-off-by: networkException <git@nwex.de>

changelogs/client_server/newsfragments/2410.clarification

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

changelogs/client_server/newsfragments/2422.clarification

@@ -0,0 +1 @@
+Use MXC URI type for all user `avatar_url` fields. Contributed by @networkException.

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 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 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/api/client-server/definitions/public_rooms_chunk.yaml

@@ -54,7 +54,8 @@ properties:
     example: true
   avatar_url:
     type: string
-    format: uri
+    format: mx-mxc-uri
+    pattern: "^mxc:\\/\\/"
     description: The URL for the room's avatar, if one is set.
     example: "mxc://example.org/abcdef"
   join_rule:

data/api/client-server/rooms.yaml

@@ -340,7 +340,8 @@ paths:
                             description: The display name of the user this object is representing.
                           avatar_url:
                             type: string
-                            format: uri
+                            format: mx-mxc-uri
+                            pattern: "^mxc:\\/\\/"
                             description: The avatar of the user this object is representing, as an [`mxc://`
                               URI](/client-server-api/#matrix-content-mxc-uris).
                     description: A map from user ID to a RoomMember object.

data/api/client-server/search.yaml

@@ -238,7 +238,8 @@ paths:
                                               title: Display name
                                             avatar_url:
                                               type: string
-                                              format: uri
+                                              format: mx-mxc-uri
+                                              pattern: "^mxc:\\/\\/"
                                               title: Avatar Url
                                     events_before:
                                       type: array

data/api/client-server/users.yaml

@@ -90,7 +90,8 @@ paths:
                           description: The display name of the user, if one exists.
                         avatar_url:
                           type: string
-                          format: uri
+                          format: mx-mxc-uri
+                          pattern: "^mxc:\\/\\/"
                           example: mxc://bar.com/foo
                           description: The avatar url, as an [`mxc://`
                             URI](/client-server-api/#matrix-content-mxc-uris),

data/api/server-server/query.yaml

@@ -172,6 +172,8 @@ paths:
                     example: John Doe
                   avatar_url:
                     type: string
+                    format: mx-mxc-uri
+                    pattern: "^mxc:\\/\\/"
                     description: |-
                       The avatar URL for the user's avatar. MUST either be omitted or set to
                       `null` if the user does not have an avatar set.

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.

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

@@ -12,6 +12,8 @@
             "properties": {
                 "avatar_url": {
                     "type": "string",
+                    "format": "mx-mxc-uri",
+                    "pattern": "^mxc:\\/\\/",
                     "description": "The current avatar URL for this user, if any."
                 },
                 "displayname": {

data/event-schemas/schema/m.room.member.yaml

@@ -53,7 +53,8 @@ properties:
       avatar_url:
         description: 'The avatar URL for this user, if any.'
         type: string
-        format: uri
+        format: mx-mxc-uri
+        pattern: "^mxc:\\/\\/"
       displayname:
         description: 'The display name for this user, if any.'
         type: