Draupnir

The @the-draupnir-project/interface-manager library provides a command-oriented presentation interface specifically designed for Matrix bots. It handles three primary responsibilities:

1. Command Parsing: Interpreting user input into structured commands.
2. Rendering: Generating visual representations of command outputs.
3. Interaction Prompts: Managing how the bot interacts with users via prompts.

Additionally, it includes a JSXFactory that allows developers to write JSX templates. These templates are transformed into org.matrix.custom.html for rich Matrix rendering, with a plain text fallback for environments that do not support HTML.

The @the-draupnir-project/matrix-basic-types library provides specialized types for Matrix identifiers to prevent accidental mixing of string values. Instead of using generic strings, use the specific types provided for StringUserID, MatrixRoomID, and eventID. This ensures type safety when handling room IDs, user IDs, and event IDs throughout your application.

async function acceptInvitation(
  inviteSender: StringUserID,
  room: MatrixRoomID
): Promise<Result<void>> {
  console.log(
    `accepting invitation from ${inviteSender} to ${room.toPermalink()}`
  );
  return await client.joinRoom(room.toRoomIDOrAlias(), room.getViaServers());
}

Draupnir is built on several core technical improvements over traditional moderation bots:

• Responsiveness: It does not need to request data from the homeserver before applying bans.
• Revision System: Uses an advanced persistent revision system for room state, members, policies, and policy matches, processing only simple deltas.
• Backing Store: Offers a room state backing store to allow fast startup even when deployed far from the homeserver.
• Extensibility: Core functionality is implemented as protections that can be dynamically enabled/disabled or customized using JS/TS.
• Core Packages:
  • matrix-protection-suite: Provides Matrix client code, event parsing, and types.
  • interface-manager: Provides an advanced command-oriented interface.
  • matrix-basic-types: Handles Matrix string types.

Draupnir uses an interactive prompt-based UX to reduce the need for manual commands. Instead of typing complex strings, Draupnir sends interactive prompts to your management room for common activities:

• Banning/Unbanning: When you ban or unban a user via your standard Matrix client, Draupnir will prompt you in the management room to decide if that action should be added to a policy list.
• Command usage: If you prefer using commands, the ban command now takes the user/entity as the first argument. You can provide just the entity, and Draupnir will prompt you for the policy list and the ban reason.
• Automated Prompts: Prompts are automatically sent for inviting the bot to protect rooms, watching policy lists, and managing bans.

Draupnir is a forwards and backwards compatible drop-in replacement for Mjolnir. Migration is straightforward and typically requires no manual steps beyond updating your server configuration to use the latest Draupnir Docker image instead of the Mjolnir image:

# Use the latest Draupnir image
gnuxie/draupnir:latest

Because Draupnir maintains backwards compatibility, you can test it and switch back to Mjolnir if necessary.

Once Draupnir is running, use these commands to initialize your community protections:

1. Create a ban list: Create a new ban list with a shortcode and an alias. This will automatically invite you to the room created for managing that list.

   !draupnir list create <shortcode> <alias>
   # Example:
   !draupnir list create my-coc code-of-conduct-ban-list

2. Explore capabilities: Use the help command to see all available functions.

   !draupnir help

For detailed configuration, refer to the config/default.yaml file in the repository.

Draupnir provides a comprehensive CLI interface for managing Matrix servers (specifically Synapse) and implementing moderation policies. Commands are organized into logical subcommands under the draupnir prefix.

Common administrative tasks include managing aliases, bans, protections, rooms, and rules. Additionally, Draupnir can proxy or extend native synapse admin commands.

The ReportPoller uses a pagination mechanism to fetch reports from the Synapse admin API. It tracks progress using an opaque token (or the total count) and persists this state to the Matrix user's account data under the event type org.matrix.mjolnir.report_poll.

This ensures that if the bot restarts, it can resume polling from the last successfully processed report without duplication.