API и интеграции

Один OAuth2-движок (Authorization Code Flow) обслуживает любой сервис — провайдер описывается данными, а не кодом. Встроенные провайдеры: google, gmail, avito, github, slack, notion, threads, twitter, dropbox, spotify, yandex, vk.

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

• AI вызывает get_oauth_url(service='...') и возвращает реальный authorize-URL с одноразовым state, сохранённым в БД
• Вы подтверждаете доступ у провайдера и попадаете на /auth/oauth2/callback (или на путь провайдера, например /auth/google/callback)
• Сервер валидирует state, обменивает code на токены и сохраняет их в зашифрованном виде (Fernet/AES) для каждого пользователя
• AI читает токены через credential_get('oauth2:'); истёкшие токены обновляются автоматически с retry/backoff

Эндпоинты

Добавить свой провайдер — без правки кода

MY_SERVICE_CLIENT_ID=...
MY_SERVICE_CLIENT_SECRET=...
MY_SERVICE_AUTH_URL=https://example.com/oauth/authorize
MY_SERVICE_TOKEN_URL=https://example.com/oauth/token
MY_SERVICE_SCOPES=read,write
MY_SERVICE_PROBE_URL=https://api.example.com/me
OAUTH_PROVIDERS=my_service

Опционально: {NAME}_SCOPE_SEPARATOR, {NAME}_TOKEN_AUTH_METHOD (client_secret_post / client_secret_basic), {NAME}_USE_PKCE, {NAME}_REFRESH_SUPPORTED, {NAME}_REDIRECT_PATH, {NAME}_PROBE_URL. Redirect URI: https://asibiont.com/auth/oauth2/callback (канонический хост без www).

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

• PKCE (RFC 7636) — code_verifier + code_challenge (S256) для провайдеров, которые это поддерживают
• State — одноразовый, хранится в таблице oauth_pending_states с TTL 10 минут; переживает рестарты и несколько воркеров
• Шифрование — токены шифруются Fernet (AES) и никогда не передаются между пользователями
• Проверка здоровья — credential_health обновляет токен и делает реальный пробный запрос к провайдеру

AI принимает события от любых внешних сервисов. Зарегистрируйте вебхук через register_webhook(service, webhook_url, secret) — сервис будет слать POST на /api/webhooks/{service}.

Эндпоинты

Проверка подписи

Если задан секрет, запрос должен содержать X-Signature-256 или X-Hub-Signature-256 — HMAC-SHA256 от сырого тела, в виде hex или sha256=. При несовпадении возвращается 403. События изолированы по пользователям; очередь хранит до 1000 событий на пользователя.

import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, received.replace('sha256=', ''))

Python-обработчики выполняются с retry (3 попытки, экспоненциальный backoff); когда попытки исчерпаны, событие попадает в dead-letter очередь (до 100 событий на пользователя), которую AI может просмотреть.

Подпишитесь на события AI и получайте HTTP POST уведомления на ваш URL. Каждый вебхук подписывается HMAC-SHA256 — проверяйте подлинность на своей стороне.

Типы событий

• mission_created — Создана новая миссия
• task_completed — Задача завершена
• ai_message — Сообщение AI в чате
• reminder_triggered — Напоминание сработало
• note_created — Создана заметка
• scheduled_trigger — Задача по расписанию выполнена
• integration_connected — Интеграция подключена

Каждый вебхук содержит заголовок X-ASI-Signature — HMAC-SHA256 от тела запроса, подписанный секретным ключом. Таймаут доставки — 15 секунд; без ответа HTTP 200 доставка считается неудачной. Автоматических повторов нет — эндпоинт должен быть идемпотентным.

Планируйте выполнение AI-промптов по cron-расписанию. Укажите промпт и время — AI выполнит задачу, сохранит результат в заметки и пришлёт отчёт.

Примеры

Фоновый воркер проверяет задачи каждые 60 секунд. При срабатывании AI выполняет промпт, сохраняет ответ как заметку и генерирует событие scheduled_trigger (перехватывается вебхуками).

Система событий — это центральная шина сообщений, соединяющая все компоненты ASI Biont. Построенная на архитектуре asyncio.Queue, она обеспечивает надёжную асинхронную доставку событий по всей платформе.

Архитектура

• События помещаются в in-memory asyncio.Queue
• Фоновый воркер обрабатывает события одно за другим
• Каждое событие логируется в таблицу event_logs для аудита
• Обработчики регистрируются через декоратор @EventSystem.on('event_type')

Формат события

{
    "user_id": 42,
    "event_type": "task_completed",
    "payload": {
        "task_id": 123,
        "title": "Analyze sales data",
        "status": "completed"
    }
}

Встроенные обработчики

• Outgoing Webhooks — Доставляет события на зарегистрированные URL вебхуков с подписью HMAC-SHA256
• Event Logging — Сохраняет каждое событие в БД для аудита и отладки

AI ASI Biont может подключаться к удалённым серверам через SSH и общаться с оборудованием через последовательные порты. SSH-подключения выполняются в безопасной Python-песочнице; доступ к COM-портам идёт через Hardware Bridge — отдельное приложение (bridge.py), запущенное на ПК пользователя.

SSH (paramiko)

AI использует библиотеку paramiko для подключения к любому SSH-серверу. Credentials хранятся в зашифрованном виде (Fernet: AES-128-CBC + HMAC-SHA256) через credential_set и никогда не попадают в код AI.

• По умолчанию только read-only команды (логи, мониторинг, диагностика)
• Деструктивные команды — только с явного разрешения пользователя
• Защита от SSRF — подключения к private IP (10.x, 192.168.x, 127.0.0.1) блокируются
• Таймаут 30 секунд — зависшие соединения автоматически обрываются

COM-порты — Hardware Bridge

AI общается с устройствами через последовательные порты с помощью Hardware Bridge — отдельного приложения bridge.py, запущенного на ПК пользователя. Bridge подключается к ASI Biont через WebSocket (единственный канал связи) и обеспечивает доступ к COM-портам локально через pyserial. AI отправляет команды через industrial_command — они уходят на bridge пользователя, который читает/пишет в COM-порт.

• Arduino, ESP32, ESP8266 — чтение датчиков, управление пинами
• Промышленные контроллеры — Modbus RTU, RS-232/RS-485
• GPS-приёмники — чтение NMEA-данных
• Любые USB-serial устройства — считыватели штрихкодов, принтеры чеков, терминалы
• Атомарная операция serial_write_and_read — запись и чтение за один вызов, без риска таймаута
• HELP протокол — отправь serial_write_and_read(data="48454c500a") для получения списка команд устройства
• Кроссплатформенность: Windows (CancelIoEx + PurgeComm fallback), Linux, macOS