diff --git a/changelogs/client_server/newsfragments/2207.feature b/changelogs/client_server/newsfragments/2207.feature new file mode 100644 index 00000000..74c16ddb --- /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 00000000..f4b5ad38 --- /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 18a9cc27..6726e537 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2810,7 +2810,7 @@ fresh state can be acquired from a join. Stripped state should contain some or all of the following state events, which should be represented as stripped state events when possible: -* [`m.room.create`](#mroomcreate) +* [`m.room.create`](#mroomcreate) ({{% changed-in v="1.16" %}} required on invites and knocks) * [`m.room.name`](#mroomname) * [`m.room.avatar`](#mroomavatar) * [`m.room.topic`](#mroomtopic) diff --git a/content/server-server-api.md b/content/server-server-api.md index e98d2e4c..3e4f87f3 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/stripped_state.json b/data/api/server-server/examples/stripped_state.json new file mode 100644 index 00000000..416d1958 --- /dev/null +++ b/data/api/server-server/examples/stripped_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 b1771018..c8e411f6 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -71,13 +71,33 @@ 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 + type: object + properties: {} + description: |- + 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/invite_room_state.json + $ref: ./examples/stripped_state.json type: object required: true responses: @@ -118,24 +138,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/stripped_state.json"} }, "content": { "membership": "invite" @@ -168,6 +171,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 6ac8bb3e..fd6790f5 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -72,13 +72,33 @@ 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 + type: object + properties: {} + description: |- + 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/invite_room_state.json + $ref: ./examples/stripped_state.json required: - room_version - event @@ -111,24 +131,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/stripped_state.json"} }, "content": { "membership": "invite" @@ -151,6 +154,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 01bfa637..6994f609 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -293,19 +293,40 @@ paths: knock_room_state: type: array items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: object + 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/stripped_state.json" required: - knock_room_state examples: response: value: { "knock_room_state": { - "$ref": "../../event-schemas/examples/knock_room_state.json" + "$ref": "./examples/stripped_state.json" } } "403": diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index e768c906..75510d51 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