diff --git a/CHANGELOG.md b/CHANGELOG.md index fa8b2f22..0bb9aaa9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,25 +9,30 @@ SPDX-License-Identifier: CC-BY-SA-4.0 All notable changes to Draupnir will be kept in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +and this project adheres to +[Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] - 2024-10-04 ### Changed -- `Dockerfile`: entry-point was renamed from `mjolnir-entrypoint.sh` to `draupnir-entrypoint.sh`. - If you have built a Dockerfile based on ours, you may need to make some changes. +- `Dockerfile`: entry-point was renamed from `mjolnir-entrypoint.sh` to + `draupnir-entrypoint.sh`. If you have built a Dockerfile based on ours, you + may need to make some changes. -- `Dockerfile`: source code was moved from `/mjolnir` to `/draupnir`. If you have built a custom - docker image based on our Dockerfile based on ours, you may need to make some changes. +- `Dockerfile`: source code was moved from `/mjolnir` to `/draupnir`. If you + have built a custom docker image based on our Dockerfile based on ours, you + may need to make some changes. -- The appservice registration file generator no longer emits `mjolnir-registration.yaml` - as it has been renamed to `draupnir-registration.yaml`. This is only a concern if you have - automated tooling that generates a registration file. +- The appservice registration file generator no longer emits + `mjolnir-registration.yaml` as it has been renamed to + `draupnir-registration.yaml`. This is only a concern if you have automated + tooling that generates a registration file. ## Versions v2.0.0-beta.7 and prior -Please see [Releases](https://github.com/the-draupnir-project/Draupnir/releases) for more information. +Please see [Releases](https://github.com/the-draupnir-project/Draupnir/releases) +for more information. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc262265..6b0381e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,4 +6,6 @@ SPDX-License-Identifier: CC0-1.0 # Contributing to Draupnir -Our contributing guidelines can be found as part of our documentation. [This link](https://the-draupnir-project.github.io/draupnir-documentation/contributing) leads to the contributing guidelines. +Our contributing guidelines can be found as part of our documentation. +[This link](https://the-draupnir-project.github.io/draupnir-documentation/contributing) +leads to the contributing guidelines. diff --git a/README.md b/README.md index 93bf198c..d6fbaf78 100644 --- a/README.md +++ b/README.md @@ -6,32 +6,31 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Draupnir -A [Matrix](https://matrix.org) moderation bot and protection platform. -Visit [#draupnir:matrix.org](https://matrix.to/#/#draupnir:matrix.org) -in your client and come say hi. +A [Matrix](https://matrix.org) moderation bot and protection platform. Visit +[#draupnir:matrix.org](https://matrix.to/#/#draupnir:matrix.org) in your client +and come say hi. -Please see the [draupnir -documentation](https://the-draupnir-project.github.io/draupnir-documentation/) +Please see the +[draupnir documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for installation instructions and usage guides. ## Features -Draupnir has two main functions, the first is to synchronise bans for -users and servers across all of the matrix rooms that you moderate. -The second is to protect your community by applying policies from community curated -policy lists, for example the [community moderation effort](https://matrix.to/#/#community-moderation-effort-bl:neko.dev), -to your rooms around the clock. This means that communities can warn -and protect each other of known threats. +Draupnir has two main functions, the first is to synchronise bans for users and +servers across all of the matrix rooms that you moderate. The second is to +protect your community by applying policies from community curated policy lists, +for example the +[community moderation effort](https://matrix.to/#/#community-moderation-effort-bl:neko.dev), +to your rooms around the clock. This means that communities can warn and protect +each other of known threats. -Draupnir also includes a series of protections that can be enabled -that might help you in some scenarios. +Draupnir also includes a series of protections that can be enabled that might +help you in some scenarios. -By default Draupnir includes support for user bans, redactions and -server ACLs. +By default Draupnir includes support for user bans, redactions and server ACLs. -Some support is also provided for server administrative functions, -such as reviewing abuse reports, deactivating user accounts and -shutting down rooms. +Some support is also provided for server administrative functions, such as +reviewing abuse reports, deactivating user accounts and shutting down rooms. ### Differences from Mjolnir @@ -39,133 +38,146 @@ shutting down rooms. Draupnir started as a fork of [Mjolnir](https://github.com/matrix-org/mjolnir), in order to radically refactor the code base and break a feature freeze. -Draupnir has now completed this refactor and large sections of the the -code base are now very distinct, as much of Draupnir was rewritten. +Draupnir has now completed this refactor and large sections of the the code base +are now very distinct, as much of Draupnir was rewritten. -Draupnir remains a drop in replacement for Mjolnir and is forwards and -backwards compatible. +Draupnir remains a drop in replacement for Mjolnir and is forwards and backwards +compatible. #### Changes in `v2.0.0-beta.*` (pre-release) -- Draupnir's new core efficiently caches room state and room - membership allowing Draupnir to be much more responsive than - Mjolnir. +- Draupnir's new core efficiently caches room state and room membership allowing + Draupnir to be much more responsive than Mjolnir. -- Draupnir is much less dependant on commands - and will automatically send prompts to the management room. - Prompts are sent for inviting Draupnir to protect rooms, - watch policy lists, ban users, and unban users. +- Draupnir is much less dependant on commands and will automatically send + prompts to the management room. Prompts are sent for inviting Draupnir to + protect rooms, watch policy lists, ban users, and unban users. -- Draupnir offers a [room state backing - store](https://github.com/the-draupnir-project/Draupnir/blob/main/config/default.yaml#L206-L212), - allowing Draupnir startup quickly, even when deployed at distance - from the homeserver. +- Draupnir offers a + [room state backing store](https://github.com/the-draupnir-project/Draupnir/blob/main/config/default.yaml#L206-L212), + allowing Draupnir startup quickly, even when deployed at distance from the + homeserver. -- Draupnir's core functionality is implemented as protections, - which can be dynamically turned on and off. +- Draupnir's core functionality is implemented as protections, which can be + dynamically turned on and off. -- Most effort has been spent refactoring the code base, paving the way - for future feature development and adjacent projects. This includes - the rewrite of the core of Draupnir into the +- Most effort has been spent refactoring the code base, paving the way for + future feature development and adjacent projects. This includes the rewrite of + the core of Draupnir into the [matrix-protection-suite](https://github.com/Gnuxie/matrix-protection-suite), - providing all the Matrix client code required to operate a - protection platform. The + providing all the Matrix client code required to operate a protection + platform. The [interface-manager](https://github.com/the-draupnir-project/interface-manager) - providing an advanced command-oriented interface (note, this does - not mean command-line interface). The + providing an advanced command-oriented interface (note, this does not mean + command-line interface). The [matrix-basic-types](https://github.com/the-draupnir-project/matrix-basic-types) - library for dealing with Matrix's various string types. And finally - the introduction of [prettier](https://prettier.io/), + library for dealing with Matrix's various string types. And finally the + introduction of [prettier](https://prettier.io/), [eslint](https://eslint.org/) and - [typescript-eslint](https://typescript-eslint.io/) into Draupnir's - development tooling, modernising TypeScript development. + [typescript-eslint](https://typescript-eslint.io/) into Draupnir's development + tooling, modernising TypeScript development. #### Changes in latest `v1.87.0` The main difference from Mjolnir is that it is no longer necessary to use -commands for some functions. Banning a user in a protected room from your -Matrix client will cause Draupnir to show a prompt in the management room, -which will offer to add the ban to a policy list[^the-gif-width]. +commands for some functions. Banning a user in a protected room from your Matrix +client will cause Draupnir to show a prompt in the management room, which will +offer to add the ban to a policy list[^the-gif-width]. ![A demo showing a propagation prompt](docs/ban-propagation-prompt.gif) -You can also unban users the same way, and Draupnir will prompt you -to unban them without any confusing hiccups. -If you do still wish to use the ban command, please note that users -and other entities that are being banned are now the first argument -to the ban command. It is now also possible to provide only the entity to -Draupnir and have Draupnir prompt you for the policy list and the ban reason. +You can also unban users the same way, and Draupnir will prompt you to unban +them without any confusing hiccups. If you do still wish to use the ban command, +please note that users and other entities that are being banned are now the +first argument to the ban command. It is now also possible to provide only the +entity to Draupnir and have Draupnir prompt you for the policy list and the ban +reason. ![A demo showing the ban command](docs/ban-command-prompt.gif) -In general, all commands have been migrated to a new interface which -feature better error messages for common problems and allow admins -to trace the cause of unexpected errors much more easily. +In general, all commands have been migrated to a new interface which feature +better error messages for common problems and allow admins to trace the cause of +unexpected errors much more easily. [^the-gif-width]: - Yes, i know they don't align horizontally, - you are welcome to suggest how this should be fixed. + Yes, i know they don't align horizontally, you are welcome to suggest how + this should be fixed. ## Status -Draupnir is being supported with a grant from NLnet, -the goals of the work are described [here](https://marewolf.me/posts/draupnir/24-nlnet-goals.html) +Draupnir is being supported with a grant from NLnet, the goals of the work are +described [here](https://marewolf.me/posts/draupnir/24-nlnet-goals.html) -Currently The UX and code base of Draupnir has been overhauled and -Draupnir is moving towards a 2.0.0 release. +Currently The UX and code base of Draupnir has been overhauled and Draupnir is +moving towards a 2.0.0 release. -As Draupnir heads towards `v2.0.0`, releases will appear [here](https://github.com/Gnuxie/Draupnir/releases). -Until `v2.0.0` there will be frequent changes to commands but all of these -will be noted in the changes for that release. +As Draupnir heads towards `v2.0.0`, releases will appear +[here](https://github.com/Gnuxie/Draupnir/releases). Until `v2.0.0` there will +be frequent changes to commands but all of these will be noted in the changes +for that release. -Currently, we are running a beta channel (`v2.0.0-beta.*`). As of now -all functionality apart from dynamic configuration of protection -settings is stable in the beta channel. +Currently, we are running a beta channel (`v2.0.0-beta.*`). As of now all +functionality apart from dynamic configuration of protection settings is stable +in the beta channel. -For the latest stable release, see `v1.87.0`, the documentation -for which can be found [here](https://github.com/the-draupnir-project/Draupnir/tree/v1.87.0). +For the latest stable release, see `v1.87.0`, the documentation for which can be +found [here](https://github.com/the-draupnir-project/Draupnir/tree/v1.87.0). ### Migration Migrating from Mjolnir is straightforward and requires no manual steps, migration for your setup is likely as simple as changing your server config to -pull the latest Draupnir docker image instead of a mjolnir one. -Draupnir remains backwards compatible so that it is possible to try Draupnir -and still have the option to switch back to Mjolnir. +pull the latest Draupnir docker image instead of a mjolnir one. Draupnir remains +backwards compatible so that it is possible to try Draupnir and still have the +option to switch back to Mjolnir. -Any problems with migration should be reported to our [support room](https://matrix.to/#/#draupnir:matrix.org). +Any problems with migration should be reported to our +[support room](https://matrix.to/#/#draupnir:matrix.org). ## Setting up -See the [setup documentation](https://the-draupnir-project.github.io/draupnir-documentation/bot/setup) for first-time setup documentation. +See the +[setup documentation](https://the-draupnir-project.github.io/draupnir-documentation/bot/setup) +for first-time setup documentation. -See the [configuration sample with documentation](config/default.yaml) for detailed information about Draupnir's configuration. +See the [configuration sample with documentation](config/default.yaml) for +detailed information about Draupnir's configuration. -See the [synapse module documentation](docs/synapse_module.md) for information on how to setup Draupnir's accompanying Synapse Module. +See the [synapse module documentation](docs/synapse_module.md) for information +on how to setup Draupnir's accompanying Synapse Module. ## Quickstart guide -After your bot is up and running, you'll want to run a couple commands to get everything -set up: +After your bot is up and running, you'll want to run a couple commands to get +everything set up: -1. `!draupnir list create my-coc code-of-conduct-ban-list` - This will create a new ban list - with the shortcode `my-coc` and an alias of `#code-of-conduct-ban-list:example.org`. You - will be invited to the room it creates automatically where you can change settings such - as the visibility of the room. -2. Review the [Moderator's Guide](https://the-draupnir-project.github.io/draupnir-documentation/moderator/setting-up-and-configuring). +1. `!draupnir list create my-coc code-of-conduct-ban-list` - This will create a + new ban list with the shortcode `my-coc` and an alias of + `#code-of-conduct-ban-list:example.org`. You will be invited to the room it + creates automatically where you can change settings such as the visibility of + the room. +2. Review the + [Moderator's Guide](https://the-draupnir-project.github.io/draupnir-documentation/moderator/setting-up-and-configuring). 3. Review `!draupnir help` to see what else the bot can do. ## Enabling readable abuse reports -Since version 1.2, Draupnir offers the ability to replace the Matrix endpoint used -to report abuse and display it into a room, instead of requiring you to request -this data from an admin API. +Since version 1.2, Draupnir offers the ability to replace the Matrix endpoint +used to report abuse and display it into a room, instead of requiring you to +request this data from an admin API. This requires two configuration steps: -1. In your Draupnir configuration file, typically `/etc/draupnir/config/production.yaml`, copy and paste the `web` section from `default.yaml`, if you don't have it yet (it appears with version 1.20) and set `enabled: true` for both `web` and - `abuseReporting`. -2. Setup a reverse proxy that will redirect requests from `^/_matrix/client/(r0|v3)/rooms/([^/]*)/report/(.*)$` to `http://host:port/api/1/report/$2/$3`, where `host` is the host where you run Draupnir, and `port` is the port you configured in `production.yaml`. For an example nginx configuration, see `test/nginx.conf`. It's the confirmation we use during runtime testing. +1. In your Draupnir configuration file, typically + `/etc/draupnir/config/production.yaml`, copy and paste the `web` section from + `default.yaml`, if you don't have it yet (it appears with version 1.20) and + set `enabled: true` for both `web` and `abuseReporting`. +2. Setup a reverse proxy that will redirect requests from + `^/_matrix/client/(r0|v3)/rooms/([^/]*)/report/(.*)$` to + `http://host:port/api/1/report/$2/$3`, where `host` is the host where you run + Draupnir, and `port` is the port you configured in `production.yaml`. For an + example nginx configuration, see `test/nginx.conf`. It's the confirmation we + use during runtime testing. ### Security note @@ -181,16 +193,17 @@ this feature will publish information from room _foo_ is: Essentially, this is a more restricted variant of the Admin APIs available on homeservers. -However, if you are uncomfortable with this, please do not activate this feature. -Also, you should probably setup your `production.yaml` to ensure that the web -server can only receive requests from your reverse proxy (e.g. `localhost`). +However, if you are uncomfortable with this, please do not activate this +feature. Also, you should probably setup your `production.yaml` to ensure that +the web server can only receive requests from your reverse proxy (e.g. +`localhost`). ## Contributing & Opening Issues -Draupnir wants to be yours as much as it is ours. -Please see or [contributing document](https://the-draupnir-project.github.io/draupnir-documentation/contributing), but do not -worry too much about following the guidance to the letter. And -keep that in mind throughout. +Draupnir wants to be yours as much as it is ours. Please see or +[contributing document](https://the-draupnir-project.github.io/draupnir-documentation/contributing), +but do not worry too much about following the guidance to the letter. And keep +that in mind throughout. ## Supported by diff --git a/docs/appservice.md b/docs/appservice.md index f5fd8b37..410a38b1 100644 --- a/docs/appservice.md +++ b/docs/appservice.md @@ -4,4 +4,5 @@ SPDX-FileCopyrightText: 2024 Gnuxie SPDX-License-Identifier: CC0-1.0 --> -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/appservice +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/appservice diff --git a/docs/code-style.md b/docs/code-style.md index d060ec6e..fcb0b144 100644 --- a/docs/code-style.md +++ b/docs/code-style.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Code style -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/contributing/code-style +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/contributing/code-style diff --git a/docs/context.md b/docs/context.md index 1f3c812d..4ef6cb3d 100644 --- a/docs/context.md +++ b/docs/context.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 ## Context for developing Draupnir -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/contributing/context +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/contributing/context diff --git a/docs/development-environment.md b/docs/development-environment.md index 4f914849..88a25b4d 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Developing Draupnir - tests, tools, and environment -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment diff --git a/docs/development.md b/docs/development.md index 867f8433..0c08ec3a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Developing Draupnir -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/contributing/development +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/contributing/development diff --git a/docs/moderators.md b/docs/moderators.md index 5dcafb50..cc746195 100644 --- a/docs/moderators.md +++ b/docs/moderators.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Moderator's guide to Draupnir (bot edition) -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/bot/moderators +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/bot/moderators diff --git a/docs/setup.md b/docs/setup.md index 665b6459..e2b447b1 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Setting up Draupnir -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/bot/setup +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/bot/setup diff --git a/docs/setup_docker.md b/docs/setup_docker.md index 56369f3d..bee5ff3f 100644 --- a/docs/setup_docker.md +++ b/docs/setup_docker.md @@ -4,4 +4,5 @@ SPDX-FileCopyrightText: 2024 Gnuxie SPDX-License-Identifier: CC0-1.0 --> -This document has moved to https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_docker +This document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_docker diff --git a/docs/setup_selfbuild.md b/docs/setup_selfbuild.md index 853ecacc..0c75b9b8 100644 --- a/docs/setup_selfbuild.md +++ b/docs/setup_selfbuild.md @@ -4,4 +4,5 @@ SPDX-FileCopyrightText: 2024 Gnuxie SPDX-License-Identifier: CC0-1.0 --> -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_selfbuild +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_selfbuild diff --git a/docs/synapse_module.md b/docs/synapse_module.md index b6b1dec6..7fa10908 100644 --- a/docs/synapse_module.md +++ b/docs/synapse_module.md @@ -4,4 +4,5 @@ SPDX-FileCopyrightText: 2024 Gnuxie SPDX-License-Identifier: CC0-1.0 --> -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module diff --git a/docs/triaging.md b/docs/triaging.md index 1e9c0e09..a94d7985 100644 --- a/docs/triaging.md +++ b/docs/triaging.md @@ -6,4 +6,5 @@ SPDX-License-Identifier: CC0-1.0 # Triaging issues -This Document has moved to https://the-draupnir-project.github.io/draupnir-documentation/contributing/triaging +This Document has moved to +https://the-draupnir-project.github.io/draupnir-documentation/contributing/triaging