From a07f2d0f230ad1a1688758c59c4c0d5d7b0c38b1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Sep 2025 15:59:26 -0600 Subject: [PATCH] Part 1: Invites --- content/client-server-api/_index.md | 2 +- content/server-server-api.md | 12 ++++ data/api/server-server/invites-v1.yaml | 59 ++++++++++++++-- data/api/server-server/invites-v2.yaml | 74 +++++++++++++++----- data/event-schemas/schema/m.room.member.yaml | 6 +- 5 files changed, 130 insertions(+), 23 deletions(-) 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/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index b1771018..82edddf3 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -71,9 +71,20 @@ 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. items: $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml example: @@ -119,13 +130,23 @@ paths: "sender": "@someone:example.org", "unsigned": { "invite_room_state": [ + { + "type": "m.room.create", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "version": "12" + }, + "remaining_fields": "are formatted according to the room version specification" + }, { "type": "m.room.name", "sender": "@bob:example.org", "state_key": "", "content": { "name": "Example Room" - } + }, + "remaining_fields": "are formatted according to the room version specification" }, { "type": "m.room.join_rules", @@ -133,7 +154,8 @@ paths: "state_key": "", "content": { "join_rule": "invite" - } + }, + "remaining_fields": "are formatted according to the room version specification" } ] }, @@ -168,6 +190,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..743c88e8 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -72,9 +72,20 @@ 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. items: $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml example: @@ -112,22 +123,33 @@ paths: "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.create", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "version": "12" + }, + "remaining_fields": "are formatted according to the room version specification" + }, + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + }, + "remaining_fields": "are formatted according to the room version specification" + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + }, + "remaining_fields": "are formatted according to the room version specification" } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" - } - } ] }, "content": { @@ -151,6 +173,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/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index e768c906..824d64d9 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,7 +148,8 @@ 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