Merge b0f08c871a 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/appendices/newsfragments/2396.clarification

@@ -0,0 +1 @@
+Clarify that clients must avoid producing ambiguous matrix.to URIs. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2404.breaking

@@ -0,0 +1 @@
+Clients are now supposed to follow 30x redirects from `/.well-known/matrix/client` as per [MSC4402](https://github.com/matrix-org/matrix-spec-proposals/pull/4402).

changelogs/client_server/newsfragments/2407.clarification

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

changelogs/client_server/newsfragments/2412.clarification

@@ -0,0 +1 @@
+Use the User ID type in OlmPayload and DeviceKeys.

changelogs/client_server/newsfragments/2417.clarification

@@ -0,0 +1 @@
+Wording improvements and spelling fixes. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2418.clarification

@@ -0,0 +1 @@
+Rename OlmPayload to OlmPlaintext to avoid confusion with Olm message Payload Bytes.

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/appendices.md

@@ -887,20 +887,22 @@ https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
 
 The identifier may be a room ID, room alias, or user ID. The
 extra parameter is only used in the case of permalinks where an event ID
-is referenced. The matrix.to URI, when referenced, must always start
+is referenced. The matrix.to URI, when referenced, MUST always start
 with `https://matrix.to/#/` followed by the identifier.
 
 The `<additional arguments>` and the preceding question mark are
-optional and only apply in certain circumstances, documented below.
+OPTIONAL and only apply in certain circumstances, documented below.
 
-Clients should not rely on matrix.to URIs falling back to a web server
-if accessed and instead should perform some sort of action within the
+Clients SHOULD NOT rely on matrix.to URIs falling back to a web server
+if accessed and instead SHOULD perform some sort of action within the
 client. For example, if the user were to click on a matrix.to URI for a
-room alias, the client may open a view for the user to participate in
+room alias, the client MAY open a view for the user to participate in
 the room.
 
 The components of the matrix.to URI (`<identifier>` and
 `<extra parameter>`) MUST be percent-encoded as per RFC 3986.
+Failure to do so will result in downstream software misinterpreting
+the links as invalid/not turning them into clickable links in UI.
 
 Examples of matrix.to URIs are:
 

content/client-server-api/_index.md

@@ -429,6 +429,7 @@ Instead, they can be reached via HTTPS on the [server name](/appendices/#server-
 
 Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
 as per the [CORS](#web-browser-clients) section in this specification.
+{{% added-in v="1.20" %}} Servers SHOULD also ensure that each 30x redirect, if any, offers such CORS headers.
 {{% /boxes/note %}}
 
 The flow for auto-discovery is as follows:
@@ -437,6 +438,7 @@ The flow for auto-discovery is as follows:
     Matrix ID at the first colon.
 2.  Extract the hostname from the server name as described by the [grammar](/appendices/#server-name).
 3.  Make a GET request to `https://hostname/.well-known/matrix/client`.
+    {{% added-in v="1.20" %}} 30x redirects SHOULD be followed, however redirection loops should be avoided.
     1.  If the returned status code is 404, then `IGNORE`.
     2.  If the returned status code is not 200, or the response body is
         empty, then `FAIL_PROMPT`.
@@ -3660,7 +3662,7 @@ The actual aggregation format depends on the `rel_type`.
 
 When an event is served to the client through the APIs listed below, a
 `m.relations` property is included under `unsigned` if the event has child
-events which can be aggregated and point at it. The `m.relations` property is
+events which can be aggregated. The `m.relations` property is
 an object keyed by `rel_type` and value being the type-specific aggregated
 format for that `rel_type`. This `m.relations` property is known as a "bundled
 aggregation".

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

@@ -1623,9 +1623,8 @@ In such cases where the current history visibility setting does not allow sharin
 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:
+In all other cases, before inviting Bob to a room, Alice's client SHOULD share all available shareable keys.
+It does this by constructing and sending 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.
@@ -1772,12 +1771,9 @@ Messages with type 1 can only be decrypted with an existing session. If
 there is no matching session, the client must treat this as an invalid
 message.
 
-The plaintext payload is of the form:
+The plaintext corresponding to the "Cipher-Text" in an an [Olm message](/olm-megolm/olm/#normal-messages) is of the form:
 
-{{% definition path="api/client-server/definitions/olm_payload" %}}
-
-The type and content of the plaintext message event are given in the
-payload.
+{{% definition path="api/client-server/definitions/olm_plaintext" %}}
 
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully
@@ -1950,7 +1946,7 @@ As of `v1.3`, the `sender_key` and `device_id` keys are **deprecated**. They
 SHOULD continue to be sent, however they MUST NOT be used to verify the
 message's source.
 
-Clients MUST NOT store or lookup sessions using the `sender_key` or `device_id`.
+Clients MUST NOT store or look up sessions using the `sender_key` or `device_id`.
 
 In a future version of the specification the keys can be removed completely,
 including for sending new messages.

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/client-server-api/modules/threading.md

@@ -191,7 +191,7 @@ Note that, as in the example above, child events of the `latest_event` should
 themselves be aggregated and included under `m.relations` for that event. The
 server should be careful to avoid loops, though loops are not currently
 possible due to `m.thread` not being permitted to target an event with an
-`m.relates_to` property.
+`m.relates_to` property with a `rel_type`.
 
 `count` is simply the number of events using `m.thread` as a `rel_type` pointing to the target event.
 It does not include events sent by [ignored users](#ignoring-users).

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/device_keys.yaml

@@ -20,6 +20,8 @@ properties:
     description: |-
       The ID of the user the device belongs to. Must match the user ID used
       when logging in.
+    format: mx-user-id
+    pattern: "^@"
     example: "@alice:example.com"
   device_id:
     type: string

data/api/client-server/definitions/olm_plaintext.yaml

@@ -14,9 +14,9 @@
 
 
 type: object
-title: OlmPayload
+title: OlmPlaintext
 description: |-
-  The plaintext payload of an event encrypted using Olm.
+  The plaintext of an event encrypted using Olm.
 properties:
   type:
     type: string
@@ -27,9 +27,13 @@ properties:
   sender:
     type: string
     description: The user ID of the event sender.
+    format: mx-user-id
+    pattern: "^@"
   recipient:
     type: string
     description: The user ID of the intended event recipient.
+    format: mx-user-id
+    pattern: "^@"
   recipient_keys:
     description: The recipient's signing keys of the encrypted event.
     $ref: "#/components/schemas/SigningKeys"

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/client-server/wellknown.yaml

@@ -1,4 +1,5 @@
 # Copyright 2018 New Vector Ltd
+# Copyright 2026 Hagen Echzell
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -20,7 +21,11 @@ paths:
     get:
       summary: Gets Matrix server discovery information about the domain.
       description: |-
-        Gets discovery information about the domain. The file may include
+        Gets discovery information about the domain.
+        {{% added-in v="1.20" %}} Clients SHOULD follow 30x redirects, carefully
+        avoiding redirect loops, and use normal X.509 certificate validation.
+        
+        The file may include
         additional keys, which MUST follow the Java package naming convention,
         e.g. `com.example.myapp.property`. This ensures property names are
         suitably namespaced for each application and reduces the risk of

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:

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

@@ -13,7 +13,7 @@ description: |-
   [Olm](/client-server-api/#molmv1curve25519-aes-sha2).
 
   The `sender_device_keys` property in the [Olm
-  plaintext](/client-server-api/#definition-olmpayload) MUST be
+  plaintext](/client-server-api/#definition-olmplaintext) MUST be
   populated. Recipients SHOULD ignore `m.room_key_bundle` messages which omit
   them.
 properties: