Перейти к основному содержимому

Static токены

Static-токен — это plaintext bot_<48hex> строка, которую owner получает при создании бота. Хранится в БД как HMAC-SHA256 keyed-MAC на отдельном bot_token_secret (изоляция blast-radius от JWT/media-ключей).

Когда использовать​

✅ Self-hosted

Бот живёт на вашей инфраструктуре, никто другой токен не использует.

✅ Internal automation

Daily-job, slack-bridge, internal tools.

❌ Public/marketplace

1-click install для пользователей через OAuth2 — в roadmap, пока не реализован. Сейчас бот подключается static-токеном и приглашением в Space.

❌ Mobile/SPA

Токен попадёт в bundle — это leak. Держите static-токен только на сервере; клиентский OAuth + PKCE — в roadmap, пока недоступен.

Использование​

В каждом запросе к bot-API:

curl https://api.reasonspace.ru/api/bot/spaces/{id}/voice \
  -H "Authorization: Bot bot_8c4f9a1b3d2e7f6a5c9b8d3e7f2a1c4b9e6d2f8a3c1b5e7d"

Verify на сервере (~1µs):

  • Extract first 12 chars → lookup row через partial-unique index
  • HMAC-SHA256 от всего токена (keyed-MAC на bot_token_secret), сравнение constant-time hmac.compare_digest со stored hash

Ротация​

При ротации старый token инвалидируется немедленно. Новый plaintext возвращается один раз. Если развёрнуто несколько инстансов со старым токеном — все они потеряют доступ одновременно.

curl -X POST https://api.reasonspace.ru/api/bots/{bot_user_id}/tokens/rotate \
  -H "Authorization: Bearer <owner_jwt>"

# Response:
{
  "token": "bot_xxxx...",     # новый plaintext (ОДИН РАЗ)
  "token_prefix": "bot_xxxx"  # видимый prefix (для UI/logs)
}

Security​

Хранение

Только в env-переменных. .env файлы в .gitignore. Для cloud deployments — Vault / AWS Secrets Manager / GCP Secret Manager.

Передача

Только HTTPS. Bot SDK добавляет Authorization header автоматически — не логируйте raw HTTP requests.

Logs

SDK не логирует raw-токен — он передаётся только в заголовке Authorization. При написании собственного клиента никогда не пишите полный токен в логи; если нужно отобразить — показывайте только префикс вида bot_xxxx….

Что делать при утечке

Если токен утёк (попал в публичный репозиторий, лог, скриншот) — немедленно ротируйте его: POST /api/bots/{bot_user_id}/tokens/rotate. Старый токен инвалидируется сразу. Автоматического отзыва по GitHub Secret Scanning платформа пока не выполняет — отслеживайте утечки на своей стороне. См. Privacy.

Limits​

Один active token на бота. При ротации старый сразу revoked. Если нужно несколько одновременно работающих instances — используйте один static token и при ротации вручную обновляйте BOT_TOKEN в окружении всех инстансов с их перезапуском (на 401 SDK бросает BotAPIError — автоматического восстановления и реакции на ротацию нет). Отдельный access-token на установку через OAuth — в roadmap, пока не реализован.