# 2026-matrix-csonac

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

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

1. Клонируйте репозиторий и перейдите в его директорию
```bash
git clone https://git.tyukalov.su/nikita/2026-matrix-csonac.git
cd 2026-matrix-csonac
```
2. Создайте `venv`, активируйте его
```bash
python3 -m venv .venv
. .venv/bin/activate
```
5. Запустите приложение чтобы сгененерировать конфиг
```bash
python main.py
```
6. Отредактируйте конфиг
7. Запустите приложение ещё раз, чтобы авторизоваться
```bash
python main.py
```

## Запуск

Для запуска приложения вы можете либо активировать `venv`, либо просто использовать полный путь до интерпретатора Python:
```bash
~/2026-matrix-downloader/.venv/bin/python main.py
```
```bash
. .venv/bin/activate
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 адресов

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

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

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

Все запросы к веб-серверу являются GET-запросами и требуют авторизации.
Авторизоваться можно двумя путями:
1. Использовать HTTP-заголовок `Authorization` и схему `Bearer`. Например:
   ```plain
   Authorization: Bearer 1234567890abcdef
   ```
2. Использовать URL параметр `token`. Например:
   ```plain
   https://csonac.su/notify?token=f1829e94d...
   ```
Рекомендуется использовать первый способ (HTTP-заголовок), так как это позволяет
избежать раскрытия токена в логах сервера и других местах, где можно посмотреть
URL прошлых запросов.

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

Доступные эндпоинты:
- `GET /notify`
    - **Описание.** Используется, чтобы отправить уведомление в канал.
    - **Параметры запроса**
      - `channel` - код канала, получаемый при помощи команды `!info`,
        выполненной в комнате Matrix
      - `service` - имя сервиса (учитывается, только если для токена не было
        настроено имя сервиса через бота)
      - `text` - текст уведомления (форматирование не поддерживается)
    - **Ответ**
      - В случае успеха сервер вернёт `200` и JSON следующего формата:
        ```json
        {
          "notification_id": "Notification ID will be here"
        }
        ```
        > В текущей версии `notification_id` не имеет практической пользы и его
        > формат будет меняться.
      - В случае ошибки сервер вернёт JSON следующего формата:
        ```json
        {
          "detail": "Error description in English"
        }
        ```