1#pragma once
2
3/// @file
4/// @brief policy rules for room moderation
5///
6/// With Matrix being an open network where anyone can participate, a very wide range of content
7/// exists and it is important that users are empowered to select which content they wish to see,
8/// and which content they wish to block. By extension, room moderators and server admins should
9/// also be able to select which content they do not wish to host in their rooms and servers.
10///
11/// The protocol’s position on this is one of neutrality: it should not be deciding what content is
12/// undesirable for any particular entity and should instead be empowering those entities to make
13/// their own decisions. As such, a generic framework for communicating “moderation policy lists” or
14/// “moderation policy rooms” is described. Note that this module only describes the data structures
15/// and not how they should be interpreting: the entity making the decisions on filtering is best
16/// positioned to interpret the rules how it sees fit.
17///
18/// Moderation policy lists are stored as room state events. There are no restrictions on how the
19/// rooms can be configured (they could be public, private, encrypted, etc).
20///
21/// There are currently 3 kinds of entities which can be affected by rules: user, server, and room.
22/// All 3 are described with m.policy.rule.<kind> state events. The state_key for a policy rule is
23/// an arbitrary string decided by the sender of the rule.
24///
25/// Rules contain recommendations and reasons for the rule existing. The reason is a human-readable
26/// string which describes the recommendation. Currently only one recommendation, m.ban, is
27/// specified.
28
29#include <optional>
30#include <string_view>
31
32#if __has_include(<nlohmann/json_fwd.hpp>)
33#include <nlohmann/json_fwd.hpp>
34#else
35#include <nlohmann/json.hpp>
36#endif
37
38namespace mtx {
39namespace events {
40namespace state {
41namespace policy_rule {
42
43//! A recommendation of how to handle the entity.
44namespace recommendation {
45/// @brief a recommendation to ban an entity
46///
47/// When this recommendation is used, the entities affected by the rule should be banned from
48/// participation where possible. The enforcement of this is deliberately left as an implementation
49/// detail to avoid the protocol imposing its opinion on how the policy list is to be interpreted.
50inline constexpr std::string_view ban = "m.ban";
51}
52
53//! Content of the `m.policy.rule.*` events.
54//
55//! The entity described by the state events can contain * and ? to match zero or more and one or
56//! more characters respectively. Note that rules against rooms can describe a room ID or room alias
57//! - the subscriber is responsible for resolving the alias to a room ID if desired.
58struct Rule
59{
60 //! Required: The entity affected by this rule. Glob characters * and ? can be used to match
61 //! zero or more and one or more characters respectively.
62 std::string entity;
63
64 //! Required: The human-readable description for the recommendation.
65 std::string reason;
66
67 //! Required: The suggested action to take. Currently only m.ban is specified.
68 std::string recommendation;
69
70 friend void from_json(const nlohmann::json &obj, Rule &create);
71 friend void to_json(nlohmann::json &obj, const Rule &create);
72};
73
74struct UserRule : public Rule
75{
76 friend void from_json(const nlohmann::json &obj, UserRule &create);
77 friend void to_json(nlohmann::json &obj, const UserRule &create);
78};
79struct RoomRule : public Rule
80{
81 friend void from_json(const nlohmann::json &obj, RoomRule &create);
82 friend void to_json(nlohmann::json &obj, const RoomRule &create);
83};
84struct ServerRule : public Rule
85{
86 friend void from_json(const nlohmann::json &obj, ServerRule &create);
87 friend void to_json(nlohmann::json &obj, const ServerRule &create);
88};
89} // namespace policy_rule
90} // namespace state
91} // namespace events
92} // namespace mtx
93