Управление операторами

Операторы Soul Stack — это Архонты (Archon): люди и сервисные идентичности, которые управляют кластером через Operator API (REST/HTTP, MCP, web-UI). Этот раздел — эксплуатационный справочник по тому, как устроена их идентичность, права и видимость. Он дополняет модель безопасности из раздела Безопасность: там — как операторы доказывают, кто они; здесь — что им разрешено и что они видят.

Архонт и AID

Каждый оператор — это запись в реестре operators в PostgreSQL. Идентификатор оператора — AID (Archon ID): устойчивая строка, под которой он фигурирует в аудит-журнале и в привязках ролей.

AID — произвольная строка из ограниченного безопасного набора символов: ^[a-z0-9][a-z0-9._@-]{1,127}$ (начинается с буквы или цифры; далее строчные ASCII-буквы, цифры и . _ @ -; длина 2–128). Подходят, например, archon-alice, alice@corp.com, uid-4815, ops-team.
Набор символов выбран так, чтобы AID было безопасно встраивать в имена файлов, JWT-claims, логи и SQL: нет / и \ (path-traversal), только ASCII-lowercase (нет unicode-двойников и неоднозначности регистра), нет управляющих символов и кавычек.
Благодаря этому AID может напрямую вмещать внешнее identity-имя (например alice@corp.com или uid-4815) без искусственной обёртки.

Подробнее о жизненном цикле Архонта — Архонты.

Аутентификация — JWT

Оператор предъявляет Operator API подписанный JWT:

заголовок Authorization: Bearer <jwt> на каждом HTTP/MCP-вызове;
ключ подписи живёт в Vault (на стороне Keeper-а), сам токен ничего не открывает без проверки подписи;
по sub-claim Keeper извлекает AID и далее проверяет права этого Архонта.

Токены имеют ограниченный TTL (auth.jwt.ttl_default). Короткий срок жизни — основа модели отзыва: ревокация Архонта означает, что новых токенов ему не выпустят, а действующий перестанет работать с истечением TTL. Дополнительно отзыв распространяется по кластеру через тот же механизм, что и изменения ролей, — отозванный оператор перестаёт проходить проверку практически сразу.

Роли и permissions

Права оператора задаются не на нём напрямую, а через роли. Роль — это именованный набор permissions (конкретных разрешённых действий) плюс необязательный scope-селектор. Оператор получает права, будучи привязанным к одной или нескольким ролям.

Permission — это либо * (полный доступ, эквивалент роли cluster-admin), либо строка вида <resource>.<action> (incarnation.create, soul.list, role.grant-operator) с необязательным фильтром по covens, хостам, сервисам и т.п.
У оператора может быть несколько ролей; права складываются (OR): действие разрешено, если его покрывает хотя бы одна роль.
Полный список доступных permissions — динамический каталог backend-а, не зашитая в документацию таблица. Web-UI и инструменты подтягивают его из API. Механика ролей и привязок — Роли и доступ.

Default-deny

Базовая политика авторизации — deny по умолчанию, без исключений: любое действие, которое не покрыто явной allow-permission, запрещено. Не существует «всё открыто, кроме перечисленного» — модель строится только из разрешений.

Из этого следуют два инварианта, важных для безопасной эксплуатации:

Нельзя выдать право шире собственного (least-privilege). Оператор, создавая или раздавая роли, не может включить в них permission, которого нет у него самого. Иначе право на «управление ролями» конвертировалось бы в любые права.
Нельзя оставить кластер без администратора (защита от self-lockout). Операция, которая сняла бы последнего активного оператора с полным доступом (*), отвергается с ошибкой 409 would-lock-out-cluster.

Оба инварианта работают и для прямых привязок ролей, и для привязок через группы (Synod).

С чего начать

Архонты — bootstrap первого оператора, создание следующих, ревокация, инвариант последнего администратора.
Роли и доступ — как устроены роли и permissions, привязка оператора к роли, динамический каталог прав.
Synod и Purview — группы операторов (Synod) и scoped-видимость душ (Purview).

Как операторы доказывают свою идентичность (JWT, ключ подписи в Vault) — раздел Безопасность → Идентичность.