# felicia

web service for sharing lists of bad actors. originally made for the fediverse, but flexible enough to use in other contexts.

## config

`felicia` is configured via environment variables:

* `PORT`: service port, 8090 by default
* `LOCAL_LIST_PATH`: path to a local list file, see below
* `SOURCES_PATH`: path to a sources file, see below
* `SOURCES_LIFETIME`: list cache lifetime, 10 minutes by default

you must provide at least `LOCAL_SOURCES` or `SOURCES_PATH`. you can of course also set both.

`felicia` automatically invalidates cached lists (either local or remote ones) on a set interval and will re-fetch them when necessary, so restarting the service is not necessary for changes to be reflected.

note that the local source list itself is not automatically refreshed at the moment, so if you add a new source you do need to restart.  

## models

### List

list of domains and acompanying information.

```json
{
  "domains": [
    {
      "domain": "example.org",
      "level": "low|medium|high"
      "reason": "<...>",
      "notes": "<...>",
      "source": "<source where this domain entry originates from>"
    }
  ]
}
```

### Source

sources to fetch more lists from.

```json
{
  "sources": [
    "http://example.org/list.json"
  ]
}
```

## api

### GET /list/all

fetch all entries available, local and/or remote.

#### request

* Query params
  * `dedup` -- if present and set to `true`, return de-duplicated entries

#### response

* type: application/json
* model: List

### GET /list/all/mastodonCsv

fetch all entries available, local and/or remote, as a Mastodon-compatible domain blocklist.

#### response

* type: text/csv

### GET /list/search

filter all entries available for a specific domain and/or the amount of times it appears in different sources.

#### request

* Query params
  * `domain` -- if present, filter domain names by the given substring
  * `threshold` -- if present and given an integer `n`, filter domains that appear in at least `n` distinct sources
  * `source` -- if present, filter domain sources by the given substring
  * `level` -- if present, filter by entry severity level (`low`, `medium` or `severe`)
  * `dedup` -- if present and set to `true`, return de-duplicated entries

#### response

* type: application/json
* model: List

## caveats

`felicia` is meant to facilitate aggregating and sharing potentially decentralized lists of bad actors. it doesn't, by itself, solve issues related to trust in the source themselves.

*you must still verify your sources, including transitive ones, and make sure you can trust them.*

## license

(C) ariela wenner, 2023

unless otherwise specified, all code is licensed under the AGPL 3.0.