iva-file-delivery

Плагин для Iva, который отправляет готовый локальный файл в текущий личный Telegram-чат владельца от имени бота Ивы.

Плагин решает один узкий сценарий: Ива создала или извлекла документ и должна приложить его к ответу. Файл загружается напрямую в Telegram методом sendDocument; личный аккаунт владельца, «Избранное» и публичный файловый хостинг не используются. Проверять и применять следующие стабильные версии можно из того же чата после нативного кнопочного подтверждения.

Статус: текущая версия проверена с Iva 0.4.3 (Eve 0.51.1). Перед установкой на основной экземпляр рекомендуется один контролируемый canary-файл без чувствительных данных.

Как это выглядит

владелец просит файл в личном чате
  → Iva сохраняет результат в vault/attachments/
    → file_delivery__send_document
      → Telegram Bot API
        → тот же личный чат, отправитель — бот Ивы

обычный текст ответа
  → штатный Outbox Iva

File tool принимает только относительный путь внутри vault/attachments/ и необязательное безопасное имя файла. Адрес чата в его аргументах отсутствует.

Related MCP server: mcp-telegram-claudecode

Граница безопасности

• Получатель берётся из аутентифицированного контекста текущего Telegram-turn, а не из текста запроса или аргумента модели.

• Разрешён только личный чат, где Telegram chat_id совпадает с аутентифицированным user_id. Группы, каналы, CLI-turn и отправка другому пользователю отклоняются.

• Файл должен быть обычным, видимым и непустым, находиться физически внутри vault/attachments/ и иметь размер не больше 50 МБ.

• Абсолютные пути, dot-path, выход через .., симлинки и переименование файла в путь отклоняются.

• Плагин не принимает caption: пояснение Ивы продолжает идти через штатный Outbox.

• Нет fallback на userbot, «Избранное», произвольный chat_id или публичную ссылку.

• Telegram bot token читается из уже настроенного окружения Iva. Отдельный секрет плагину не нужен, токен не возвращается в tool result и не логируется кодом плагина.

• Updater принимает только SHA и одноразовый token свежего offer для этого уже установленного плагина. Имя плагина, URL, ref и shell-команда не принимаются от модели.

• Обновление разрешается только при более высокой SemVer и успешном GitHub Actions на точном candidate SHA; после установки запускается iva doctor, а неуспешная версия откатывается.

Плагин не анализирует содержимое файла на секреты. Файл передаётся Telegram и остаётся доступен владельцу чата; перед отправкой чувствительных данных нужно проверить сам результат. Подробная модель угроз и осознанные ограничения описаны в SECURITY.md и docs/DESIGN.md.

Требования

• Iva 0.4.3;

• настроенный Telegram-бот Iva и личный чат владельца;

• Linux с user systemd для обновления из чата;

• Node.js 24 для разработки.

Поддержка заявляется только для проверенных сочетаний из docs/COMPATIBILITY.md. Более новая Iva не считается автоматически совместимой.

Установка

На сервере под тем же Unix-пользователем, которому принадлежит Iva:

iva plugin add mamysh/iva-file-delivery/plugin@stable --trust
iva plugin list
iva doctor

Дополнительный .env не нужен. --trust разрешает только отдельный MCP-процесс updater; отправка файла остаётся встроенным Extension. Iva соберёт Extension, подключит updater и перезапустит агент по штатному lifecycle. Для первого теста попросите Иву создать небольшой текстовый файл и прислать его в текущий чат.

Ветка stable двигается только на проверенные выпуски. После установки попросите Иву: «Проверь обновление плагина доставки файлов». Она покажет версии и источник, затем предложит нативные кнопки Обновить и Позже. Для полностью неизменяемой установки укажите точный tag, например @v0.2.0; такой source не получает новые версии автоматически.

Пошаговая установка, обновление, удаление и troubleshooting находятся в docs/SETUP.md.

Разработка

npm ci
npm run check

Проверка ищет секреты и приватные локальные следы, валидирует дистрибутив, запускает TypeScript typecheck, отрицательные и положительные тесты, собирает Eve Extension и проверяет stdio MCP smoke-test. plugin/sh.iva/dist/ не коммитится: Iva собирает Extension при установке. plugin/update-server.mjs и plugin/update-worker.mjs коммитятся намеренно, чтобы production не загружал npm-зависимости updater во время установки.

Изменения приветствуются по правилам CONTRIBUTING.md. Устройство плагина и release-процесс описаны в docs/DESIGN.md и docs/RELEASING.md.

Связанные проекты

• Iva

• Agent Plugins specification

• Telegram Bot API: sendDocument

Безопасность

Не публикуйте Telegram bot token, реальные chat/user ID, содержимое частных файлов, абсолютные пути сервера или несокращённые логи. Уязвимости следует сообщать приватно по инструкции в SECURITY.md.

Лицензия

MIT © 2026 mamysh