2026-matrix-csonac/README.md

2026-matrix-csonac

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

Подготовка окружения

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

Запуск

Для запуска приложения вы можете либо активировать venv, либо просто использовать полный путь до интерпретатора Python:

~/2026-matrix-downloader/.venv/bin/python main.py

. .venv/bin/activate
python main.py

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

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

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

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

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

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

Все запросы к веб-серверу требуют авторизации, используя HTTP заголовок Authorization и схему Bearer. Токен авторизации генерируется посредством взаимодействия с ботом в Matrix.

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

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

• POST /<channel>/notify
  • Описание. Используется, чтобы отправить уведомление в указанный канал. Вместо <channel> указывается код канала, получаемый при помощи команды !info, выполненной в комнате Matrix.
  • Тело запроса. Тело запроса представляет собой json объект:

      {
          "service": "<название сервиса; указывается, если токен это позволяет>",
          "text": "<текст уведомления>"
      }
    

  • Тело ответа. Тело ответа представляет собой json объект. В случае успеха в нём будут все поля, перечисляемые ниже. В случае провала - только поле error, содержащее текстовое описание ошибки.

      {
          "error": null,
          "notification_id": "<здесь будет Notification ID>"
      }
    

• ``