Merge 7b3083885b into 643a6dca2d

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Richard van der Hoff <richard@matrix.org>

changelogs/client_server/newsfragments/2122.feature

@@ -0,0 +1 @@
+Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2125.feature

@@ -0,0 +1 @@
+Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/server_server/newsfragments/2125.feature

@@ -0,0 +1 @@
+Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

content/client-server-api/_index.md

@@ -2878,6 +2878,10 @@ that are not `world_readable` regardless of their visibility.
 
 {{% http-api spec="client-server" api="list_public_rooms" %}}
 
+### Room Summaries
+
+{{% http-api spec="client-server" api="room_summary" %}}
+
 ## User Data
 
 ### User Directory

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

@@ -1512,40 +1512,11 @@ message.
 
 The plaintext payload is of the form:
 
-```json
+{{% definition path="api/client-server/definitions/olm_payload" %}}
-{
-  "type": "<type of the plaintext event>",
-  "content": "<content for the plaintext event>",
-  "sender": "<sender_user_id>",
-  "recipient": "<recipient_user_id>",
-  "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
-  },
-  "keys": {
-    "ed25519": "<sender_ed25519_key>"
-  }
-}
-```
 
 The type and content of the plaintext message event are given in the
 payload.
 
-Other properties are included in order to prevent an attacker from
-publishing someone else's curve25519 keys as their own and subsequently
-claiming to have sent messages which they didn't. `sender` must
-correspond to the user who sent the event, `recipient` to the local
-user, and `recipient_keys` to the local ed25519 key.
-
-Clients must confirm that the `sender_key` property in the cleartext
-`m.room.encrypted` event body, and the `keys.ed25519` property in the
-decrypted plaintext, match the keys returned by
-[`/keys/query`](#post_matrixclientv3keysquery) for
-the given user. Clients must also verify the signature of the keys from the
-`/keys/query` response. Without this check, a client cannot be sure that
-the sender device owns the private part of the ed25519 key it claims to
-have in the Olm payload. This is crucial when the ed25519 key corresponds
-to a verified device.
-
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully
 decrypted a message. For these purposes, a session that has not received
@@ -1555,6 +1526,68 @@ maximum number of olm sessions that it will maintain for each device,
 and expiring sessions on a Least Recently Used basis. The maximum number
 of olm sessions maintained per device should be at least 4.
 
+###### Validation of incoming decrypted events
+
+{{% changed-in v="1.15" %}} Existing checks made more explicit, and checks for `sender_device_keys` added.
+
+After decrypting an incoming encrypted event, clients MUST apply the
+following checks:
+
+1.  The `sender` property in the decrypted content must match the
+    `sender` of the event.
+2.  The `keys.ed25519` property in the decrypted content must match
+    the `sender_key` property in the cleartext `m.room.encrypted`
+    event body.
+3.  The `recipient` property in the decrypted content must match
+    the user ID of the local user.
+4.  The `recipient_keys.ed25519` property in the decrypted content
+    must match the client device's [Ed25519 signing key](#device-keys).
+5.  Where `sender_device_keys` is present in the decrypted content:
+    1.  `sender_device_keys.user_id` must also match the `sender`
+        of the event.
+    2.  `sender_device_keys.keys.ed25519:<device_id>` must also match
+        the `sender_key` property in the cleartext `m.room.encrypted`
+        event body.
+    3.  `sender_device_keys.keys.curve25519:<device_id>` must match
+        the Curve25519 key used to establish the Olm session.
+    4.  The `sender_device_keys` structure must have a valid signature
+        from the key with ID `ed25519:<device_id>` (i.e., the sending
+        device's Ed25519 key).
+
+Any event that does not comply with these checks MUST be discarded.
+
+###### Verification of the sending user for incoming events
+
+{{% added-in v="1.15" %}}
+
+In addition, for each Olm session, clients MUST verify that the
+Curve25519 key used to establish the Olm session does indeed belong
+to the claimed `sender`. This requires a signed "device keys" structure
+for that Curve25519 key, which can be obtained in one of two ways:
+
+1.  An Olm message may be received with a `sender_device_keys` property
+    in the decrypted content.
+2.  The keys are returned via a [`/keys/query`](#post_matrixclientv3keysquery)
+    request. Note that both the Curve25519 key **and** the Ed25519 key in
+    the returned device keys structure must match those used in an
+    Olm-encrypted event as above. (In particular, the Ed25519 key must
+    be present in the **encrypted** content of an Olm-encrypted event
+    to prevent an attacker from claiming another user's Curve25519 key
+    as their own.)
+
+Ownership of the Curve25519 key is then established in one of two ways:
+
+1.  Via [cross-signing](#cross-signing). For this to be sufficient, the
+    device keys structure must be signed by the sender's self-signing key,
+    and that self-signing key must itself have been validated (either via
+    [explicit verification](#device-verification) or a "trust on first use" (TOFU) mechanism).
+2.  Via explicit verification of the device's Ed25519 signing key, as
+    contained in the device keys structure. This is no longer recommended.
+
+A failure to complete these verifications does not necessarily mean that
+the session is bogus; however it is the case that there is no proof that
+the claimed sender is accurate, and the user should be warned accordingly.
+
 ###### Recovering from undecryptable messages
 
 Occasionally messages may be undecryptable by clients due to a variety

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

@@ -0,0 +1,88 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C
+#
+# 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.
+
+
+type: object
+title: OlmPayload
+description: |-
+  The plaintext payload of Olm message events.
+properties:
+  type:
+    type: string
+    description: The type of the event.
+  content:
+    type: object
+    description: The event content.
+  sender:
+    type: string
+    description: The user ID of the event sender.
+  recipient:
+    type: string
+    description: The user ID of the intended event recipient.
+  recipient_keys:
+    description: The recipient's signing keys of the encrypted event.
+    $ref: "#/components/schemas/SigningKeys"
+  keys:
+    $ref: "#/components/schemas/SigningKeys"
+    description: The sender's signing keys of the encrypted event.
+  sender_device_keys:
+    $ref: device_keys.yaml 
+    description: The sender's device keys.
+    x-addedInMatrixVersion: "1.15"
+required:
+  - type
+  - content
+  - sender
+  - recipient
+  - recipient_keys
+  - keys
+components:
+  schemas:
+    SigningKeys:
+      type: object
+      title: SigningKeys
+      description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
+      properties:
+        ed25519:
+          type: string
+          description: The Ed25519 public key encoded using unpadded base64.
+      required:
+        - ed25519
+example: {
+  "type": "<type of the plaintext event>",
+  "content": "<content for the plaintext event>",
+  "sender": "<sender_user_id>",
+  "recipient": "<recipient_user_id>",
+  "recipient_keys": {
+    "ed25519": "<our_ed25519_key>"
+  },
+  "keys": {
+    "ed25519": "<sender_ed25519_key>"
+  },
+  "sender_device_keys": {
+    "algorithms": ["<supported>", "<algorithms>"],
+    "user_id": "<user_id>",
+    "device_id": "<device_id>",
+    "keys": {
+      "ed25519:<device_id>": "<sender_ed25519_key>",
+      "curve25519:<device_id>": "<sender_curve25519_key>"
+    },
+    "signatures": {
+      "<user_id>": {
+        "ed25519:<device_id>": "<device_signature>",
+        "ed25519:<ssk_id>": "<ssk_signature>",
+      }
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# 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.
+
+type: object
+title: RoomSummary
+allOf:
+  - $ref: public_rooms_chunk.yaml
+  - type: object
+    properties:
+      room_type:
+        type: string
+        description: The `type` of room (from
+          [`m.room.create`](/client-server-api/#mroomcreate)),
+          if any.
+      allowed_room_ids:
+        type: array
+        items:
+          type: string
+        description: |-
+          If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
+          are specified by the join rules. Empty or omitted otherwise.
+      encryption:
+        type: string
+        enum:
+          - "m.megolm.v1.aes-sha2"
+        description: |-
+          The encryption algorithm to be used to encrypt messages sent in the
+          room.
+      room_version:
+        description: The version of the room.
+        type: string
+
+required:
+  - room_id
+  - num_joined_members
+  - world_readable
+  - guest_can_join

data/api/client-server/room_summary.yaml

@@ -0,0 +1,138 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# 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 Room Summary API
+  version: 1.0.0
+paths:
+  "/room_summary/{roomIdOrAlias}":
+    get:
+      x-addedInMatrixVersion: "1.15"
+      summary: Retrieves a summary for a room.
+      description: |-
+        Retrieves a summary for a room.
+
+        Clients should note that requests for rooms where the user's membership
+        is `invite` or `knock` might yield outdated, partial or even no data
+        since the server may not have access to the current state of the room.
+
+        Servers MAY allow unauthenticated access to this API if at least one of
+        the following conditions holds true:
+
+        - The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
+          `knock_restricted`.
+        - The room has a `world_readable` [history visibility](#room-history-visibility).
+
+        Servers should consider rate limiting federation requests more heavily,
+        if the client is unauthenticated.
+      operationId: getRoomSummary
+      security:
+        - signedRequest: []
+      parameters:
+        - in: path
+          name: roomIdOrAlias
+          description: The room identifier or alias to summarise.
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
+        - in: query
+          name: via
+          description: |-
+            The servers to attempt to request the summary from when
+            the local server cannot generate it (for instance, because
+            it has no local user in the room).
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        "200":
+          description: A summary of the room.
+          content:
+            application/json:
+              schema:
+                description: A summary of the room.
+                allOf:
+                  - $ref: ../client-server/definitions/room_summary.yaml
+                  - type: object
+                    properties:
+                      room_type:
+                        x-addedInMatrixVersion: # Overrides room_summary.yaml
+                      membership:
+                        description: |-
+                          The membership state of the user if the user is joined to the room. Absent
+                          if the API was called unauthenticated.
+                        enum:
+                          - invite
+                          - join
+                          - knock
+                          - leave
+                          - ban
+                        type: string
+                required:
+                  - guest_can_join
+                  - num_joined_members
+                  - room_id
+                  - world_readable
+              examples:
+                response:
+                  value: {
+                    room_id: "!ol19s:bleecker.street",
+                    avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
+                    guest_can_join: false,
+                    name: "CHEESE",
+                    num_joined_members: 37,
+                    topic: "Tasty tasty cheese",
+                    world_readable: true,
+                    join_rule: "public",
+                    room_type: "m.space",
+                    membership: "invite",
+                    encryption: "m.megolm.v1.aes-sha2",
+                    room_version: "9001",
+                  }
+        "404":
+          description: |-
+            The room could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found."
+                  }
+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/space_hierarchy.yaml

@@ -102,15 +102,10 @@ paths:
                        * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
                     items:
                       allOf:
-                        - $ref: definitions/public_rooms_chunk.yaml
+                        - $ref: definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyRoomsChunk
                           properties:
-                            room_type:
-                              type: string
-                              description: The `type` of room (from
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
-                                if any.
                             children_state:
                               type: array
                               description: |-
@@ -130,6 +125,12 @@ paths:
                                         description: The `origin_server_ts` for the event.
                                     required:
                                       - origin_server_ts
+                            allowed_room_ids:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            encryption:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            room_version:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                           required:
                             - children_state
                   next_batch:

data/api/server-server/space_hierarchy.yaml

@@ -61,22 +61,10 @@ paths:
                   room:
                     description: A summary of the room requested.
                     allOf:
-                      - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                      - $ref: ../client-server/definitions/room_summary.yaml
                       - type: object
                         title: SpaceHierarchyParentRoom
                         properties:
-                          room_type:
-                            type: string
-                            description: The `type` of room (from
-                              [`m.room.create`](/client-server-api/#mroomcreate)),
-                              if any.
-                          allowed_room_ids:
-                            type: array
-                            items:
-                              type: string
-                            description: |-
-                              If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
-                              are specified by the join rules. Empty or omitted otherwise.
                           children_state:
                             type: array
                             description: |-
@@ -96,6 +84,10 @@ paths:
                                       description: The `origin_server_ts` for the event.
                                   required:
                                     - origin_server_ts
+                          encryption:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                          room_version:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                         required:
                           - children_state
                   children:
@@ -105,22 +97,14 @@ paths:
                       be excluded.
                     items:
                       allOf:
-                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                        - $ref: ../client-server/definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyChildRoomsChunk
                           properties:
-                            room_type:
+                            encryption:
-                              type: string
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                              description: The `type` of room (from
+                            room_version:
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                                if any.
-                            allowed_room_ids:
-                              type: array
-                              items:
-                                type: string
-                              description: |-
-                                If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
-                                are specified by the join rules. Empty or omitted otherwise.
                   inaccessible_children:
                     type: array
                     items: