51 lines
No EOL
3.8 KiB
Markdown
51 lines
No EOL
3.8 KiB
Markdown
# FiftyFiftyOneArizona's Matrix-Based Reporting System
|
|
|
|
This file documents a currently under development system which collects and distributes ICE sightings in a secure, decentralized, and resilient way using Matrix.
|
|
|
|
At the time of writing, this system is still being planned and is far from reaching maturity. However, the first version of this document (and the first commit to the repository holding it) will contain a fully complete explanation on how the system works.
|
|
|
|
The decision to make the specification as rigid as it is comes from the knowledge that this system will be relied upon by people to not be kidnapped and illegally sent to an El Salvadorian gulag. However, the specification is rather simple and only aims to be a standardized way to collect and distribute information, with a heavy focus on real-word locations in the U.S.
|
|
|
|
## Why Matrix
|
|
|
|
Matrix is more or less uncontested as a medium to distribute this information. Matrix has an already-built ecosystem of servers, clients, bots, and SDKs which lets people easily add in nearly any functionality they want. Matrix is also distributed, fault-tolerant, secured with SSL, and fully authenticated. We hope that more organizations will spin up their own Matrix server and contribute information to this system.
|
|
|
|
## Event Format
|
|
|
|
Every event is a text message (`m.text`). This is done so that real people can contribute information directly to the system, and so that Maubot works with it nicely.
|
|
|
|
Every message has a format similar to that of a typical UNIX-style command-line program:
|
|
|
|
```
|
|
!report <region> human readable message
|
|
```
|
|
|
|
The bang (exclamation mark) at the beginning of the message is there so the system works with Maubot.
|
|
|
|
The human readable message can be anything. Such as "ICE Spotted at 500 E Fake St."
|
|
|
|
The region field is a single token (no spaces in it) which designates the state or territory that the report is for. This is a required field. This requirement and its granularity have undergone quite a bit of scrutiny. Its purpose is to allow for consumers of this information to filter by their general location without being too granular. The specific choice of state came down to most 50501 groups being organized around each state.
|
|
|
|
This is **not case sensitive**, but again it must be a single word/token. Just concatenate the words for state or territory names with multiple words. Like NorthDakota or puertoRico or NATIONAL.
|
|
|
|
A more complete example might be:
|
|
|
|
```
|
|
!report arizona ICE seen at 500 N Central Ave in Phoenix`
|
|
```
|
|
|
|
## Input-Output & Authentication
|
|
|
|
This system is intended to be used in a Matrix room where different Matrix accounts are adding and consuming information. For simplicity, I will stick to the adders and consumers terminology. The adders can be bots or people, whereas the consumers are intended to be bots only.
|
|
|
|
Additionally, consumer bots would probably want to only pay attention to certain region designations. Additionally, consumer bots may only want to pay attention to certain users. All Maubot plugins that FiftyFiftyOne
|
|
|
|
As an example, a person could be the only adder, with two consumers—say a bot that forwards it to NTFY, and another one which forwards it to Signal.
|
|
|
|
When the person enters in `!report arizona Some Report` the two consumer bots should process it as follows:
|
|
|
|
1. Split the message into the region designator `arizona`, and the string after it.
|
|
2. If the bot is set to only pay attention to specific region designators, check that `arizona` is in that set. Silently ignore the message if it isn't.
|
|
3. If the bot is set to only pay attention to specific users for the region designator `arizona`, check if the sending user is in that set. Silently ignore the message if it isn't.
|
|
4. Run through its own code to process the message as it sees fit.
|
|
5. Optionally reply to the message saying that it was processed. |