Merge 02ce04f083 into 4c2bb5aae1

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

changelogs/client_server/newsfragments/2407.clarification

@@ -0,0 +1 @@
+Add further normative language in mutual rooms server behaviour.

changelogs/client_server/newsfragments/2413.clarification

@@ -0,0 +1 @@
+Improve the format description of `m.room.encrypted` (Olm/Megolm) events.

changelogs/client_server/newsfragments/2422.clarification

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

changelogs/olm_megolm/newsfragments/2421.clarification

@@ -0,0 +1 @@
+Fix typesetting of some symbols in the Olm/Megolm spec.

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

@@ -1723,28 +1723,30 @@ Devices that support Olm must include "m.olm.v1.curve25519-aes-sha2" in
 their list of supported messaging algorithms, must list a Curve25519
 device key, and must publish Curve25519 one-time keys.
 
-An event encrypted using Olm has the following format:
+The content of an [`m.room.encrypted`](#mroomencrypted) event using Olm has the following format:
 
 ```json
 {
-  "type": "m.room.encrypted",
   "content": {
     "algorithm": "m.olm.v1.curve25519-aes-sha2",
     "sender_key": "<sender_curve25519_key>",
     "ciphertext": {
       "<device_curve25519_key>": {
         "type": 0,
-        "body": "<encrypted_payload_base_64>"
+        "body": "<base64_encoded_olm_message>"
       }
     }
   }
 }
 ```
-
-`ciphertext` is a mapping from device Curve25519 key to an encrypted
-payload for that device. `body` is a Base64-encoded [Olm message body](/olm-megolm/olm/#the-olm-message-format).
-`type` is an integer indicating the type of the message body: 0 for the
-initial [pre-key message](/olm-megolm/olm/#pre-key-messages), 1 for [normal messages](/olm-megolm/olm/#normal-messages).
+Note that when the event is received from the server, it will have a `type`
+(with a value of `m.room.encrypted`) and `sender` property alongside the
+`content` property. In `content`, `ciphertext` is a mapping from a device
+Curve25519 key to an object with a `type` and a `body`. Here, `body` is a
+Base64-encoded [Olm message](/olm-megolm/olm/#the-olm-message-format), and
+`type` is an integer indicating the type of the message:
+0 for the initial [pre-key messages](/olm-megolm/olm/#pre-key-messages),
+1 for [normal messages](/olm-megolm/olm/#normal-messages).
 
 Olm sessions will generate messages with a type of 0 until they receive
 a message. Once a session has decrypted a message it will produce
@@ -1891,23 +1893,24 @@ This uses:
 Devices that support Megolm must support Olm, and include
 "m.megolm.v1.aes-sha2" in their list of supported messaging algorithms.
 
-An event encrypted using Megolm has the following format:
+The content of an [`m.room.encrypted`](#mroomencrypted) event using Megolm has the following format:
 
 ```json
 {
-  "type": "m.room.encrypted",
   "content": {
     "algorithm": "m.megolm.v1.aes-sha2",
     "sender_key": "<sender_curve25519_key>",
     "device_id": "<sender_device_id>",
     "session_id": "<outbound_group_session_id>",
-    "ciphertext": "<encrypted_payload_base_64>"
+    "ciphertext": "<base64_encoded_megolm_message>"
   }
 }
 ```
-
-The encrypted payload can contain any message event. The plaintext is of
-the form:
+Note that when the event is received from the server, it will have additional
+properties alongside the `content` property, including a `type` (with a value
+of `m.room.encrypted`) and a `sender` property. In `content`, `ciphertext`
+is a Base64-encoded [Megolm message](/olm-megolm/megolm/#message-format),
+whose plaintext body is of the form:
 
 ```json
 {
@@ -1917,7 +1920,7 @@ the form:
 }
 ```
 
-We include the room ID in the payload, because otherwise the homeserver
+We include the room ID in the encrypted message, because otherwise the homeserver
 would be able to change the room a message was sent in.
 
 Clients must guard against replay attacks by keeping track of the

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

@@ -91,13 +91,13 @@ For example, a replacement for an encrypted event might look like this:
         "sender_key": "<sender_curve25519_key>",
         "device_id": "<sender_device_id>",
         "session_id": "<outbound_group_session_id>",
-        "ciphertext": "<encrypted_payload_base_64>"
+        "ciphertext": "<base64_encoded_megolm_message>"
     }
     // irrelevant fields not shown
 }
 ```
 
-... and, once decrypted, the payload might look like this:
+... and the plaintext body of the Megolm message might look like this:
 
 ```json
 {

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

@@ -6,9 +6,9 @@
 
 #### Server behaviour
 
-The server may decide that the response to this endpoint is too large, and only return a
-subset of the results. In this case, the server should populate the optional field `next_batch`
-with an [opaque identifier](/appendices/#opaque-identifiers). The client may then supply
+The server MAY decide that the response to this endpoint is too large, and only return a
+subset of the results. In this case, the server populates the optional field `next_batch`
+with an [opaque identifier](/appendices/#opaque-identifiers). The client can then supply
 the identifier as the `from` query parameter in a subsequent request, along with the original
 `user_id`, to fetch the next batch of responses. This will continue until the server no longer
 inserts `next_batch`, meaning there are no further results.

content/olm-megolm/megolm.md

@@ -257,8 +257,8 @@ consists of the following key-value pairs:
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-Message-Index|0x08|Integer|The index of the ratchet, i
-Cipher-Text|0x12|String|The cipher-text, Xi, of the message
+Message-Index|0x08|Integer|The index of the ratchet, \(i\).
+Cipher-Text|0x12|String|The cipher-text of the message, \(X_i\).
 
 Within the payload, integers are encoded using a variable length encoding. Each
 integer is encoded as a sequence of bytes with the high bit set followed by a

content/olm-megolm/olm.md

@@ -17,12 +17,12 @@ side of an \(=\) it means that the output is split.
 When this document uses \(\operatorname{ECDH}\left(K_A,K_B\right)\) it means
 that each party computes a Diffie-Hellman agreement using their private key 
 and the remote party's public key.
-So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{public},K_A^{private}\right)\)
-and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{public},K_B^{private}\right)\).
+So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{\mathit{public}},K_A^{\mathit{private}}\right)\)
+and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{\mathit{public}},K_B^{\mathit{private}}\right)\).
 
-Where this document uses \(\operatorname{HKDF}\left(salt,IKM,info,L\right)\) it
+Where this document uses \(\operatorname{HKDF}\left(\mathit{salt},\mathit{IKM},\mathit{info},L\right)\) it
 refers to the [HMAC-based key derivation function][] with a salt value of
-\(salt\), input key material of \(IKM\), context string \(info\),
+\(\mathit{salt}\), input key material of \(\mathit{IKM}\), context string \(\mathit{info}\),
 and output keying material length of \(L\) bytes.
 
 ## The Olm Algorithm
@@ -226,9 +226,9 @@ significant bits are stored in the first byte.
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-Ratchet-Key|0x0A|String|The public part of the ratchet key, Ti, of the message
-Chain-Index|0x10|Integer|The chain index, j, of the message
-Cipher-Text|0x22|String|The cipher-text, Xi, j, of the message
+Ratchet-Key|0x0A|String|The public part of the ratchet key of the message, \(T_i\).
+Chain-Index|0x10|Integer|The chain index of the message, \(j\).
+Cipher-Text|0x22|String|The cipher-text of the message, \(X_{i,j}\).
 
 The length of the MAC is determined by the authenticated encryption algorithm
 being used. (Olm version 1 uses [HMAC-SHA-256][], truncated to 8 bytes). The
@@ -251,9 +251,9 @@ The payload uses the same key-value format as for normal messages.
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-One-Time-Key|0x0A|String|The public part of Bob's single-use key, Eb.
-Base-Key|0x12|String|The public part of Alice's single-use key, Ea.
-Identity-Key|0x1A|String|The public part of Alice's identity key, Ia.
+One-Time-Key|0x0A|String|The public part of Bob's single-use key, \(E_B\).
+Base-Key|0x12|String|The public part of Alice's single-use key, \(E_A\).
+Identity-Key|0x1A|String|The public part of Alice's identity key, \(I_A\).
 Message|0x22|String|An embedded Olm message with its own version and MAC.
 
 ## Olm Authenticated Encryption
@@ -268,13 +268,13 @@ message key using [HKDF-SHA-256][] using the default salt and an info of
 
 \[
 \begin{aligned}
-    AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j}
+    \mathit{AES\_KEY}_{i,j}\;\parallel\;\mathit{HMAC\_KEY}_{i,j}\;\parallel\;\mathit{AES\_IV}_{i,j}
     &= \operatorname{HKDF}\left(0,M_{i,j},\text{``OLM\_KEYS"},80\right)
 \end{aligned}
 \]
 
-The plain-text is encrypted with AES-256, using the key \(AES\_KEY_{i,j}\)
-and the IV \(AES\_IV_{i,j}\) to give the cipher-text, \(X_{i,j}\).
+The plain-text is encrypted with AES-256, using the key \(\mathit{AES\_KEY}_{i,j}\)
+and the IV \(\mathit{AES\_IV}_{i,j}\) to give the cipher-text, \(X_{i,j}\).
 
 Then the entire message (including the Version Byte and all Payload Bytes) are
 passed through [HMAC-SHA-256][]. The first 8 bytes of the MAC are appended to the message.

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/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: