Merge a0cc3f30a9 into bf5fbc9945

* use User ID type in OlmPayload and DeviceKeys

Signed-off-by: Johanna Stuber <johannas@element.io>

* add newsfragment

Signed-off-by: Johanna Stuber <johannas@element.io>

---------

Signed-off-by: Johanna Stuber <johannas@element.io>

changelogs/client_server/newsfragments/2357.clarification

@@ -0,0 +1 @@
+Clarify which tokens can be used in `from` or `to` in `GET /rooms/{roomId}/relations/{eventId}`.

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

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

@@ -1940,7 +1940,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/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).

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_payload.yaml

@@ -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/relations.yaml

@@ -22,13 +22,13 @@ paths:
       description: |-
         Retrieve all of the child events for a given parent event.
 
-        Note that when paginating the `from` token should be "after" the `to` token in
-        terms of topological ordering, because it is only possible to paginate "backwards"
-        through events, starting at `from`.
+        Note that, in terms of topological ordering, the `from` token should be "after"
+        the `to` token when `dir=b`, and should be "before" the `to` token when `dir=f`.
 
-        For example, passing a `from` token from page 2 of the results, and a `to` token
-        from page 1, would return the empty set. The caller can use a `from` token from
-        page 1 and a `to` token from page 2 to paginate over the same range, however.
+        For example, with `dir=b`, passing a `from` token from page 2 of the results, and
+        a `to` token from page 1, would return the empty set. The caller can use a `from`
+        token from page 1 and a `to` token from page 2 to paginate over the same range,
+        however.
       operationId: getRelatingEvents
       security:
         - accessTokenQuery: []
@@ -80,13 +80,13 @@ paths:
         Retrieve all of the child events for a given parent event which relate to the parent
         using the given `relType`.
 
-        Note that when paginating the `from` token should be "after" the `to` token in
-        terms of topological ordering, because it is only possible to paginate "backwards"
-        through events, starting at `from`.
+        Note that, in terms of topological ordering, the `from` token should be "after"
+        the `to` token when `dir=b`, and should be "before" the `to` token when `dir=f`.
 
-        For example, passing a `from` token from page 2 of the results, and a `to` token
-        from page 1, would return the empty set. The caller can use a `from` token from
-        page 1 and a `to` token from page 2 to paginate over the same range, however.
+        For example, with `dir=b`, passing a `from` token from page 2 of the results, and
+        a `to` token from page 1, would return the empty set. The caller can use a `from`
+        token from page 1 and a `to` token from page 2 to paginate over the same range,
+        however.
       operationId: getRelatingEventsWithRelType
       security:
         - accessTokenQuery: []
@@ -142,13 +142,13 @@ paths:
         Retrieve all of the child events for a given parent event which relate to the parent
         using the given `relType` and have the given `eventType`.
 
-        Note that when paginating the `from` token should be "after" the `to` token in
-        terms of topological ordering, because it is only possible to paginate "backwards"
-        through events, starting at `from`.
+        Note that, in terms of topological ordering, the `from` token should be "after"
+        the `to` token when `dir=b`, and should be "before" the `to` token when `dir=f`.
 
-        For example, passing a `from` token from page 2 of the results, and a `to` token
-        from page 1, would return the empty set. The caller can use a `from` token from
-        page 1 and a `to` token from page 2 to paginate over the same range, however.
+        For example, with `dir=b`, passing a `from` token from page 2 of the results, and
+        a `to` token from page 1, would return the empty set. The caller can use a `from`
+        token from page 1 and a `to` token from page 2 to paginate over the same range,
+        however.
       operationId: getRelatingEventsWithRelTypeAndEventType
       security:
         - accessTokenQuery: []
@@ -252,9 +252,14 @@ components:
         The pagination token to start returning results from. If not supplied, results
         start at the most recent topological event known to the server.
 
-        Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
-        `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
-        or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
+        If `dir=b`, then `from` can be `next_batch` from a previous call, or a
+        `prev_batch` token from a [`/sync`] or a `start` token from a [`/messages`].
+
+        If `dir=f`, then `from` can be `prev_batch` from a previous call, or a
+        `next_batch` token from a [`/sync`] or an `end` token from a [`/messages`].
+
+        [`/messages`]: /client-server-api/#get_matrixclientv3roomsroomidmessages
+        [`/sync`]: /client-server-api/#get_matrixclientv3sync
       required: false
       example: page2_token
       schema:
@@ -266,8 +271,11 @@ components:
         The pagination token to stop returning results at. If not supplied, results
         continue up to `limit` or until there are no more events.
 
-        Like `from`, this can be a previous token from a prior call to this endpoint
-        or from `/messages` or `/sync`.
+        Like `from`, this can be a previous token from a prior call to this endpoint,
+        or from [`/sync`] or [`/messages`].
+
+        [`/messages`]: /client-server-api/#get_matrixclientv3roomsroomidmessages
+        [`/sync`]: /client-server-api/#get_matrixclientv3sync
       required: false
       example: page3_token
       schema:

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