Skip to content

Commit 3ecedfc

Browse files
GnuxieGnuxie
authored
Protections & Capabilities documentation. (#53)
* Protections & Capabilities documentation. * yeah i stand by it. i want this.
1 parent 2df006d commit 3ecedfc

File tree

5 files changed

+143
-4
lines changed

5 files changed

+143
-4
lines changed

‎docs/matrix-protection-suite/_category_.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"label": "Matrix Protection Suite"
3+
}

‎docs/matrix-protection-suite/concepts/_category_.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"label": "Concepts"
3+
}

‎docs/matrix-protection-suite/concepts/protection.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
sidebar_position: 0
3+
sidebar_label: Protections & Capabilities
4+
---
5+
<!--
6+
SPDX-FileCopyrightText: 2024 Gnuxie <Gnuxie@protonmail.com>
7+
8+
SPDX-License-Identifier: CC-BY-SA-4.0
9+
-->
10+
11+
# Protections & Capabilities
12+
13+
:::tip
14+
15+
For a tutorial on how to use protections, please see [the protections
16+
tutorial](../../protections/configuring-protections). This page is for an
17+
advanced explanation of how protections work and what capabilities
18+
are. Intended for room moderators with advanced use cases and
19+
protection developers.
20+
21+
:::
22+
23+
## Overview
24+
25+
A protection is a self contained module that can hook into a variety of
26+
different events and react to them:
27+
28+
* Protections provide functionality that is directly useful to the end
29+
user, often in reaction to other events.
30+
- So for example, in Draupnir, a protection exists to ban room members
31+
in reaction to policies that exist on Draupnir's watched policy lists.
32+
33+
* Protections can be toggled between enabled and disabled at runtime
34+
to dynamically toggle functionality.
35+
- As an example, a community under a targeted attack may wish to
36+
enabled the `JoinWaveShortCircuitProtection` for the duration
37+
of the period, but might want to turn it off if they are
38+
advertising their community or have been featured somehwere.
39+
40+
* Protections have their own independent configuration settings, that
41+
can be changed dynamically at runtime.
42+
- No need to restart the bot to change protection settings. So for
43+
example, tweaking the allowed number of joins in the
44+
`JoinWaveShortCircuitProtection`.
45+
46+
What sets protections apart from library and supporting code is that
47+
supporting code provides protections with the means to fetch information,
48+
and cause effects.
49+
50+
So as another example, library code needs to provide the underlying
51+
functionality to watch policy lists. Library code also needs to
52+
provide the infrastructure to inform protections when policies are
53+
added and removed. Another example is that library code also needs to
54+
provide code for effects, a protection cannot issue room level bans if
55+
there is no supporting code to do that.
56+
57+
### How do protections express their behaviour?
58+
59+
In Draupnir, and the _matrix-protection-suite_, protections express
60+
their behaviour and effects through _capabilities_. As an example, the
61+
`MemberBanSynchronisationProtection`, which is responsible for issuing
62+
room level bans in reaction to policies, uses a capability interface
63+
called `UserConsequences`. When the protection needs to ban a user,
64+
this capability is used to provide the room level bans.
65+
66+
### Why do protections cause effects through capabilities?
67+
68+
Conventionally in software, effects are caused by using _ambient
69+
authority_. This is to say effects are caused directly, by using
70+
authority that is available to the entire application. Draupnir has
71+
access to the entire Matrix account it has been configured to use, and
72+
so conventionally all parts of Draupnir could cause any effect.
73+
Whether that be to shutdown Matrix rooms, ban users, hijack rooms, or
74+
go rogue. Draupnir has the ambient authority to do all these things,
75+
we have to challange this authority and create ways of containing and
76+
auditing it. Because without, any protection that is enabled could
77+
act with the entire authority of Draupnir, to shutdown rooms and ban
78+
users, and this would be very confusing to the end user, especially
79+
when trying to find which protection is causing these effects and why.
80+
81+
Additionally, without describing effects through capability
82+
interfaces, dry running protections or behaviours would require
83+
special cased code to exist in sprinkles throughout the code base, and
84+
would be very fragile to maintain. This was the reality of _Mjolnir_'s
85+
dry-run feature. It became very easy for contributors to forget the
86+
feature existed, or not realise that a behaviour they were creating
87+
should have a special case. Because effects were being implemented
88+
implicitly with the general protection buisness logic.
89+
90+
By using capability interfaces we can make these effects explicit, and
91+
accounting for different modes of operation becomes a first class
92+
feature that is implicit to using capabilities. No special casing or
93+
thought is required to implement a dry-run mode, because we can now
94+
just replace the capabilities that are provided to the protection,
95+
just by matching their interface.
96+
97+
### What is a capability interface?
98+
99+
A capability interface represents a place in the protection for a
100+
specific behaviour. This interface gets used by the protection's code
101+
in place of the _concrete_ (actual, real) capability.
102+
103+
So for example, in the matrix-protection-suite, we use the
104+
`UserConsequences` interface for protections in place of the actual
105+
capability to ban users from rooms.
106+
107+
When a protection is enabled, the protection asks Draupnir for
108+
capabilities matching its capability interfaces. And this allows
109+
Draupnir to choose whether to provide the capability to ban a user, or
110+
instead a capability that simply logs a message when the protection
111+
tried to ban a user. Without causing any other effect.
112+
113+
### What is a capability provider?
114+
115+
A capability provider is essentially a factory that produces a
116+
specific capability for an interface, from an application context,
117+
such as Draupnir. This is essentially used to provide the glue code to
118+
decouple capabilities from the application context. The capability
119+
provider is used by the application context to produce fresh
120+
capabilities for a protection as the protection as enabled. The
121+
capability provider that is used for this purpose is called the
122+
_active_ capability provider.
123+
124+
Capability providers in Draupnir are configurable on a per protection
125+
basis.

‎docs/protections/configuring-protections.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
15
<!--
26
SPDX-FileCopyrightText: 2025 Gnuxie <Gnuxie@protonmail.com>
37
48
SPDX-License-Identifier: CC-BY-SA-4.0
59
-->
610

7-
---
8-
sidebar_position: 1
9-
---
10-
1111
# Configuring protections
1212

1313
:::info

‎docs/protections/protections.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ SPDX-FileCopyrightText: 2024 Gnuxie <Gnuxie@protonmail.com>
99
SPDX-License-Identifier: CC-BY-SA-4.0
1010
-->
1111

12+
:::tip
13+
14+
This is an overview of Draupnir protections, for a more indepth (but
15+
still friendly) explanation, please view [this
16+
page](./matrix-protection-suite/concepts/protection).
17+
18+
:::
19+
1220
# Protections
1321

1422
Protections are plugins or individual modules that work with

0 commit comments

Comments
 (0)