synapse-invite-checker/README.md
2024-09-16 20:02:36 +02:00

63 lines
2.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Synapse Invite Checker Module
This is a Synapse module that checks incoming invites based on allowlist and blocklist rules. The module allows or blocks invites from certain homeservers depending on whether they appear in a dynamically fetched allowlist or blocklist JSON file.
## Features
- **Allowlist and Blocklist**: Allows invites from homeservers in the allowlist, blocks invites from homeservers in the blocklist.
- **Dynamic Fetching**: The allowlist and blocklist are fetched dynamically from a provided URL, and cached.
- **Support for MSC2313 Policy Rooms**: This module supports fetching blocklists from MSC2313 policy rooms to block invites based on room state events.
- **Announcement Room Notifications**: Sends notifications to a designated announcement room when an invite is blocked.
- **Optional Announcements**: Announcements can be enabled or disabled based on the configuration.
## Configuration
Add this module to your Synapse's `homeserver.yaml` under the `modules` section. Heres an example configuration:
```yaml
modules:
- module: synapse_invite_checker.InviteChecker
config:
# URL to fetch the JSON file containing the allowlist and blocklist
blocklist_allowlist_url: "https://example.com/invite-checker-lists.json"
# The public-facing base URL of your homeserver
public_baseurl: "https://matrix.example.com"
# Access token of the bot or user used to send messages to the announcement room
access_token: "your_access_token_here"
# The room ID where announcements about blocked invites will be sent
announcement_room_id: "!your_announcement_room_id:example.com"
# Enable or disable sending announcements when invites are blocked (default: false)
enable_announcement: true
# Optionally specify policy rooms for dynamic blocklist fetching via MSC2313
policy_room_ids:
- "!policy-room-1:matrix.org"
- "!policy-room-2:matrix.org"
# Whether to use the allowlist to allow certain homeservers (default: true)
use_allowlist: true
# Whether to use the blocklist to block certain homeservers (default: true)
use_blocklist: true
# List of room aliases or room IDs to block invites from (optional)
blocklist_rooms:
- "#test:matrix.org"
- "!dkgsemSiSMrGfxEwCb:ubuntu.com"
```
```json
{
"use_allowlist": true,
"use_blocklist": true,
"allowlist": [
"trusted-homeserver.com",
"another-trusted-server.org"
],
"blocklist": [
"malicious-homeserver.com",
"blocked-server.org"
],
"blocklist_rooms": [
"#test:matrix.org", // Room alias to be resolved to room_id
"#private-room:example.org", // Another room alias
"!abc123:matrix.org" // Direct room ID
]
}
```