2026-matrix-csonac/README.md

2026-matrix-csonac

Реализация CSoNaC (Centralized System of Notification and Control) для Matrix. Раньше был бот с таким же функционалом, но для Telegram. Telegram больше не в почёте, и теперь у меня всё в локальном Matrix, поэтому бот тоже перенесён сюда.

Для запуска рекомендуется docker

1. Скачайте образ (измените версию на нужную вам):

sudo docker pull git.tyukalov.su/nikita/2026-matrix-csonac:0.4

2. Выполните первый запуск в интерактивном режиме

sudo mkdir runtime
sudo chown 1000:1000 runtime
sudo docker run -v ./runtime:/runtime -ti git.tyukalov.su/nikita/2026-matrix-csonac:0.4

3. В папке runtime появится файл config.json. Внесите туда нужные настройки
4. Запустите ещё раз в интерактивном режиме, чтобы авторизоваться

sudo docker run -v ./runtime:/runtime -ti git.tyukalov.su/nikita/2026-matrix-csonac:0.4

5. Дальше можно запускать контейнер в фоне

sudo docker run -p 127.0.0.1:4980:4980 -v ./runtime:/runtime --detach git.tyukalov.su/nikita/2026-matrix-csonac:0.4

Рекомендуется запускать контейнер при помощи docker compose.

Запуск без docker

1. Клонируйте репозиторий и перейдите в его директорию

git clone https://git.tyukalov.su/nikita/2026-matrix-csonac.git
cd 2026-matrix-csonac

2. Создайте venv, активируйте его

python3 -m venv .venv
. .venv/bin/activate

5. Запустите приложение чтобы сгененерировать конфиг

python main.py

6. Отредактируйте конфиг
7. Запустите приложение ещё раз, чтобы авторизоваться

python main.py

Как работает бот

Для каждой службы (канала уведомлений) создаётся своя собственная комната и в такие комнаты добавляется бот. Затем вся работа с ботом производится при помощи команд - текстовых сообщений, начинающихся с восклицательного знака. Поддерживаются следующие команды:

• !help - получить справку
• !info - получить сведения о комнате
• !tokens - получить список токенов
• !auth [SERVICE_NAME] - создать новый токен (если указать имя сервиса, то приложение, использующее токен, не сможет самостоятельно указывать имя сервиса - всегда будет использовано имя, указанное вами)
• !deauth <TOKEN> - удалить токен
• !name <TOKEN> [SERVICE_NAME] - указать (или удалить) имя сервиса для токена
• !ban <IP> <SECONDS> [REASON] - забанить указанный IP на указанное число секунд (можно указать причину)
• !unban <IP> - разбанить указанный IP адрес
• !bans - получить список забаненных IP адресов
• !short <TOKEN> - создать токен с указанным именем

Как работает веб-сервер

Этот бот запускает веб-сервер, используя web_host и web_port из файла конфигурации.

Не открывайте доступ к серверу напрямую! Используйте reverse proxy, например, nginx. Это также позволит вам использовать защищённое соединение, что исключит возможность применения атаки Man-in-the-Middle для перехвата токена.

Все запросы к веб-серверу являются GET-запросами и требуют авторизации. Авторизоваться можно двумя путями:

1. Использовать HTTP-заголовок Authorization и схему Bearer. Например:

   Authorization: Bearer 1234567890abcdef
   

2. Использовать URL параметр token. Например:

   https://csonac.su/api/notify?token=f1829e94d...
   

Рекомендуется использовать первый способ (HTTP-заголовок), так как это позволяет избежать раскрытия токена в логах сервера и других местах, где можно посмотреть URL прошлых запросов.

Для каждого сервиса, использующего бота, рекомендуется генерировать свой собственный токен. Это позволит отозвать токен только для одного серсива, если токен будет украден.

Доступные эндпоинты:

• GET /api/notify
  • Описание. Используется, чтобы отправить уведомление в канал.
  • Параметры запроса
    • channel - код канала, получаемый при помощи команды !info, выполненной в комнате Matrix
    • service - имя сервиса (учитывается, только если для токена не было настроено имя сервиса через бота)
    • text - текст уведомления (форматирование не поддерживается)
  • Ответ
    • В случае успеха сервер вернёт 200 и JSON следующего формата:

      {
        "notification_id": "Notification ID will be here"
      }
      

      В текущей версии notification_id не имеет практической пользы и его формат будет меняться.

    • В случае ошибки сервер вернёт JSON следующего формата:

      {
        "detail": "Error description in English"
      }