Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-14 18:13:47 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge 8ea6744ae0 into f92c3579ac

Browse source
This commit is contained in:
Kévin Commaille 2026-01-30 18:47:36 +00:00 committed by GitHub
parent f92c3579ac 8ea6744ae0
commit 75d7bb66a1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 123 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2305.feature Normal file
View file

@ -0,0 +1 @@
Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380).

2
content/client-server-api/_index.md
View file

@ -4071,6 +4071,7 @@ that profile.
| [Sticker Messages](#sticker-messages) | Optional | Optional | Optional | Optional | Optional |
| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
| [Threading](#threading) | Optional | Optional | Optional | Optional | Optional |
| [Invite permission](#invite-permission) | Optional | Optional | Optional | Optional | Optional |
*Please see each module for more details on what clients need to
implement.*
@ -4159,3 +4160,4 @@ systems.
{{% cs-module name="Recently used emoji" filename="recent_emoji" %}}
{{% cs-module name="Threading" filename="threading" %}}
{{% cs-module name="Reference relations" filename="reference_relations" %}}
{{% cs-module name="Invite permission" filename="invite_permission" %}}

52
content/client-server-api/modules/invite_permission.md Normal file
View file

@ -0,0 +1,52 @@
### Invite permission
{{% added-in v="1.18" %}}
Users may want to control who is allowed to invite them to new rooms. This module defines how
clients and servers can implement invite permission.
#### Events
{{% event event="m.invite_permission_config" %}}
#### Client behaviour
To reject invites from all users automatically, clients MUST add an [`m.invite_permission_config`](#minvite_permission_config)
event in the user's [account data](#client-config) with the `default_action` property set to
`block`. To stop rejecting all invites, the same event without the `default_action` property MUST be
added to the account data.
When the `default_action` field is unset, other parts of the specification might still have effects
on invites seen by clients, like [ignoring users](#ignoring-users).
When sending an invite to a user that blocks invites, clients SHOULD receive an error response with
the `M_INVITE_BLOCKED` error code.
#### Server behaviour
When invites to a given user are blocked, the user's homeserver MUST respond to the following
endpoints with an HTTP 403 status code, with the Matrix error code `M_INVITE_BLOCKED`, if the user
is invited:
* [`PUT /_matrix/federation/v1/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv1inviteroomideventid)
* [`PUT /_matrix/federation/v2/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv2inviteroomideventid)
* [`POST /_matrix/client/v3/rooms/{roomId}/invite`](#post_matrixclientv3roomsroomidinvite)
* [`POST /_matrix/client/v3/createRoom`](#post_matrixclientv3createroom), due to a user in the
`invite` list. It is possible for one of the invited users to be rejected whilst the room creation
as a whole succeeds.
* [`PUT /_matrix/client/v3/rooms/{roomId}/state/m.room.member/{stateKey}`](#put_matrixclientv3roomsroomidstateeventtypestatekey),
when the `membership` is set to `invite`.
In addition, existing events already in the database MUST NOT be served over client synchronisation
endpoints such as [`GET /sync`](#get_matrixclientv3sync). Invite events received over federation
should likewise not be served over `GET /sync` requests.
Servers MAY return any suppressed invite events over `GET /sync` if invite blocking is later
disabled.
Other endpoints, such as [`GET /rooms/{roomId}/state`](#get_matrixclientv3roomsroomidstate), are not
affected by invite blocking: invite events are returned as normal.
The Application Services API is also unaffected by invite blocking: invite events are sent over
[`PUT /_matrix/app/v1/transactions/{txnId}`](/application-service-api/#put_matrixappv1transactionstxnid).

12
data/api/client-server/create_room.yaml
View file

@ -250,7 +250,6 @@ paths:
}
"400":
description: |-
The request is invalid. A meaningful `errcode` and description
error text will be returned. Example reasons for rejection include:
@ -274,6 +273,17 @@ paths:
application/json:
schema:
$ref: definitions/errors/error.yaml
"403":
description: |-
Creating the room is not allowed.
{{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
indicate that one of the homeservers of the invited users rejected
the invite due to [invite blocking](/client-server-api/#invite-permission).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
tags:
- Room creation
servers:

10
data/api/client-server/inviting.yaml
View file

@ -83,7 +83,7 @@ paths:
value: {}
"400":
description: |-
The request is invalid. A meaningful `errcode` and description
error text will be returned. Example reasons for rejection include:
@ -99,12 +99,18 @@ paths:
$ref: definitions/errors/error.yaml
"403":
description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
You do not have permission to invite the user to the room. A
meaningful `errcode` and description error text will be returned.
Example reasons for rejections are:
- The invitee has been banned from the room.
- The invitee is already a member of the room.
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
{{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
indicate that the homeserver rejected the invite due to
[invite blocking](/client-server-api/#invite-permission).
content:
application/json:
schema:

8
data/api/client-server/room_state.yaml
View file

@ -116,7 +116,13 @@ paths:
"error": "The alias '#hello:example.org' does not point to this room."
}
"403":
description: The sender doesn't have permission to send the event into the room.
description: |-
The sender doesn't have permission to send the event into the room.
{{% added-in v="1.18"%}} If the `eventType` is `m.room.member` and
the `membership` is `invite`, the `M_INVITE_BLOCKED` error code is
used to indicate that the homeserver rejected the invite due to
[invite blocking](/client-server-api/#invite-permission).
content:
application/json:
schema:

8
data/api/server-server/invites-v1.yaml
View file

@ -155,11 +155,17 @@ paths:
]
"403":
description: |-
The invite is not allowed. This could be for a number of reasons, including:
The invite is not allowed.
The `M_FORBIDDEN` error code is used to indicate one of the following:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
{{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
indicate that the homeserver rejected the invite due to
[invite blocking](/client-server-api/#invite-permission).
content:
application/json:
schema:

8
data/api/server-server/invites-v2.yaml
View file

@ -192,11 +192,17 @@ paths:
}
"403":
description: |-
The invite is not allowed. This could be for a number of reasons, including:
The invite is not allowed.
The `M_FORBIDDEN` error code is used to indicate one of the following:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
{{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
indicate that the homeserver rejected the invite due to
[invite blocking](/client-server-api/#invite-permission).
content:
application/json:
schema:

7
data/event-schemas/examples/m.invite_permission_config.yaml Normal file
View file

@ -0,0 +1,7 @@
{
"$ref": "core/event.json",
"type": "m.invite_permission_config",
"content": {
"default_action": "block"
}
}

21
data/event-schemas/schema/m.invite_permission_config.yaml Normal file
View file

@ -0,0 +1,21 @@
---
$schema: https://json-schema.org/draft/2020-12/schema
allOf:
- $ref: core-event-schema/event.yaml
- title: Invite Permission
type: object
description: |-
The permission configuration for receiving invites for the current account.
properties:
content:
type: object
properties:
default_action:
type: string
description: |-
When set to `block`, the user does not wish to receive *any* room invites, and they
should be rejected automatically by the homeserver.
A missing, invalid or unsupported value means that the user wants to receive invites
as normal. Other parts of the specification might still have effects on invites, like
[ignoring users](/client-server-api/#ignoring-users).