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

/**

  • @fileoverview Авторизация Bot Manager API (/api/bot/* + PAT bot_manager)
  • Как Studio управляется из Telegram-бота без дыры «любой telegram_id в query».
  • Контракт API: docs/api/bot.md (генерация через npm run docs:api). */

Bot Manager API: PAT и actor

Зачем​

Шаблон Bot Manager управляет проектами Studio из Telegram: список проектов, токены, пользователи, импорт.

Раньше хендлеры /api/bot/* часто брали личность из query telegram_id — это было удобно боту, но небезопасно: любой залогиненный мог подставить чужой id.

Теперь личность всегда из сессии или Bearer PAT, а telegram_id — только «от чьего имени», с жёсткими правилами.

Модель доступа​

Кто звонитActor (от чьего имени действие)
Session cookie connect.sidreq.user.id. Query telegram_id, если есть, обязан совпасть, иначе 403
Обычный PAT (read / read,write)То же: только свой id
PAT со scope bot_managerQuery telegram_id обязателен и становится actor (impersonation для Bot Manager)

Без session/PAT → 401.
Доступ к проекту/токену проверяется уже для actor (hasProjectAccess).

Как настроить Bot Manager​

  1. Создать PAT со scope bot_manager (в development может любой залогиненный; в production — только id из BOT_MANAGER_ADMIN_IDS):
curl -s -X POST http://localhost:5000/api/agent-tokens -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"label":"bot-manager","scopes":"read,write,bot_manager"}'

Сохранить секрет mcp_… (показывается один раз).

  1. На сервере Studio в .env:
STUDIO_BOT_MANAGER_TOKEN=mcp_...
# production:
# BOT_MANAGER_ADMIN_IDS=123456789
  1. В env бота Bot Manager (карточка токена → переменные):
STUDIO_BOT_MANAGER_TOKEN=${{STUDIO_BOT_MANAGER_TOKEN}}

${{…}} подставляется из whitelist серверных ключей при генерации .env бота (ALLOWED_SERVER_ENV_KEYS).

  1. Перезапустить бота. HTTP-ноды шаблона шлют:
Authorization: Bearer {STUDIO_BOT_MANAGER_TOKEN}

и ?telegram_id={user_id} из апдейта Telegram.

UI Studio​

Часть UI всё ещё ходит в /api/bot/... (import проекта, collaborators) с cookie и своим telegram_id — это ок: actor = залогиненный пользователь.

Env-секреты в UI — через /api/projects/.../env-variables, не через /api/bot/.../env.

Связанные файлы​

ЧтоГде
Middleware actorserver/middleware/bot-api-actor.ts
Маршруты /api/bot/*server/routes/setupUserProjectAndTokenRoutes.ts
Шаблонserver/templates/bot-manager.json
OpenAPIdocs/api/bot.md, тег bot
Тестыserver/middleware/bot-api-actor.test.ts

См. также​