matrix-org · turt2live · Jul 27, 2026 · Aug 1, 2025 · Aug 1, 2025 · Aug 1, 2025
diff --git a/proposals/4319-room-member-events-for-invite-knock-sync-response.md b/proposals/4319-room-member-events-for-invite-knock-sync-response.md
@@ -0,0 +1,220 @@
+# MSC4139: Room member events for invite and knock rooms in the `/sync` response
+
+In the Client-Server API, the response of the [`GET /sync`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync)
+endpoint, the `events` array in the `invite_state` for rooms under `invite` and in the `knock_state`
+for rooms under `knock` are defined as containing the stripped state of the room.
+
+This stripped state comes over federation, via the
+[`PUT /invite`](https://spec.matrix.org/v1.15/server-server-api/#put_matrixfederationv2inviteroomideventid)
+and [`PUT /send_knock`](https://spec.matrix.org/v1.15/server-server-api/#put_matrixfederationv1send_knockroomideventid)
+endpoints in the Server-Server API.
+
+In the definition of the [stripped state][stripped-state]
+it is recommended to contain the following state events:
+
+- `m.room.create`
+- `m.room.name`
+- `m.room.avatar`
+- `m.room.topic`
+- `m.room.join_rules`
+- `m.room.canonical_alias`
+- `m.room.encryption`
+
+Although these events are useful to be able to present information about the room, they don't
+contain information about the invite/knock event itself.
+
+The following information can be useful for clients:
+
+- The sender of the invite, including their display name and avatar, to present to the user.
+- The time of the invite or knock, to present to the user or to sort the invite/knock list by
+  recency.
+- Whether an invite event was preceded by a knock, if the client wants to auto-accept invites that
+  come from knocking.
+
+Furthermore, appservices may want to deduplicate this event received via `/sync` from events
+received via `/_matrix/app/v1/transactions`, so they need to be able to identify it uniquely. The
+easiest way to do this is to use its `event_id`.
+
+> [!NOTE]
+> The initial purpose of this proposed change was to specify behavior that has been implemented for
+> a long time in some homeserver implementations and that clients already rely on, but that is
+> currently unspecced.
+>
+> Because current homeserver implementations differ there is no clear consensus on what this
+> solution should actually look like, so the purpose of this MSC has shifted to propose a change
+> that still includes all the same data necessary for clients but offers a more coherent API.
+
+
+## Proposal
+
+### `m.room.member` event with a `membership` of `invite` or `knock`
+
+For clients to be able to get all the details about an invite or knock, a `state` key is added to
+the [`InvitedRoom`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync_response-200_invited-room)
+and [`KnockedRoom`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync_response-200_knocked-room)
+objects. It uses the same format as the [`State`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync_response-200_state)
+object in [`JoinedRoom`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync_response-200_joined-room)
+and MUST include the `m.room.member` event that was created during the invite or knock process, in
+the [`ClientEventWithoutRoomID`](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3sync_response-200_clienteventwithoutroomid)
+format. This SHOULD be the only event present in the `events` array.
+
+> [!NOTE]
+> Making it mandatory makes sense because this event is the reason why the room appears in `invite`
+> or `knock` in the first place. Providing the full event format allows clients to access details
+> like the `origin_server_ts`, the `event_id` or the `unsigned` object.
+
+> [!IMPORTANT]
+> This MSC doesn't change the format of this event over the Server-Server API. This only proposes to
+> forward more information to clients that has always been available to homeservers.
+
+For compatibility with the current client implementations, homeservers SHOULD also continue to
+include this event in the `events` array of the `invite_state` or `knock_state` in the same format
+as in `State` for a time limited to 1 spec release after this proposal is released in a new spec
+version.
+
+For compatibility with the current server implementations, clients MAY look for the invite/knock
+`m.room.member` event in `invite_state` or `knock_state` as a fallback if it is not found under the
+`state` key.
+
+> [!NOTE]
+> The example for the response of `GET /sync` includes the stripped `m.room.member` event although
+> it is not specified.
+
+### `m.room.member` event of the `sender` of the invite
+
+The [list of events that should be included in the stripped state][stripped-state] over the
+Client-Server and Server-Server APIs is extended with the `m.room.member` event of the `sender` of
+the invite for rooms that the user has been invited to. This event has the same format as other
+events in the stripped state, i.e. the full event format according to the room version in the
+Server-Server API endpoints, and the `Stripped state event` format in the Client-Server API's
+`/sync` endpoint. This event allows clients to be able to display information about the sender of
+an invite, like their display name or avatar.
+
+> [!NOTE]
+> For a knock the target user and the sender MUST be the same user according to the
+> [authorisation rules](https://spec.matrix.org/v1.15/rooms/v11/#authorisation-rules), so the
+> `m.room.member` event of the sender is the same as in the previous section and it doesn't need to
+> be provided separately. 
+
+### Example
+
+Example of an `InvitedState` object:
+
+```json
+{
+  "state": {
+    "events": [
+      {
+        "content": {
+          "membership": "invite",
+          "displayname": "Alice"
+        },
+        "type": "m.room.member",
+        "state_key": "@alice:example.org",
+        "sender": "@bob:example.org",
+        "event_id": "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg",
+        "origin_server_ts": 1432735824653,
+        "unsigned": {
+          "prev_content": {
+            "membership": "knock",
+            "displayname": "Alice"
+          }
+        }
+      }
+    ]
+  },
+  "invite_state": {
+    "events": [
+      {
+        "content": {
+          "membership": "invite",
+          "displayname": "Alice"
+        },
+        "type": "m.room.member",
+        "state_key": "@alice:example.org",
+        "sender": "@bob:example.org",
+      },
+      {
+        "content": {
+          "m.federate": true,
+          "predecessor": {
+            "event_id": "$something:example.org",
+            "room_id": "!oldroom:example.org"
+          },
+          "room_version": "11"
+        },
+        "sender": "@example:example.org",
+        "state_key": "",
+        "type": "m.room.create",
+      },
+      {
+        "content": {
+          "membership": "join",
+          "displayname": "Bob"
+        },
+        "type": "m.room.member",
+        "state_key": "@bob:example.org",
+        "sender": "@bob:example.org",
+      },
+    ]
+  }
+}
+```
+
+### Dependencies
+
+Although it is not considered a dependency of this MSC, if this is accepted the new `/sync`
+endpoint introduced in [MSC4286: Simplified Sliding Sync](https://github.com/matrix-org/matrix-spec-proposals/pull/4186)
+should also be updated for invited and knocked rooms to include the full invite/knock
+`m.room.member` event in `required_state` and the inviter's `m.room.member` event in
+`stripped_state`.
+
+
+## Potential issues
+
+This changes the current expectations of clients by moving the `m.room.member` event outside of the
+`invite_state` and `knock_state` so they will need to adapt to the change. This is mitigated by
+encouraging servers to keep sending the event in these objects.
+
+By showing more information about the sender of an invite, users might be subject to undesirable
+content like abusive language or images. Mitigating this is out of scope of this MSC, and other MSCs
+exist for this, like [MSC4278](https://github.com/matrix-org/matrix-spec-proposals/pull/4278).
+
+
+## Alternatives
+
+We could put the full `m.room.member` event in the `events` array of the `invite_state` or
+`knock_state`, but mixing event formats in a list is undesirable.
+
+We could put the full `m.room.member` event under another key in the `invite_state` or
+`knock_state`, the `state` key was chosen for its similarity with other room objects. It will also
+allow to add more events using their full format in the future if needed.
+
+We could add more fields to the stripped state format, but given all the fields that are needed for
+the different use cases, it would mean that the stripped state has the same format as normal state.
+Using the full event format might give the wrong idea that this state has been validated by the
+homeserver, which is currently not possible
+(see [this discussion in MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311#discussion_r2274781824)).
+Besides, those fields are really only necessary for the `invite` or `knock` `m.room.member` event.
+
+This doesn't solve the case where a room doesn't have an `m.room.name` or `m.room.canonical_alias`
+state event, so [its display name should be computed using the room summary](https://spec.matrix.org/v1.15/client-server-api/#calculating-the-display-name-for-a-room).
+This is left to another MSC.
+
+
+## Security considerations
+
+No potential security issues are known to the author.
+
+
+## Unstable prefix
+
+While this proposal is not considered stable, implementations should use `org.matrix.msc4319.state`
+for the `state` key in `InvitedRoom` and `KnockedRoom`.
+
+
+## Dependencies
+
+None.
+
+[stripped-state]: https://spec.matrix.org/v1.15/client-server-api/#stripped-state