diff --git a/changelogs/client_server/newsfragments/2207.feature b/changelogs/client_server/newsfragments/2207.feature new file mode 100644 index 000000000..74c16ddb5 --- /dev/null +++ b/changelogs/client_server/newsfragments/2207.feature @@ -0,0 +1 @@ +Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). diff --git a/changelogs/server_server/newsfragments/2207.feature b/changelogs/server_server/newsfragments/2207.feature new file mode 100644 index 000000000..f4b5ad38c --- /dev/null +++ b/changelogs/server_server/newsfragments/2207.feature @@ -0,0 +1 @@ +`invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 18a9cc27e..fde7d305d 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2818,6 +2818,14 @@ should be represented as stripped state events when possible: * [`m.room.canonical_alias`](#mroomcanonical_alias) * [`m.room.encryption`](#mroomencryption) +{{% changed-in v="1.16" %}} The `m.room.create` event is now **required** in +the following places: +* [`invite_state`](#get_matrixclientv3sync_response-200_invited-room) and + [`knock_state`](#get_matrixclientv3sync_response-200_knocked-room) on + [`/sync`](#get_matrixclientv3sync) responses. +* On [`m.room.member`](#mroommember) events, the `invite_room_state` + and `knock_room_state` under `unsigned` on the event. + {{% boxes/note %}} Clients should inspect the list of stripped state events and not assume any particular event is present. The server might include events not described @@ -2848,6 +2856,12 @@ events are not signed and could theoretically be modified, or outdated due to updates not being sent. {{% /boxes/warning %}} +{{% boxes/warning %}} +{{% added-in v="1.16" %}} Servers cannot pass through what they receive over +federation to clients as stripped state. Servers are expected to prune the events +into the stripped state schema below before passing the details onto clients. +{{% /boxes/warning %}} + {{% event-fields event_type="stripped_state" %}} ### Size limits diff --git a/content/server-server-api.md b/content/server-server-api.md index e98d2e4c6..3e4f87f3a 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -945,6 +945,18 @@ Note that invites are used to indicate that knocks were accepted. As such, receiving servers should be prepared to manually link up a previous knock to an invite if the invite event does not directly reference the knock. +{{% boxes/note %}} +{{% added-in v="1.16" %}} `invite_room_state` MUST now have its entries formatted +according to the room's version (see [room version specification](/rooms)). However, +servers SHOULD consider their local ecosystems before returning the described +`400 M_MISSING_PARAM` error code. While migrating, servers SHOULD warn about +invites which fail the validation rather than error in room versions 1 through 11. +All invites to other room versions which fail validation SHOULD result in an error. + +The specification suggests that servers finish their migration no later than +January 2026, though servers may extend this as required to support their users. +{{% /boxes/note %}} + {{% http-api spec="server-server" api="invites-v1" %}} {{% http-api spec="server-server" api="invites-v2" %}} diff --git a/data/api/server-server/examples/invite_or_knock_state.json b/data/api/server-server/examples/invite_or_knock_state.json new file mode 100644 index 000000000..416d19582 --- /dev/null +++ b/data/api/server-server/examples/invite_or_knock_state.json @@ -0,0 +1,9 @@ +[ + {"$ref": "./minimal_pdu.json"}, + { + "type": "m.room.create", + "content": { + "see_room_version_spec": "The event format changes depending on the room version." + } + } +] \ No newline at end of file diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index b1771018b..beb44b849 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -71,13 +71,32 @@ paths: properties: invite_room_state: type: array + x-changedInMatrixVersion: + "1.16": | + `m.room.create` and format requirements were added. description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. + A list of state events to help the receiver of the invite identify the room. + Translated as [stripped state events](/client-server-api/#stripped-state) + over the Client-Server API. + + MUST contain the `m.room.create` event for the room. All events listed + MUST additionally be formatted according to the room version specification. + + Servers might need to apply validation to the `invite_room_state` depending + on room version. See the `400 M_MISSING_PARAM` error definition for more + information. + + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml - example: - $ref: ../../event-schemas/examples/invite_room_state.json + type: object + title: PDU + properties: {} + description: |- + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. type: object required: true responses: @@ -118,24 +137,7 @@ paths: "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" - } - } - ] + "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"} }, "content": { "membership": "invite" @@ -168,6 +170,35 @@ paths: "errcode": "M_FORBIDDEN", "error": "User cannot invite the target user." } + "400": + description: |- + The `M_MISSING_PARAM` error code is used to indicate one or more of + the following: + + * The `m.room.create` event is missing from `invite_room_state`. + * One or more entries in `invite_room_state` are not formatted according + to the room's version. + * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events). + * One or more events does not reside in the same room as the invite. + Note: Some room versions may require calculating the room ID for an + event rather than relying on the presence of `room_id`. + + 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. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_MISSING_PARAM", + "error": "Create event not among invite state entries." + } servers: - url: "{protocol}://{hostname}{basePath}" variables: diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 6ac8bb3e3..7b71b4725 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -72,13 +72,32 @@ paths: $ref: definitions/invite_event.yaml invite_room_state: type: array + x-changedInMatrixVersion: + "1.16": | + `m.room.create` and format requirements were added. description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. + A list of state events to help the receiver of the invite identify the room. + Translated as [stripped state events](/client-server-api/#stripped-state) + over the Client-Server API. + + MUST contain the `m.room.create` event for the room. All events listed + MUST additionally be formatted according to the room version specification. + + Servers might need to apply validation to the `invite_room_state` depending + on room version. See the `400 M_MISSING_PARAM` error definition for more + information. + + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml - example: - $ref: ../../event-schemas/examples/invite_room_state.json + type: object + title: PDU + properties: {} + description: |- + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. required: - room_version - event @@ -111,24 +130,7 @@ paths: "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" - } - } - ] + "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"} }, "content": { "membership": "invite" @@ -151,6 +153,24 @@ paths: The error should be passed through to clients so that they may give better feedback to users. + + The `M_MISSING_PARAM` error code is used to indicate one or more of + the following: + + * The `m.room.create` event is missing from `invite_room_state`. + * One or more entries in `invite_room_state` are not formatted according + to the room's version. + * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events). + * One or more events does not reside in the same room as the invite. + Note: Some room versions may require calculating the room ID for an + event rather than relying on the presence of `room_id`. + + 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. content: application/json: schema: diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index 01bfa637f..380920857 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -293,19 +293,41 @@ paths: knock_room_state: type: array items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: object + title: PDU + properties: {} + description: |- + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. + x-changedInMatrixVersion: + "1.16": | + `m.room.create` and format requirements were added. description: |- - A list of [stripped state events](/client-server-api/#stripped-state) - to help the initiator of the knock identify the room. + A list of state events to help the initiator of the knock identify + the room. Translated as [stripped state events](/client-server-api/#stripped-state) + over the Client-Server API. + + MUST contain the `m.room.create` event for the room. All events + listed MUST additionally be formatted according to the room + version specification. + + Entries which are [improperly signed](/server-server-api/#validating-hashes-and-signatures-on-received-events) + or formatted SHOULD be removed by the server prior to supplying + them over the Client-Server API. + + Note that events have a different format depending on the room + version - check the [room version specification](/rooms) for + precise event formats. example: - $ref: ../../event-schemas/examples/knock_room_state.json + "$ref": "./examples/invite_or_knock_state.json" required: - knock_room_state examples: response: value: { "knock_room_state": { - "$ref": "../../event-schemas/examples/knock_room_state.json" + "$ref": "./examples/invite_or_knock_state.json" } } "403": diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index e768c9064..75510d51c 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -137,6 +137,9 @@ properties: - type: object properties: invite_room_state: + x-changedInMatrixVersion: + "1.16": | + `m.room.create` was made a required event type for stripped state. description: |- A subset of the state of the room at the time of the invite, if `membership` is `invite`. Note that this state is informational, and SHOULD NOT be trusted; once the client has @@ -145,16 +148,21 @@ properties: they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name` - SHOULD be included. + SHOULD be included. The `m.room.create` event MUST be included, though MAY be missing if + the server hasn't updated to support the Matrix 1.16 specification. items: $ref: "core-event-schema/stripped_state.yaml" type: array knock_room_state: + x-changedInMatrixVersion: + "1.16": | + `m.room.create` was made a required event type for stripped state. description: |- A subset of the state of the room at the time of the knock, if `membership` is `knock`. This has the same restrictions as `invite_room_state`. If they are set on the room, at least the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, `m.room.name`, - and `m.room.encryption` SHOULD be included. + and `m.room.encryption` SHOULD be included. The `m.room.create` event MUST be included, + though MAY be missing if the server hasn't updated to support the Matrix 1.16 specification. items: $ref: "core-event-schema/stripped_state.yaml" type: array