MSC4155: Invite filtering

proposals/4155-invite-filtering.md

@@ -0,0 +1,186 @@
+# MSC4155: Invite filtering
+
+Matrix supports ignoring users via the eponymous [module] and the `m.ignored_user_list` account data
+event. This is a nuclear option though and will suppress both invites and room events from the ignored
+users. Additionally, the `m.ignored_user_list` event only allows for block-list configurations that ignore
+specific users but doesn't have a mechanism to ignore entire servers. These shortcomings make the module
+insufficient for use cases such as tightly locked down applications where ignoring needs to be the default
+behaviour.
+
+This proposal generalises the ignoring users [module] to allow filtering invites specifically. The scheme
+outlined below was conceptually borrowed from the [gematik specification].
+
+
+## Proposal
+
+To allow users to configure which other users are allowed to invite them into rooms, a new account data
+event `m.invite_permission_config` is introduced.
+
+```json5
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    // User-level settings
+    "allowed_users": [ "@john:goodguys.org", ... ],
+    "ignored_users": [ ... ],
+    "blocked_users": [ ... ],
+    // Server-level settings
+    "allowed_servers": [ ... ],
+    "ignored_servers": [ ... ],
+    "blocked_servers": [ "*" ] // A feature of all the fields at this level, globs
+  }
+}
+```
+
+All properties in `content` are optional arrays. A missing or `null` property MUST be treated like an
+empty array. The array elements are [glob expressions] to be matched against user IDs and server names,
+respectively.
+
+When evaluating an invite against the contents of `m.invite_permission_config`, implementations MUST
+apply the following order:
+
+1.  Verify the invite against each `*_users` setting: 
+  1.  If it matches `allowed_users`, stop processing and allow.
+  2.  If it matches `ignored_users`, stop processing and ignore.
+  3.  If it matches `blocked_users`, stop processing and block.
+2.  Verify the invite against each `*_servers` setting: 
+  1.  If it matches `allowed_servers`, stop processing and allow.
+  2.  If it matches `ignored_servers`, stop processing and ignore.
+  3.  If it matches `blocked_servers`, stop processing and block.
+3.  Otherwise, allow.
+
+The semantics of "ignore" and "block" follow [MSC4283] which means ignoring hides the invite with no
+feedback to the invite whereas blocking rejects (or refuses, in the case of servers) the invite.
+
+When blocking an inviter, the server must respond to the following endpoints with an error:
+
+- `PUT /_matrix/federation/(v1|v2)/invite/{roomId}/{eventId}`
+- `POST /_matrix/client/v3/rooms/{roomId}/invite`
+- `POST /_matrix/client/v3/createRoom` (checking the `invite` list)
+- `PUT /_matrix/client/v3/rooms/{roomId}/state/m.room.member/{stateKey}` (for invite membership)
+
+The error SHOULD be `M_INVITE_BLOCKED` with a HTTP 403 status code.
+
+When ignoring an invite, these endpoints MUST handle an invite normally as if accepted. However, the server
+MUST not include the invite down client synchronization endpoints such as `GET /_matrix/client/v3/sync` or
+MSC4186's sliding sync endpoint. In addition, these invites MUST be ignored when calculating push notifications.
+
+Otherwise, all other endpoints (such as `GET /_matrix/client/v3/rooms/{roomId}/state`) should work as before. 
+
+Servers are not expected to process these rules for appservice users when calculating events to send down
+`PUT /_matrix/app/v1/transactions`. Appservices are not expected to be run directly by client users, and
+should be able to handle their own spam prevention.
+
+The semantics and order of evaluation enable a number of use cases, for instance:
+
+```json5
+// Invites from everyone
+{
+  "type": "m.invite_permission_config",
+  "content": { }
+}
+
+// No invites at all
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "blocked_servers": [ "*" ]
+  }
+}
+
+// Only invites from goodguys.org
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "allowed_servers": [ "goodguys.org" ],
+    "blocked_servers": [ "*" ]
+  }
+}
+
+// Invites from everyone except badguys.org
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "blocked_servers": [ "badguys.org" ]
+  }
+}
+
+// Only invites from goodguys.org except for @notactuallyguy:goodguys.org
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "blocked_users": [ "@notactuallyguy:goodguys.org" ],
+    "allowed_servers": [ "goodguys.org" ]
+    "blocked_servers": [ "*" ]
+  }
+}
+
+// No invites from badguys.org unless it's @goodguy:badguys.org
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "allowed_users": [ "@goodguy:badguys.org" ],
+    "blocked_servers": [ "badguys.org" ]
+  }
+}
+
+// Only invites from goodguys.org and don't provide feedback to reallybadguys.org
+{
+  "type": "m.invite_permission_config",
+  "content": {
+    "allowed_servers": [ "goodguys.org" ],
+    "ignored_servers": [ "reallybadguys.org" ],
+    "blocked_servers": [ "*" ]
+  }
+}
+```
+
+Servers MUST enforce `m.invite_permission_config` against incoming new invites. Additionally, Servers
+SHOULD apply the config against existing pending invites as well.
+
+
+## Potential issues
+
+Enforcing the permission configuration exclusively on the server means users have no way to review
+processed invites. This is desirable in most cases as a spam protection measure. It does mean, however,
+that if the user has accidentally blocked a good actor and is informed about it through a different
+communication channel, they'll have to update their permission configuration and request a re-invite.
+
+
+## Alternatives
+
+A comprehensive comparison of existing invite filtering proposals may be found in [MSC4192]. The
+present proposal is functionally inferior to some of the alternatives outline there. It does, for
+instance, not cover the change history of the permission config or sharing the config among different
+users. The proposal is, however, a straightforward and easy to implement extension of the existing
+`m.ignored_user_list` mechanism. See also [this comment] for further details. This proposal is additionally
+extensible for further types of blocking in the future. For example, a future MSC could create definitions
+and behaviours to block/ignore/allow invites from contacts, of a particular type (DM, space, etc), 
+to a particular room, or even with given keywords.
+
+
+## Security considerations
+
+None.
+
+
+## Unstable prefix
+
+Until this proposal is accepted into the spec, implementations should refer to `m.invite_permission_config`
+and `m.invite_permission_config_enforced` as `org.matrix.msc4155.invite_permission_config` and
+`org.matrix.msc4155.invite_permission_config_enforced`, respectively. Note that the [gematik specification],
+which predates this MSC, uses an event type of `de.gematik.tim.account.permissionconfig.v1` and
+a different event schema.
+
+The error `M_INVITE_BLOCKED` should be `ORG.MATRIX.MSC4155.M_INVITE_BLOCKED` until this proposal is accepted into the spec.
+## Dependencies
+
+This proposal loosely depends on [MSC4283] for the semantics of "ignore" and "block".
+
+
+[gematik specification]: https://github.com/gematik/api-ti-messenger/blob/9b9f21b87949e778de85dbbc19e25f53495871e2/src/schema/permissionConfig.json
+[glob expressions]: https://spec.matrix.org/v1.14/appendices/#glob-style-matching
+[MSC4192]: https://github.com/matrix-org/matrix-spec-proposals/pull/4192
+[MSC4283]: https://github.com/matrix-org/matrix-spec-proposals/pull/4283
+[module]: https://spec.matrix.org/v1.10/client-server-api/#ignoring-users
+[this comment]: https://github.com/matrix-org/matrix-spec-proposals/pull/4192#discussion_r2025188127