From a7721b7b5827d449734cbb858abff73301080788 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 7 Feb 2026 20:53:12 +0200 Subject: [PATCH] Move validation to endpoint description --- data/api/server-server/invites-v1.yaml | 53 ++++++++++++------------- data/api/server-server/invites-v2.yaml | 55 +++++++++++++------------- data/api/server-server/joins-v1.yaml | 19 +++++---- data/api/server-server/joins-v2.yaml | 21 +++++----- data/api/server-server/knocks.yaml | 19 ++++----- data/api/server-server/leaving-v1.yaml | 19 ++++----- data/api/server-server/leaving-v2.yaml | 19 ++++----- 7 files changed, 103 insertions(+), 102 deletions(-) diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index 31cc4eeb..5ec95d5e 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -36,6 +36,30 @@ paths: Also note that if the remote homeserver is already in the room, it will receive the invite event twice; once through this endpoint, and again through a [federation transaction](/server-server-api/#transactions). + + Servers MUST apply certain validation to ensure they don't accidentally sign non-invite + events from a malicious server. The `M_MISSING_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. + + The `M_MISSING_PARAM` error code is also used to indicate one or more of the following + problems in the `invite_room_state` field: + + * 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 `invite_room_state` validation to room versions 1 through 11, + and SHOULD apply the validation to all other room versions. operationId: sendInviteV1 security: - signedRequest: [] @@ -172,34 +196,7 @@ 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: - - * 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` 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. + The request is invalid in some way. content: application/json: schema: diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 9c3a474b..72b69e10 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -40,6 +40,30 @@ paths: Also note that if the remote homeserver is already in the room, it will receive the invite event twice; once through this endpoint, and again through a [federation transaction](/server-server-api/#transactions). + + Servers MUST apply certain validation to ensure they don't accidentally sign non-invite + events from a malicious server. The `M_MISSING_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. + + The `M_MISSING_PARAM` error code is also used to indicate one or more of the following + problems in the `invite_room_state` field: + + * 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 `invite_room_state` validation to room versions 1 through 11, + and SHOULD apply the validation to all other room versions. operationId: sendInviteV2 security: - signedRequest: [] @@ -154,34 +178,9 @@ 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: - - * 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` 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. + 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/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index ae62411f..6cb30c7d 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -238,6 +238,15 @@ paths: **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** + + The receiving server MUST apply certain validation before accepting the event. + 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`. operationId: sendJoinV1 security: - signedRequest: [] @@ -391,16 +400,6 @@ 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: diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 51687fb5..0f23ca94 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -38,6 +38,15 @@ paths: **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** + + The receiving server MUST apply certain validation before accepting the event. + 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`. operationId: sendJoinV2 security: - signedRequest: [] @@ -247,15 +256,9 @@ 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. + 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. New in `v1.2`, the following error conditions might happen: diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index 6d0e2d78..13596598 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -204,6 +204,15 @@ paths: **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** + + The receiving server MUST apply certain validation before accepting the event. + 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`. operationId: sendKnock security: - signedRequest: [] @@ -332,15 +341,7 @@ paths: } "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. + The request is invalid in some way. content: application/json: schema: diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index b36ac6ac..beb3776c 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -153,6 +153,15 @@ paths: **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** + + The receiving server MUST apply certain validation before accepting the event. + 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`. operationId: sendLeaveV1 security: - signedRequest: [] @@ -251,15 +260,7 @@ paths: ] "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. + The request is invalid in some way. content: application/json: schema: diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 019ff1b3..33dab2d4 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -38,6 +38,15 @@ paths: **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** + + The receiving server MUST apply certain validation before accepting the event. + 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`. operationId: sendLeaveV2 security: - signedRequest: [] @@ -136,15 +145,7 @@ paths: 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. + The request is invalid in some way. content: application/json: schema: