EvoBGP/docs/access.md

Предоставление доступа

Как выдавать доступ к control plane API, веб-клиентам и репликам BIRD (evobgp-node). Секреты храните в менеджере секретов, переменных окружения оркестратора или зашифрованных файлах — не коммитьте реальные ключи в Git.

API-ключи (EVOBGP_API_KEYS)

Формат переменной окружения: список записей через запятую без пробелов внутри логики парсера (пробелы вокруг записей допускаются при обрезке). Каждая запись:

<token>|<tenant_id>|<role>

• token — произвольная строка, передаётся клиентом как Authorization: Bearer <token>.
• tenant_id — идентификатор арендатора; все операции store привязываются к этому tenant для данного ключа.
• role — одна из ролей ниже (регистр для проверки уровня в коде приводится к lower case).

Пример для двух ключей одного tenant:

opkey|01ARZ3NDEKTSV4RRFFQ69G5FAV|operator,nodekey|01ARZ3NDEKTSV4RRFFQ69G5FAV|node

При включённом демо-сиде сервер при старте может вывести в лог готовую подсказку с реальным tenant_id из БД — см. лог evobgp-api / evobgp-all.

Роли

Роль	Уровень	Назначение
viewer	1	Только чтение (списки, GET сущностей) там, где это разрешено политикой обработчиков.
editor	2	Чтение + создание/изменение CRUD (модули, записи, peers и т.д.), без опасных операций уровня оператора.
operator	3	Полный операторский доступ: apply, rollback, настройки, отмена задач и т.п. (как задано в handlers).
node	отдельная	Только API для реплики: latest revision, скачивание бандла, enroll. Роль node запрещена для обычного CRUD — ответ 403 Forbidden.

Обратное ограничение: для эндпоинтов ноды требуется именно роль node; остальные роли получают отказ.

Режим разработки EVOBGP_DEV_INSECURE

Если установлено EVOBGP_DEV_INSECURE=1 и в store доступен демо-tenant (DemoIDs), то запрос с заголовком Authorization: Bearer dev получает контекст operator для этого tenant.

Запрещено в продакшене: любой, кто знает заголовок, получает полные права оператора на демо-данные. В reference Compose (deploy/compose/docker-compose.yaml) флаг включён только для локальной разработки.

Синхронные «тяжёлые» GET (control plane)

• POST /v1/modules/{module_id}/cdn-sources/preview — загрузка CDN в том же HTTP-запросе (лимит тела ~8 MiB, см. OpenAPI).
• GET /v1/bird/status (если маршрут включён в деплое) — опрос локального birdc, таймаут сервера ~12 с.

Детерминированный ключ подписи бандлов (тесты)

EVOBGP_BUNDLE_SEED_HEX — необязательная hex-строка для инициализации ключа подписи бандлов (удобно в CI и локальных прогонах). В проде обычно используется случайная генерация при старте, если seed не задан.

Публичный ключ бандла для нод

При старте API в лог печатается строка bundle signing public key (base64). Её нужно передать администратору реплики и использовать в evobgp-node:

evobgp-node verify-bundle -f bundle.tar.gz -pubkey-base64 "<из_лога_API>"
evobgp-node apply-bundle -f bundle.tar.gz -extract-dir /path/to/dir -pubkey-base64 "<...>"

Команда pull-bundle использует тот же Bearer-токен, что зарегистрирован с ролью node:

evobgp-node pull-bundle -base-url http://control.example:8080 -token "<node_token>" -speaker-id "<uuid>"

CORS для веб-интерфейса

Браузерные запросы с другого origin требуют заголовков CORS на API. Задайте список разрешённых origin через EVOBGP_CORS_ORIGINS (через запятую), например:

http://localhost:5173,http://127.0.0.1:5173,https://ui.example.com

Разрешённые заголовки включают Authorization, Content-Type, Idempotency-Key, Accept, X-Tenant-Id (см. internal/httpapi/cors.go).

Заголовок X-Tenant-Id (спецификация vs реализация)

В openapi.yaml описано использование X-Tenant-Id для супер-ролей при работе от имени разных арендаторов. В текущем коде после аутентификации tenant берётся только из записи API-ключа; заголовок X-Tenant-Id не переопределяет tenant в обработчиках. До появления поддержки в коде не рассчитывайте на переключение tenant через этот заголовок.

Доступ к репозиторию и CI

Чтобы коллега мог читать код, открывать PR и видеть результаты Gitea Actions:

• Выдайте права на репозиторий в вашей forge (Gitea/GitHub/GitLab): как минимум Read для просмотра, Write для веток и PR.
• Требования к runner и описание workflow — .gitea/README.md.

Секреты для публикации образов или внешних сервисов в базовом CI не обязательны; добавляйте их отдельно под свои workflow.

Краткая матрица (ориентир)

Действие	viewer	editor	operator	node
GET модули, ревизии, peers, speakers	да	да	да	нет
POST/PATCH/DELETE CRUD сущностей	нет	да	да	нет
apply, rollback, PATCH settings	нет	нет	да	нет
bundle, latest revision, enroll	нет	нет	нет	да

Точные проверки по каждому маршруту — в коде internal/httpapi и в схеме безопасности операций в OpenAPI.

Связанные документы

• api.md — список групп эндпоинтов.
• quickstart.md — запуск с примером ключей.