Matrix

Подключение PRX к сети Matrix через Client-Server API с необязательным сквозным шифрованием (E2EE) и обменом сообщениями на основе комнат.

Предварительные требования

• Домашний сервер Matrix (например, matrix.org или самохостинг Synapse/Dendrite)
• Бот-аккаунт на домашнем сервере с токеном доступа
• ID комнаты, в которой бот должен слушать
• PRX, собранный с флагом функции channel-matrix

Быстрая настройка

1. Создание бот-аккаунта

Создайте аккаунт на вашем домашнем сервере Matrix для бота. Можно использовать Element или командную строку:

# Используя curl к API домашнего сервера
curl -X POST "https://matrix.org/_matrix/client/v3/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "prx-bot", "password": "secure-password", "auth": {"type": "m.login.dummy"}}'

2. Получение токена доступа

curl -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type": "m.login.password", "user": "prx-bot", "password": "secure-password"}'

3. Приглашение бота в комнату

Из вашего Matrix-клиента пригласите бот-аккаунт в комнату, где он должен работать. Запишите ID комнаты (формат: !abc123:matrix.org).

4. Конфигурация

[channels_config.matrix]
homeserver = "https://matrix.org"
access_token = "syt_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
room_id = "!abc123def456:matrix.org"
allowed_users = ["@alice:matrix.org", "@bob:matrix.org"]

5. Проверка

prx channel doctor matrix

Справочник конфигурации

Поле	Тип	По умолчанию	Описание
homeserver	String	обязательный	URL домашнего сервера Matrix (например, "https://matrix.org")
access_token	String	обязательный	Токен доступа Matrix для бот-аккаунта
user_id	String	null	Matrix user ID (например, "@bot:matrix.org"). Используется для восстановления сессии
device_id	String	null	Matrix device ID. Используется для непрерывности E2EE-сессий
room_id	String	обязательный	ID комнаты для прослушивания (например, "!abc123:matrix.org")
allowed_users	[String]	[]	Разрешённые Matrix user ID. Пусто = запрещено всем. "*" = разрешить всем

Возможности

• Сквозное шифрование — поддержка зашифрованных комнат через matrix-sdk с Vodozemac
• Обмен сообщениями на основе комнат — прослушивание и ответы в конкретной Matrix-комнате
• Реакции на сообщения — реакции на сообщения для подтверждения получения и завершения
• Уведомления о прочтении — отправка уведомлений о прочтении обработанных сообщений
• Постоянство сессий — хранение криптосессий локально для непрерывности E2EE между перезапусками
• Независимость от сервера — работает с любым домашним сервером Matrix (Synapse, Dendrite, Conduit и т.д.)

Ограничения

• В настоящее время прослушивание только в одной комнате (задаётся через room_id)
• Требуется флаг функции channel-matrix при компиляции
• Резервное копирование ключей E2EE и верификация перекрёстной подписи ещё не поддерживаются
• Большие комнаты с высоким объёмом сообщений могут увеличить потребление ресурсов
• Бот должен быть приглашён в комнату, прежде чем сможет слушать

Устранение неполадок

Бот не отвечает в зашифрованных комнатах

• Убедитесь, что user_id и device_id заданы для корректного управления E2EE-сессиями
• Удалите локальное криптохранилище и перезапустите для восстановления сессий шифрования
• Убедитесь, что бот-аккаунт верифицирован/доверен участниками комнаты

Ошибка «Room not found»

• Подтвердите корректность формата ID комнаты (префикс !, суффикс :homeserver)
• Убедитесь, что бот приглашён и вступил в комнату
• Псевдонимы комнат (например, #room:matrix.org) не поддерживаются; используйте ID комнаты

Токен доступа отклонён

• Токены доступа могут истекать; сгенерируйте новый через API входа
• Убедитесь, что токен принадлежит корректному домашнему серверу