Merge a0cc3f30a9 into 2b68fd935c

Signed-off-by: Logan Devine <logan@zirco.dev>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

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

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/mutual_rooms`, as per [MSC2666](https://github.com/matrix-org/matrix-spec-proposals/pull/2666).

changelogs/olm_megolm/newsfragments/2387.clarification

@@ -0,0 +1 @@
+Update link from whispersystems.org to signal.org in the olm documentation

content/client-server-api/_index.md

@@ -4302,6 +4302,7 @@ that profile.
 | [Third-party Networks](#third-party-networks)              | Optional  | Optional | Optional | Optional | Optional |
 | [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
 | [Invite permission](#invite-permission)                    | Optional  | Optional | Optional | Optional | Optional |
+| [Mutual Rooms](#mutual-rooms)                              | Optional  | Optional | Optional | Optional | Optional |
 
 *Please see each module for more details on what clients need to
 implement.*
@@ -4392,3 +4393,4 @@ systems.
 {{% cs-module name="Recently used emoji" filename="recent_emoji" %}}
 {{% cs-module name="Threading" filename="threading" %}}
 {{% cs-module name="Reference relations" filename="reference_relations" %}}
+{{% cs-module name="Mutual Rooms" filename="mutual_rooms" %}}

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

@@ -0,0 +1,19 @@
+### Mutual Rooms
+
+{{% added-in v="1.19" %}}
+
+{{% http-api spec="client-server" api="mutual_rooms" %}}
+
+#### 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 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.
+
+Batch tokens generated by this endpoint SHOULD be valid for at least 10 minutes, after which,
+tokens can expire. Expired tokens SHOULD be handled similar to invalid tokens, and return
+a 400 response. When a client uses batch tokens, servers MAY omit rooms that the user joined
+after the first token was generated.

content/olm-megolm/olm.md

@@ -5,7 +5,7 @@ type: docs
 ---
 
 An implementation of the double cryptographic ratchet described by
-https://whispersystems.org/docs/specifications/doubleratchet/.
+https://signal.org/docs/specifications/doubleratchet/.
 
 ## Notation
 
@@ -320,11 +320,11 @@ Can be sent to olm at matrix.org.
 ## Acknowledgements
 
 The ratchet that Olm implements was designed by Trevor Perrin and Moxie
-Marlinspike - details at https://whispersystems.org/docs/specifications/doubleratchet/. Olm is
+Marlinspike - details at https://signal.org/docs/specifications/doubleratchet/. Olm is
 an entirely new implementation written by the Matrix.org team.
 
 [Curve25519]: http://cr.yp.to/ecdh.html
-[Triple Diffie-Hellman]: https://whispersystems.org/blog/simplifying-otr-deniability/
+[Triple Diffie-Hellman]: https://signal.org/blog/simplifying-otr-deniability/
 [HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
 [HKDF-SHA-256]: https://tools.ietf.org/html/rfc5869
 [HMAC-SHA-256]: https://tools.ietf.org/html/rfc2104

data/api/client-server/mutual_rooms.yaml

@@ -0,0 +1,127 @@
+# Copyright 2026 Logan Devine <logan@zirco.dev>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Mutual Rooms API
+  version: 1.0.0
+paths:
+  /mutual_rooms:
+    get:
+      summary: Get the list of rooms that the user shares with another user.
+      description: |-
+        Get the list of rooms that the user shares with another user. The
+        server will return a list of room IDs that the user shares with the
+        specified `user_id`.
+      operationId: getMutualRooms
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: user_id
+          required: true
+          description: The MXID of the user to check for mutual rooms with.
+          example: "@alice:example.com"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+        - in: query
+          name: from
+          required: false
+          description: |-
+            A pagination token from a previous result. This should be a `next_batch` result from
+            a previous call to this endpoint. If not provided, the server will return the first
+            batch of results.
+          example: next_batch_token
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            A list of room IDs that the user shares with the specified user.
+            If the provided `user_id` is not a valid user, the server MUST return an empty list of rooms.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - joined
+                  - count
+                properties:
+                  joined:
+                    type: array
+                    description: |-
+                      A list of room IDs where both the authenticated user and `user_id` have a
+                      membership of type `join`.
+                    items:
+                      type: string
+                      format: mx-room-id
+                      pattern: "^!"
+                      example: "!OGEhHVWSdvArJzumhm:matrix.org"
+                  count:
+                    type: integer
+                    description: |-
+                      The number of such rooms. This is the total count even if the response is
+                      batched and `joined` doesn't include all rooms. This MAY be inaccurate
+                      if the server is unable to calculate the exact number of rooms.
+                    example: 1
+                  next_batch:
+                    type: string
+                    description: |-
+                      A pagination token to retrieve the next batch of results. This will be absent
+                      if there are no more results to return.
+                    example: next_batch_token
+
+        "400":
+          description: |-
+            Part of the request was invalid. The `from` token provided was invalid or expired,
+            the `user_id` parameter was missing, [non-compliant](/appendices/#historical-user-ids),
+            or was the sender's own user ID.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "The user ID provided was invalid"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Mutual Rooms
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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: