Merge fe6c97f498 into fa78688f57

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2291.feature

@@ -0,0 +1 @@
+Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356).

changelogs/server_server/newsfragments/2284.clarification

@@ -0,0 +1 @@
+Specified input validation for PDUs passed to federation membership endpoints.

content/client-server-api/_index.md

@@ -3898,6 +3898,7 @@ that profile.
 | [Guest Access](#guest-access)                              | Optional  | Optional | Optional | Optional | Optional |
 | [Moderation Policy Lists](#moderation-policy-lists)        | Optional  | Optional | Optional | Optional | Optional |
 | [OpenID](#openid)                                          | Optional  | Optional | Optional | Optional | Optional |
+| [Recently used emoji](#recently-used-emoji)                | Optional  | Optional | Optional | Optional | Optional |
 | [Reference Relations](#reference-relations)                | Optional  | Optional | Optional | Optional | Optional |
 | [Reporting Content](#reporting-content)                    | Optional  | Optional | Optional | Optional | Optional |
 | [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
@@ -3999,5 +4000,6 @@ systems.
 {{% cs-module name="Spaces" filename="spaces" %}}
 {{% cs-module name="Event replacements" filename="event_replacements" %}}
 {{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}
+{{% cs-module name="Recently used emoji" filename="recent_emoji" %}}
 {{% cs-module name="Threading" filename="threading" %}}
 {{% cs-module name="Reference relations" filename="reference_relations" %}}

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

@@ -0,0 +1,40 @@
+### Recently used emoji
+
+{{% added-in v="1.18" %}}
+
+This module enables clients to track a user's cumulated emoji usage across different
+devices. The data is stored in the [`m.recent_emoji`](#mrecent_emoji)
+global [account data](#client-config) and can, among other things, be used to
+generate recommendations in emoji pickers.
+
+#### Events
+
+{{% event event="m.recent_emoji" %}}
+
+#### Client behaviour
+
+What exactly constitutes trackable emoji usage is left as an implementation detail
+for clients. It is RECOMMENDED to include sending emoji in both messages and
+annotations.
+
+When an emoji is used, the sending client moves (or adds) it to the beginning of
+the `recent_emoji` array and increments (or initializes) its counter. This keeps
+the array ordered by last usage time which facilitates evaluating the data. How
+exactly the client evaluates and uses the collected data is deliberately left
+unspecified.
+
+To prevent excessive growth of the event as new emoji are being used, clients
+SHOULD limit the length of the `recent_emoji` array by dropping elements from
+its end. A RECOMMENDED maximum length is 100 emoji.
+
+To enable future extension, clients MUST tolerate and preserve array elements
+within `recent_emoji` regardless of whether they understand or support the
+contained `emoji` value. This means ignoring entries with unrecognised values
+of `emoji` when deciding what to display to the user while retaining them when
+modifying the array (unless the modification is for truncation).
+
+To prevent undefined behavior, clients SHOULD remove array elements that
+don't conform to the event schema such as elements with negative counters.
+
+
+

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

@@ -0,0 +1,29 @@
+# Copyright 2026 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.
+
+title: Recent Emoji
+type: object
+properties:
+  emoji:
+    type: string
+    description: The Unicode emoji as string.
+    example: 🚀
+  total:
+    type: number
+    description: |-
+      The number of times the emoji has been used.
+      MUST be non-negative and smaller than 2^53.
+required:
+  - emoji
+  - total

data/api/server-server/invites-v1.yaml

@@ -172,6 +172,17 @@ paths:
                   }
         "400":
           description: |-
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `invite`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not a user ID on the receiving server.
+
+            Servers MUST apply the validation above to the invite event before
+            signing it regardless of room version.
+
             The `M_MISSING_PARAM` error code is used to indicate one or more of
             the following:
 
@@ -186,9 +197,9 @@ paths:
             Servers MAY apply the validation above to room versions 1 through 11,
             and SHOULD apply the validation above to all other room versions.
 
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
+            is associated with a Client-Server API request, the Client-Server API
+            request SHOULD fail with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:

data/api/server-server/invites-v2.yaml

@@ -154,6 +154,17 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `invite`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not a user ID on the receiving server.
+
+            Servers MUST apply the validation above to the invite event before
+            signing it regardless of room version.
+
             The `M_MISSING_PARAM` error code is used to indicate one or more of
             the following:
 
@@ -168,9 +179,9 @@ paths:
             Servers MAY apply the validation above to room versions 1 through 11,
             and SHOULD apply the validation above to all other room versions.
 
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request
+            is associated with a Client-Server API request, the Client-Server API
+            request SHOULD fail with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:

data/api/server-server/joins-v1.yaml

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the join event will be for.
+          description: The user ID the join event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -388,6 +388,43 @@ paths:
                       }
                     }
                   ]
+        "400":
+          description: |-
+            The request is invalid in some way.
+
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `join`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the join event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a join event."
+                  }
+        "403":
+          description: |-
+            The room that the joining server is attempting to join does not permit the user
+            to join.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room"
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/joins-v2.yaml

@@ -247,6 +247,16 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `join`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the join event.
+
             New in `v1.2`, the following error conditions might happen:
 
             If the room is [restricted](/client-server-api/#restricted-rooms)

data/api/server-server/knocks.yaml

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the knock event will be for.
+          description: The user ID the knock event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -330,6 +330,27 @@ paths:
                       "$ref": "./examples/invite_or_knock_state.json"
                     }
                   }
+        "400":
+          description: |-
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The knock event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `knock`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the knock event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a knock event."
+                  }
         "403":
           description: |-
             The knocking server or user is not permitted to knock on the room, such as when the

data/api/server-server/leaving-v1.yaml

@@ -36,7 +36,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the leave event will be for.
+          description: The user ID the leave event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -249,6 +249,27 @@ paths:
                     200,
                     {}
                   ]
+        "400":
+          description: |-
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `leave`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the leave event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/leaving-v2.yaml

@@ -134,6 +134,27 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: |-
+            The `M_INVALID_PARAM` error code is used to indicate one or more of the following:
+
+            * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * The event type is not `m.room.member`.
+            * The `membership` field inside the event content is not `leave`.
+            * The event sender is not a user ID on the origin server.
+            * The `state_key` is not equal to the `sender`.
+
+            Servers MUST apply the validation above to the leave event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/event-schemas/examples/m.recent_emoji.yaml

@@ -0,0 +1,16 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.recent_emoji",
+  "content": {
+    "recent_emoji": [{
+      "emoji": "🤔",
+      "total": 19
+    }, {
+      "emoji": "👍",
+      "total": 7
+    }, {
+      "emoji": "😅",
+      "total": 84
+    }]
+  }
+}

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

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "title": "Recent Emoji Event",
+  "description": "Lets clients maintain a list of recently used emoji.",
+  "allOf": [{
+    "$ref": "core-event-schema/event.yaml"
+  }],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["m.recent_emoji"]
+    },
+    "content": {
+      "type": "object",
+      "properties": {
+        "recent_emoji": {
+          "description": "The list of recently used emoji. Elements in the list are ordered descendingly by last usage time.",
+          "type": "array",
+          "items": {
+            "$ref": "../../api/client-server/definitions/recent_emoji.yaml"
+          },
+        }
+      },
+      "required": ["recent_emoji"]
+    }
+  },
+  "required": ["type", "content"]
+}