# 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 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 COLORADO. A more complete example might be: ``` !report arizona ICE seen at 500 N Central Ave in Phoenix` ``` ### Region List In order to be extra careful, here's an exhaustive list of all reigons for The United States, listed in alphabetical order of their proper names. | Name | Reigon Name | Shortcode | | ------------------------ | ---------------------- | --------- | | Nationwide | __global__ | AL | | Alabama | Alabama | AL | | Alaska | Alaska | AK | | American Samoa | AmericanSamoa | AS | | Arizona | Arizona | AZ | | Arkansas | Arkansas | AR | | California | California | CA | | Colorado | Colorado | CO | | Connecticut | Connecticut | CT | | Delaware | Delaware | DE | | District of Columbia | WashingtonDC | DC | | Florida | Florida | FL | | Georgia | Georgia | GA | | Guam | Guam | GU | | Hawaii | Hawaii | HI | | Idaho | Idaho | ID | | Illinois | Illinois | IL | | Indiana | Indiana | IN | | Iowa | Iowa | IA | | Kansas | Kansas | KS | | Kentucky | Kentucky | KY | | Louisiana | Louisiana | LA | | Maine | Maine | ME | | Maryland | Maryland | MD | | Massachusetts | Massachusetts | MA | | Michigan | Michigan | MI | | Minnesota | Minnesota | MN | | Mississippi | Mississippi | MS | | Missouri | Missouri | MO | | Montana | Montana | MT | | Nebraska | Nebraska | NE | | Nevada | Nevada | NV | | New Hampshire | NewHampshire | NH | | New Jersey | NewJersey | NJ | | New Mexico | NewMexico | NM | | New York | NewYork | NY | | North Carolina | NorthCarolina | NC | | North Dakota | NorthDakota | ND | | Northern Mariana Islands | NorthernMarianaIslands | MP | | Ohio | Ohio | OH | | Oklahoma | Oklahoma | OK | | Oregon | Oregon | OR | | Pennsylvania | Pennsylvania | PA | | Puerto Rico | PuertoRico | PR | | Rhode Island | RhodeIsland | RI | | South Carolina | SouthCarolina | SC | | South Dakota | SouthDakota | SD | | Tennessee | Tennessee | TN | | Texas | Texas | TX | | Utah | Utah | UT | | U.S. Virgin Islands | USVirginIslands | VI | | Vermont | Vermont | VT | | Virginia | Virginia | VA | | Washington | Washington | WA | | West Virginia | WestVirginia | WV | | Wisconsin | Wisconsin | WI | | Wyoming | Wyoming | WY | And here's a convenient one-line list of the shortcodes: ``` all al ak as az ar ca co ct de dc fl ga gu hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd mp oh ok or pa pr ri sc sd tn tx ut vi vt va wa wv wi wy ``` ## 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 or react to the message saying that it was processed. ## Maubot Specifics Here's some sample code and configuration layout to make plugin development easier. ## Sample Configuration ```yaml # Which regions the bot should pay attention to # This can be either an empty list to allow any sender for this reigon, # or can have a specified whitelist of senders allowed_regions: foo: - "@reports:fiftyfiftyonerarizona.org" bar: - "@reports:example.org" - "@reports:example.com" buzz: aaa: ``` ```yaml # Bot-specific configurations per region # The fields in each specific reigon should be the same, but their values should differ # In this case (with NTFY), the bot should post notifications for each reigon # to a different topic. region_configs: __global__: # Where and how the plugin will send the data to server_url: "https://ntfy.sh" server_topic: "changeme2" # If the plugin should use a username and password to send notifications server_use_authentication: true server_username: "no" server_password: "way" foo: # Where and how the plugin will send the data to server_url: "https://ntfy.sh" server_topic: "changeme" # If the plugin should use a username and password to send notifications server_use_authentication: true server_username: "no" server_password: "way" bar: # Where and how the plugin will send the data to server_url: "https://ntfy.sh" server_topic: "changeme2" # If the plugin should use a username and password to send notifications server_use_authentication: true server_username: "no" server_password: "way" ``` ## Helper Functions ```python # Checks if a sender if allowed to send for a particular region def validateSender(self, region: str, sender: str): # Check that config value exists if not self.config["allowed_regions"]: return False # Check that region is allowed if not region in self.config["allowed_regions"]: return False # All senders allowed for this region if len(self.config["allowed_regions"][region]) == 0: return True # Check that sender is allowed for region if not sender in self.config["allowed_regions"][region]: return False return True ``` ```python # Does the necesary config checks for the given event # Returns list of regions to process (strings) # Currently just the specified region and "__global__" def validateReport(self, evt: MessageEvent, message: str): # Split command (minus !command_name) into tokens tokens = message.split() region = tokens[0].lower() # Each command must have a state/territory designation and a message if len(tokens) < 2: return None self.log.debug(region) # This is a list of regions to process for this specific message # This is only used to consider __global__ regions_to_process = [] if (self.validateSender("__global__", evt.sender)): regions_to_process.append("__global__") if (self.validateSender(region, evt.sender)): regions_to_process.append(region) return regions_to_process ```