Merge 6656f00bee into 81273df88e

* Use consistent spacing between tables and code blocks

Tables used `4 rem` which is more than the margin above a h2 title, which seems excessive. We change it to `2 rem` which matches the margin of code blocks and info boxes.

We also remove the margin on the last item of a `.rendered-data` block because this is just wasted space.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Adjust spacing around h2 and h3 titles in `.rendered-data`

Given that h2 titles are always preceded by an horizontal rule, we don't need a lot of space to separate them from the previous section.

We also reduce the spacing when a h2 title is followed directly by a h3 title.

Finally, we add a little spacing below both so that tables are less close to the title.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

assets/scss/_styles_project.scss

@@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 3rem 0 .5rem 0;
+    margin: 1.5rem 0 1rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 .75rem 0;
+    margin: 1.5rem 0 1rem 0;
+
+  }
+
+  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + h3 {
+    margin-top: 1rem;
   }
 
   hr {
@@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec
       }
     }
 
-    // add some space between two tables when they are right next to each other
-    & + table {
-        margin-top: 4rem;
-    }
-
     caption {
       caption-side: top;
       color: $dark;
@@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec
     }
   }
 
+  /* Have consistent spacing around tables and examples */
+  table, .highlight {
+    margin-top: 0;
+    margin-bottom: 2rem;
+
+    /* We don't need the margin on the last child of the .rendered-data block */
+    &:last-child {
+      margin-bottom: 0;
+    } 
+  }
+
   pre {
     border: 0;
     border-left: solid 5px $secondary;

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/internal/newsfragments/2081.clarification

@@ -0,0 +1 @@
+Adjust margins in rendered endpoints.

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

@@ -1512,20 +1512,7 @@ message.
 
 The plaintext payload is of the form:
 
-```json
-{
-  "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>"
-  }
-}
-```
+{{% definition path="api/client-server/definitions/olm_payload" %}}
 
 The type and content of the plaintext message event are given in the
 payload.
@@ -1536,15 +1523,19 @@ 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.
+Clients must ensure that the sending 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. To perform
+this check, 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 under the `sender_device_keys`
+property. Additionally, clients MUST also verify the signature of the keys.
+If `sender_device_keys` is absent, clients MUST retrieve the sender's
+keys from [`/keys/query`](#post_matrixclientv3keysquery) instead. This
+will not allow them to verify key ownership if the sending device was
+logged out or had its keys reset since sending the event. Therefore,
+clients MUST populate the `sender_device_keys` property when sending
+events themselves.
 
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully

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>",
+      }
+    }
+  }
+}